Webshop Payment Integration

To integrate ONE webshop payments, both PNS reception and Confirm Purchases must be implemented.

• PNS(Payment Notification Service)

  • When a user completes a ONE webshop item purchase, the Webshop sends the payment result and related information to the developer’s server URL via PNS.

  • Use this information to deliver the item to the user.

• Confirm Purchases

  • Notifies the ONE store server that the item has been successfully delivered to the user.

  • Depending on your purpose, use consumePurchase or acknowledgePurchase.

  • If Confirm Purchases is not completed within 3 days, the purchase is considered undelivered and is automatically canceled.

1. PNS

When a payment or cancellation occurs, ONE store sends a notification to the developer’s server.

PNS uses the same specification as In‑App Payment API V7 (Reference : Using PNS (Push Notification Service)

1.1 Configure PNS Reception Server URL

You can configure the PNS server URL in: Developer Center > Webshop > Integration Mgmt.

For detailed setup instructions, refer to the Integration Management Guide.

1.2 PNS Detailed Specifications

URI : Payment Notification URL set in the Developer Center

Method : POST

Request Parameters : N/A

Request Header :

Name	Type	Value
Content-Type	String	application/json

Request Body : JSON format

Name	Type	Description
msgVersion	String	Message version Development (Sandbox): 3.1.0D Commercial (commercial test): 3.1.0
clientId	String	Webshop Title ID
productId	String	Webshop item 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
purchaseState	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
paymentTypeList[].paymentMethod	String	Payment method (for details, refer to the definition of paymentMethod)
paymentTypeList[].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) For Webshop, the value is fixed as MKT_ONE
signature	String	Signature for this message
serviceUserId	String	User's Game ID
serviceServerId	String	User's Server ID

Example

{
    "msgVersion" : "3.1.0"
    "clientId":"0999999999",
    "productId":"0900001234",
    "messageType":"SINGLE_PAYMENT_TRANSACTION",
    "purchaseId":"SANDBOX3000000004564",
    "developerPayload":"OS_000211234",
    "purchaseTimeMillis":24431212233,
    "purchaseState":"COMPLETED",
    "price":"10000",
    "priceCurrencyCode":"KRW"
    "productName":"GOLD100(+20)"
    "paymentTypeList":[
        {
            "paymentMethod":"ONEPAY",
            "amount":"3000"
        },
        {
            "paymentMethod":"ONESTORECASH",
            "amount":"7000"
        }
    ],
    "billingKey" : "36FED4C6E4AC9E29ADAF356057DB98B5CB92126B1D52E8757701E3A261AF49CCFBFC49F5FEF6E277A7A10E9076B523D839E9D84CE9225498155C5065529E22F5",
    "isTestMdn" : true,
    "purchaseToken" : "TOKEN",
    "environment" : "SANDBOX",
    "marketCode" : "MKT_ONE"
    "signature" : "ajkfl;askfjkladfjksl",
    "serviceUserId" : "user1234",
    "serviceServerId" : "server01"
}

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 payment provided by Korea Culture Promotion Inc.
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
POINT	ONE store point	ONE store point payment
TELCOMEMBERSHIP	Mobile carrier membership	Membership payment provided by the mobile carrier
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.

• The PublicKey in the code refers to the license key provided in the Developer Center > Webshop > Intergration Mgmt. > Settings for Licensing menu.

Java

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 {
        // Extract the signature from the JSON message.
        JsonNode root = mapper.readTree(rawMsg);
        String signature = root.get("signature").getValueAsText();
        ((ObjectNode)root).remove("signature");
          
        // Verify that the extracted signature is correct.
        Signature sign = Signature.getInstance(SIGN_ALGORITHM);
        sign.initVerify(key);
        sign.update(root.toString().getBytes("UTF-8"));
        return sign.verify(Base64.decodeBase64(signature));
    }
}

PHP

Python

1.3 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 (s)	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
...	...	...

2. Confirm Purchases

To ensure that items are delivered correctly, the Confirm Purchases process must be completed.

OAuth authentication is required to use ONE store Open APIs.

For details, refer to the ONE store OAuth Guide.

2.1 consumePurchase

[ API Spec. ]

Protocol	HTTPS	Method	POS
Content-Type	application/json	Response Format	application/json

Path	(Commercial) https://pcapis.onestore.net/pc/v7/apps/{clientId}/purchases/inapp/{purchaseToken}/consume (Development) https://sbpp.onestore.net/pc/v7/apps/{clientId}/purchases/inapp/{purchaseToken}/consume
Description	Changes the state of the purchased managed in-app product to consumed. (Only applicable to consumable products.) Error Code: Refer to the Standard response codes

[ Request ]

Parameter

Parameter Name	Data Type	Required	Description
clientId	String	Y	Webshop Title ID of the App Calling the API
purchaseToken	String	Y	Purchase Token

Header

Parameter Name	Data Type	Required	Description
Authorization	String	Y	User Access Token obtained through the User Access Token issuance API
x-market-code	String	N	Market classification code MKT_ONE: South Korea MKT_GLB: other than South Korea

Body

Parameter Name	Data Type	Data Size	Required	Description
developerPayload	String	200	N	An identifier managed by the developer to identify the purchase transaction

Example

POST /pc/v7/apps/com.onestorecorp.test/purchases/inapp/200406083435101108801/consume
Host: http://pcapis.onestore.net
Content-Type: application/json
Authorization: Bearer 680b3512-1253-5642-1263-8adjbf651nb
x-market-code: MKT_GLB

{
"developerPayload" : "1jkl2j3lk1lj"
}

[ Response ]

Element Name	Data Type	Data Size	Description
result	Object
{
code	String	50	Response Code (Successful Processing)
message	String	300	Response Message (Successful Processing)
}

Example

/// Success

{
    "result" : {
        "code" : "Success",
        "message" : "Request has been completed successfully."
    }
}



// Fail

{
    "error" : {
        "code" : "AlreadyPurchased",
        "message" : "You already have the product or a product that cannot be purchased together."
    }
}

2.2 acknowledgePurchase

[ API Spec. ]

Protocol	HTTPS	Method	POST
Content-Type	application/json	Response Format	application/json

Path	(Commercial) https://pcapis.onestore.net/pc/v7/apps/{clientId}/purchases/all/{purchaseToken}/acknowledge (Development) https://sbpp.onestore.net/pc/v7/apps/{clientId}/purchases/all/{purchaseToken}/acknowledge
Description	Changes the purchased in-app product to the purchase confirmation status. (Supported for both consumable and subscription products.) Error Code: Refer to the Standard response codes

[ Request ]

Parameter

Parameter	Data Type	Required	Description
clientId	String	Y	Webshop Title ID of the App Calling the API
purchaseToken	String	Y	Purchase Token

Header

Parameter Name	Data Type	Required	Description
Authorization	String	Y	User Access Token obtained through the User Access Token issuance API
x-market-code	String	N	Market classification code MKT_ONE: South Korea MKT_GLB: other than South Korea

Body

Element Name	Data Type	Data Size	Required	Description
developerPayload	String	200	N	An identifier managed by the developer to identify the purchase transaction

Example

POST /pc/v7/apps/com.onestorecorp.test/purchases/inapp/200406083435101108801/acknowledge
Host: pcapis.onestore.net
Content-Type: application/json
Authorization: Bearer 680b3512-1253-5642-1263-8adjbf651nb
x-market-code: MKT_GLB

{
"developerPayload" : "1jkl2j3lk1lj"
}

[ Response ]

Element Name	Data Type	Data Size	Description
result	Object
{
code	String	50	Response Code (Successful Processing)
message	String	300	Response Message (Successful Processing)
}

Example

// Success

{
    "result" : {
        "code" : "Success",
        "message" : "Request has been completed successfully."
    }
}



// Fail

{
    "error" : {
        "code" : "AlreadyPurchased",
        "message" : "You already have the product or a product that cannot be purchased together."
    }
}