Using PNS (Push Notification Service)

Overview

ONE store provides two Push Notification Services for developers.

  • If the transaction of in-app product billing or billing cancellation occurs, ONE store provides PNS (payment notification service), which sends a notification to the developer's server.

  • An SNS (Subscription Notification Service) that sends notifications to the developer server when the subscription status changes

Please note:

  • The notification might be delayed or lost depending on the status of transmitting/receiving servers, and therefore it is not recommended that you provide in-app (services) based on the reception of the notification.

  • If you want to identify whether the purchase is valid through server-to-server, it is recommended to search with the related server API instead of using PNS notifications.

  • ONE store can perform the billing test for the purpose of reviewing and monitoring, and in addition, the notification will be sent when the billing/billing cancellation is performed in the billing test. The history of the billing test performed by ONE store will be periodically canceled by ONE store.

Set Up PNS Receiving Server URL

You can set the URL of the developer's server to receive PNS by clicking on the 'Manage PNS' button on the 'Developer Center > Apps > Select In-Apps > In-App' menu.

The URL can set up the Sandbox (for development) and commercial (including commercial test) test environments respectively, and if the development/commercial servers are the same, enter the same URL.

PNS Details

Specifications for Sending Payment Notification Messages (ONE store → Developer Server)

  • URI: Payment Notification URL set up by the Developer Center

  • Method: POST

  • Request Parameters: N/A

  • Request Header:

    Parameter Name

    Data Type

    Description

    Content-Type

    String

    application/json

  • Request Body: JSON format

    Element Name

    Data Type

    Description

    msgVersion

    String

    Message version

    • Development (Sandbox): 3.0.0D

    • Commercial (commercial test): 3.0.0

    packageName

    String

    Package name of the app

    productId

    String

    In-app ID

    messageType

    String

    Fix SINGLE_PAYMENT_TRANSACTION

    purchaseId

    String

    Purchase ID

    developerPayload

    String

    Identifier managed by the developer to identify purchases

    purchaseTimeMillis

    Long

    Time (ms) when the billing is completed in ONE store billing system

    purcahseState

    String

    COMPLETED: billing completed CANCELED: canceled

    price

    String

    Payment amount

    priceCurrencyCode

    String

    Currency code for payment amount (KRW, USD, ...)

    productName

    String

    It is transmitted when the developer sets up the customized in-app title at the time of purchase request

    paymentTypeList

    List

    List of payment information

    paymentMethod

    String

    Payment method (for details, refer to the definition of paymentMethod)

    amount

    String

    Amount per payment method

    billingKey

    String

    Billing key for extended function

    isTestMdn

    Boolean

    Test phone or not(true: test phone, false: not test phone)

    purchaseToken

    String

    Purchase token

    environment

    String

    Test environment

    • Development (Sandbox): SANDBOX

    • Commercial:COMMERCIAL

    marketCode

    String

    Market identification code (MKT_ONE: ONE store, MKT_GLB: Global ONE store)

    signature

    String

    Signature for this message

  • Example

{
	"msgVersion" : "3.0.0"
	"packageName":"com.onestore.pns",
	"productId":"0900001234",
	"messageType":"SINGLE_PAYMENT_TRANSACTION",
	"purchaseId":"SANDBOX3000000004564",
	"developerPayload":"OS_000211234",
	"purchaseTimeMillis":24431212233,
	"purchaseState":"COMPLETED",
	"price":"10000",
	"priceCurrencyCode":"KRW"
	"productName":"GOLD100(+20)"
	"paymentTypeList":[
		{
			"paymentMethod":"DCB",
			"amount":"3000"
		},
		{
			"paymentMethod":"ONESTORECASH",
			"amount":"7000"
		}
	],
	"billingKey" : "36FED4C6E4AC9E29ADAF356057DB98B5CB92126B1D52E8757701E3A261AF49CCFBFC49F5FEF6E277A7A10E9076B523D839E9D84CE9225498155C5065529E22F5",
	"isTestMdn" : true,
	"purchaseToken" : "TOKEN...",
	"environment" : "SANDBOX",
	"marketCode" : "MKT_ONE"
	"signature" "SIGNATURE..."
}

Definition of paymentMethod (ONE store payment method)

paymentMethod

Payment method name

Description

DCB

Mobile phone payment

Charged as the 'information use fee' item in the telecommunication bill by mobile carriers

PHONEBILL

Mobile phone micropayment

Charged as the 'micropayment' item in the telecommunication bill by mobile carriers

ONEPAY

ONE pay

Easy pay provided by ONE store

CREDITCARD

Credit card

Typical credit card payment

11PAY

11Pay

Simple mobile phone payment provided by SK planet

NAVERPAY

N pay

Naver pay's payment provided by Naver

CULTURELAND

Culture cash

Culture cash payment provided by Korea Culture Promotion Inc.

TELCOMEMBERSHIP

Mobile carrier membership

Membership payment provided by the mobile carrier

OCB

OK cashbag

OK cashback payment provided by SK planet

ONESTORECASH

ONE store cash

ONE store cash payment

COUPON

ONE store coupon

ONE store coupon payment

EWALLET

e-Wallet

e-Wallet Payment

BANKACCT

Account Payment

Regular Account Payment

PAYPAL

Paypal

Payment provided by PayPal

MYCARD

My Card

Payment with MyCard provided by Soft World

How to review the signature

You can check whether the signature has been forced or falsified by using the code below.

  • PublicKey within the code indicates the license key provided on 'Developer Center > In-App > Credentials'. For details on the license key, refer to "Check License Key (public key) & OAuthCredentials" within the Pre-preparations page.

import java.security.PublicKey;
   
import org.apache.commons.codec.binary.Base64;
import org.codehaus.jackson.JsonNode;
import org.codehaus.jackson.map.ObjectMapper;
import org.codehaus.jackson.node.ObjectNode;
   
   
public class SignatureVerifier {
   
    private static final String SIGN_ALGORITHM = "SHA512withRSA";
    private ObjectMapper mapper = new ObjectMapper();
   
   
    boolean verify(String rawMsg, PublicKey key) throws Exception {
        // JSON 메시지에서 signature를 추출한다.
        JsonNode root = mapper.readTree(rawMsg);
        String signature = root.get("signature").getValueAsText();
        ((ObjectNode)root).remove("signature");
          
        // 추출한 signature가 올바른 값인지 검증한다.
        Signature sign = Signature.getInstance(SIGN_ALGORITHM);
        sign.initVerify(key);
        sign.update(root.toString().getBytes("UTF-8"));
        return sign.verify(Base64.decodeBase64(signature));
    }
}

Specifications for Sending Subscription Notification Messages (ONE store → Developer Server)

  • URI: Subscription Notification URL set up by the Developer Center

  • Method: POST

  • Request Parameters: N/A

  • Request Header:

    Parameter Name

    Data Type

    Description

    Content-Type

    String

    application/json

  • Request Body: JSON format

    Element Name

    Data Type

    Description

    msgVersion

    String

    Message version

    • Development (Sandbox): 3.0.0D

    • Commercial (commercial test): 3.0.0|

    packageName

    String

    Package name of the app

    eventTimeMillis

    Long

    Time when event occurs

    subscriptionNotification

    Object

    List of payment information

    version

    String

    Version of subscription alarm message

    notificationType

    Integer

    Subscription status

    purchaseToken

    String

    Purchase token

    productId

    String

    In-app ID

    environment

    String

    Test environment

    • Development (Sandbox): SANDBOX

    • Commercial:COMMERCIAL|

    marketCode

    String

    Market identification code (MKT_ONE: ONE store, MKT_STM: Storm)

  • Example

{
    "msgVersion":"3.0.0",
    "packageName":"com.onestore.pns",
    "eventTimeMillis":24431212233000,
    "subscriptionNotification": {
        "version": "1",
        "notificationType" : 1,
        "purchaseToken":"TOKEN",
        "productId": "com.product.id"
    },
    "environmenmt": "COMMERCIAL",
    "marketCode": "MKT_ONE"
}

Defining Subscription Statuses

Subscription status

Subscription Code

Description

1

SUBSCRIPTION_RECOVERED

The subscription has been recovered from its pending status.

2

SUBSCRIPTION_RENEWED

The subscription has been renewed.

3

SUBSCRIPTION_CANCELED

The user has requested to cancel the subscription.

4

SUBSCRIPTION_PURCHASED

A new subscription has been purchased.

5

SUBSCRIPTION_ON_HOLD

The subscription has been put on hold due to payment failure.

6

SUBSCRIPTION_IN_GRACE_PERIOD

The subscription has been put on a deferred status due to payment failure.

7

SUBSCRIPTION_RESTARTED

The user has canceled the request to cancel the subscription.

8

SUBSCRIPTION_PRICE_CHANGE_CONFIRMED

The user has agreed to the changes in the subscription price.

9

SUBSCRIPTION_DEFERRED

The subscription period has been deferred.

10

SUBSCRIPTION_PAUSED

The subscription has been paused.

11

SUBSCRIPTION_PAUSE_SCHEDULE_CHANGED

The "pause schedule" of the subscription has been changed.

12

SUBSCRIPTION_REVOKED

The subscription has been terminated.

13

SUBSCRIPTION_EXPIRED

The subscription has expired.

Notification Transmission Policy

ONE store's PNS server shall send notification to the developer's server through HTTP(S) requests.At this time, the developer's server must respond with the HTTP Status Code as 200 to indicate that the notification has been normally received.If the HTTP Status Code fails to be received as 200 (as the response due to the loss of notification caused by delays in the network or due to the failure in the developer's server), the PNS server determines that the notification transmission has failed, and thereby will perform up to 30 rounds of retransmission during 3 days.The retransmission of the notification will be performed after certain delays as seen in the example below, and more retransmission rounds will lead to more delays.

Example

Round

Delay(seconds)

Retransmission Time

0 (first)

0

2020-05-17 13:10:00

1

30

2020-05-17 13:10:30

2

120

2020-05-17 13:12:30

3

270

2020-05-17 13:17:00

4

480

2020-05-17 13:25:00

...

...

...

Last updated