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

Notice According to the ONE webshop security policy, only the HTTPS protocol and port 443 are supported. Using any other configuration may result in improper operation.

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

HTTP TYPE : HTTPS

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

<?php
function formatPublicKey($publicKey) {
 $BEGIN= "-----BEGIN PUBLIC KEY-----";
 $END = "-----END PUBLIC KEY-----";
  
 $pem = $BEGIN . "\n";
 $pem .= chunk_split($publicKey, 64, "\n");
 $pem .= $END . "\n";
  
 return $pem;
}
  
function formatSignature($signature) {
 return base64_decode(chunk_split($signature, 64, "\n"));
}
  
// Sample message
$sampleMessage = '{"msgVersion":"3.1.0D","purchaseId":"SANDBOX3000000004564","developerPayload":"OS_000211234","clientId":"0000000001","productId":"0900001234","messageType":"SINGLE_PAYMENT_TRANSACTION","purchaseMillis":24431212233,"purchaseState":"COMPLETED","price":20000,"productName":"한글은?GOLD100(+20)","paymentTypeList":[{"paymentMethod":"DCB","amount":3000},{"paymentMethod":"ONESTORECASH","amount":7000}],"billingKey":"36FED4C6E4AC9E29ADAF356057DB98B5CB92126B1D52E8757701E3A261AF49CCFBFC49F5FEF6E277A7A10E9076B523D839E9D84CE9225498155C5065529E22F5","isTestMdn":true,"signature":"MNxIl32ws+yYWpUr7om+jail4UQxBUXdNX5yw5PJKlqW2lurfvhiqF0p4XWa+fmyV6+Ot63w763Gnx2+7Zp2Wgl73TWru5kksBjqVJ3XqyjUHDDaF80aq0KvoQdLAHfKze34cJXKR/Qu8dPHK65PDH/Vu6MvPVRB8TvCJpkQrqg="}';
  
// Sample public key
$publicKey = "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDMzpWJoK1GSOrr4juma5+sREYjdCW8/xSd9+6z6PAkUH5af97wy8ecfkLtP9LK5VskryfDlcOjfu0BgmHYntAqKT7B4KWk8jWbJ8VHUpp30H95UbcnCRFDqpEtwYzNA5gNMYKtAdbL41K8Fbum0Xqxo65pPEI4UC3MAG96O7X1WQIDAQAB";
  
  
// Parse JSON message
$jsonArr = json_decode($sampleMessage, true);
  
// Extract and remove signature
$signature = $jsonArr["signature"];
unset($jsonArr["signature"]);
$originalMessage = json_encode($jsonArr, JSON_UNESCAPED_UNICODE);
  
// Veify
$formattedKey = formatPublicKey($publicKey);
$formattedSign = formatSignature($signature);
$hash_algorithm = 'sha512';
  
$success = openssl_verify($originalMessage, $formattedSign, $formattedKey, $hash_algorithm);
if ($success == 1) {
 echo "verified";
}
else {
 echo "unverified";
}
?>

Python

# -*- coding: utf-8 -*-
  
import json
from base64 import b64decode
from collections import OrderedDict
  
from Crypto.Hash import SHA512
from Crypto.PublicKey import RSA
from Crypto.Signature import PKCS1_v1_5
  
import sys
reload(sys)
sys.setdefaultencoding('utf-8')
  
hash = "SHA-512"
  
  
def verify(message, signature, pub_key):
    signer = PKCS1_v1_5.new(pub_key)
    digest = SHA512.new()
    digest.update(message)
    return signer.verify(digest, signature)
  
  
jsonData = json.loads(rawMsg, encoding='utf-8', object_pairs_hook=OrderedDict)
signature = jsonData['signature']
del jsonData['signature']
originalMessage = json.dumps(jsonData, ensure_ascii=False, encoding='utf-8', separators=(',', ':'))
  
RSA.importKey(publickey).publickey()
print(verify(originalMessage, b64decode(signature), RSA.importKey(publickey).publickey()))

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.

You can retrieve purchases with unprocessed confirmation using the getUnconfirmedPurchases API.

We recommend using this API to ensure stable payment processing.

• For details, refer to the getUnconfirmedPurchases documentation.

2.1 consumePurchase

Path	(Commercial) https://iap-apis.onestore.net/v7/apps/{clientId}/purchases/inapp/products/{productId}/{purchaseToken}/consume (Development) https://sbpp.onestore.net/v7/apps/{clientId}/purchases/inapp/products/{productId}/{purchaseToken}/consume
Description	Changes the state of the purchased managed in-app product to consumed. (Only applicable to consumable products.) After processing, the user can repurchase the same item. Error Code: Refer to the Standard response codes

• Method : POST

• Request Parameter : Path Variable format

  • String clientId : Client ID of the app that calls API (Data Size : 128)

  • String productId : Product ID (Data Size : 150)

  • String purchaseToken : Purchase token (Data Size : 20)

• Request Header:

  Parameter Name	Data Type	Required	Description
  Authorization	String	true	The access_token issued through the Access Token API
  Content-Type	String	true	application/json
  x-market-code	String	false	Market classification code

• Example

  Request.setHeader("Authorization", "Bearer 680b3621-1234-1234-1234-8adfaef561b4");
  Request.setHeader("Content-Type", "application/json");
  Request.setHeader("x-market-code", "MKT_ONE");

• Request Body : JSON 형식

  Element Name	Data Type	Required	Description
  developerPayload	String	false

• Example :

  {
      "developerPayload": "your payload"
  }

• Response Body : JSON Format

  The response is returned in the following format to allow for a more intuitive determination of the process completion when API processing is successful. However, when the API processing fails, it returns the standard error response.

  Element Name	Data Type	Data Size	Description
  code	String	-	Response code
  message	String	-	Response message
  result	Object	-

• Example :

  HTTP/1.1 200 OK
  Content-type: application/json;charset=UTF-8
  {
      "result" : {
          "code" : "Success",
          "message" : "Request has been completed successfully."
      }
  }

2.2 acknowledgePurchase

Path	(Commercial) https://iap-apis.onestore.net/v7/apps/{clientId}/purchases/all/products/{productId}/{purchaseToken}/acknowledge (Development) https://sbpp.onestore.net/v7/apps/{clientId}/purchases/all/products/{productId}/{purchaseToken}/acknowledge
Description	Changes the purchased in-app product to the purchase confirmation status. (Supported for both consumable and subscription products.) After processing, the user cannot repurchase the same item. Error Code: Refer to the Standard response codes

• Method : POST

• Request Parameter : Path Variable format

  • String clientId : Client ID of the app that calls API (Data Size : 128)

  • String productId : Product ID (Data Size : 150)

  • String purchaseToken : Purchase token (Data Size : 20)

• Request Header:

  Parameter Name	Data Type	Required	Description
  Authorization	String	true	The access_token issued through the Access Token API
  Content-Type	String	true	application/json
  x-market-code	String	false	Market classification code

• Example

  Request.setHeader("Authorization", "Bearer 680b3621-1234-1234-1234-8adfaef561b4");
  Request.setHeader("Content-Type", "application/json");
  Request.setHeader("x-market-code", "MKT_ONE");

• Request Body : JSON 형식

  Element Name	Data Type	Required	Description
  developerPayload	String	false

• Example :

  {
      "developerPayload": "your payload"
  }

• Response Body : JSON format The response is returned in the following format to allow for a more intuitive determination of the process completion when API processing is successful. However, when the API processing fails, it returns the standard error response.

  Element Name	Data Type	Data Size	Description
  code	String	-	Response code
  message	String	-	Response message
  result	Object	-

• Example :

  HTTP/1.1 200 OK
  Content-type: application/json;charset=UTF-8
  {
      "result" : {
          "code" : "Success",
          "message" : "Request has been completed successfully."
      }
  }