使用PNS(Push Notification Service)

ONE store為開發者提供兩種Push Notification Service。

• 第一種是PNS(Payment Notification Service，支付通知服務)，當發生In-App商品支付或取消支付時，ONE store向開發公司伺服器發送通知。

• 第二種是SNS（Subscription Notifacation Service，訂閱通知服務），在訂閱狀態發生變化時向開發公司伺服器發送通知。

• 由於notification可能因發送/接收伺服器的狀態而延遲或丟失，因此不建議以接收notification為準提供App商品(服務)。

• 如果您想以伺服器到伺服器方式確認是否正常付款，我们建議您使用相關伺服器API進行查詢，而不是使用PNS notification。

• ONE store可能會進行付款測試以便驗證和監控，在付款/取消付款時，這些測試也會收到同樣的notification。ONE store的付款測試歷史紀錄會定期由ONE store自行取消。

設置PNS接收伺服器URL

您可以通過點擊"開發者中心>Apps>App商品選擇>In-App資訊"選單中的"管理PNS"按鈕來設置接收PNS的開發公司伺服器的URL。

URL可以分別設置Sandbox(開發用)支付環境和商用(包括商用测试)支付環境，如果開發用/商用伺服器相同，則輸入相同的URL即可。

PNS詳細資訊

由於2025年3月20日開發者中心的改版，PNS 3.1.0版本已新增。

• packageName參數已更改為clientId，對於3.0.0及以下版本，沒有任何更改

Payment Notification消息發送規格(ONE store→開發公司伺服器)

• URI : 在開發者中心設置的 Payment Notification URL

• Method : POST

• Request Parameters : N/A

• Request Header

  Parameter Name	Data Type	Description
  Content-Type	String	application/json

• Request Body : JSON格式

  Element Name	Data Type	Description
  msgVersion	String	消息版本 開發(Sandbox) : 3.1.0D 商用(商用測試) : 3.1.0
  clientId	String	應用軟件的Client ID
  productId	String	In-App商品的商品ID
  messageType	String	SINGLE_PAYMENT_TRANSACTION 固定
  purchaseId	String	購買ID
  developerPayload	String	由開發公司管理以標示購買件的標示符
  purchaseTimeMillis	Long	在ONE store支付系统中完成支付的時間(ms)
  purcahseState	String	COMPLETED : 已支付 / CANCELED : 取消
  price	String	支付金額
  priceCurrencyCode	String	支付金額貨幣代碼(KRW, USD, ...)
  productName	String	請求購買時，如開發公司設置了customized In-App商品標題則傳達
  paymentTypeList	List	支付資訊列表
  	paymentMethod	String
  	amount	String
  billingKey	String	用於擴展的付款密鑰
  isTestMdn	Boolean	是否是測試機(true : 測試機, false : 非測試機)
  purchaseToken	String	購買token
  environment	String	支付環境 開發(SANDBOX) : SANDBOX 商用 :COMMERCIAL
  marketCode	String	市場分類編碼 ( MKT_ONE : ONE store, MKT_GLB : Global ONE store)
  signature	String	此消息的signature

• Example

{
	"msgVersion" : "3.1.0"
	"clientId":"0000000001",
	"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..."
}

paymentMethod(ONE store支付方式)定義

paymentMethod	支付方式名稱	說明
DCB	手機支付	在運營商費用帳單上以"資訊使用費"项目收取
PHONEBILL	手機小額支付	在運營商費用帳單以"小額支付"項目收取
ONEPAY	ONE pay	ONE store提供的簡易付款
CREDITCARD	信用卡	一般信用卡支付
11PAY	11Pay	SK Plannet提供的信用卡便捷支付
NAVERPAY	N pay	Naver提供的Naver pay支付
CULTURELAND	Culture cash	韓國文化振興提供的Culture cash支付
TELCOMEMBERSHIP	通訊公司會員	通訊公司提供的會員付款
OCB	OK cashbag	SK Plannet提供的OK cashbag支付
POINT	ONE store point	ONE store point支付
ONESTORECASH	ONE store cash	ONE store cash支付
COUPON	ONE store coupon	ONE store coupon支付
EWALLET	e-Wallet	e-Wallet支付
BANKACCT	銀行帳戶支付	一般銀行帳戶支付
PAYPAL	PAYPAL	paypal支付
MYCARD	My card	智冠科技提供的MY CARD付款

Signatue驗證方法

使用下面的代碼，您可以檢查signature是否偽造。

• 代碼中的 PublicKey 指的是「許可證管理」菜單中提供的許可證密鑰。

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 {
        // 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));
    }
}

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()))

Subscription Notification消息發送規格(ONE store → 開發公司伺服器)

• URI : 在開發者中心設置的Subscription Notification URL

• Method : POST

• Request Parameters : N/A

• Request Header

  Parameter Name	Data Type	Description
  Content-Type	String	application/json

• Request Body : JSON格式

  Element Name	Data Type	Description
  msgVersion	String	消息版本 開發(Sandbox) : 3.1.0D 商用(商用测測試) : 3.1.0
  clientId	String	應用軟件的Client ID
  eventTimeMillis	Long	event發生時間
  subscriptionNotification	Object	支付資訊目錄
  version	String	訂閱提醒消息版本
  notificationType	Integer	訂閱狀態
  purchaseToken	String	购买Token
  productId	String	In-App商品的商品ID
  environment	String	支付環境 · 開發(Sandbox) : SANDBOX · 商用 :COMMERCIAL
  marketCode	String	市場分類代碼 ( MKT_ONE )

• Example

{
    "msgVersion":"3.1.0",
    "clientId":"0000000001",
    "eventTimeMillis":24431212233000,
    "subscriptionNotification": {
        "version": "1",
        "notificationType" : 1,
        "purchaseToken":"TOKEN",
        "productId": "com.product.id"
    },
    "environmenmt": "COMMERCIAL",
    "marketCode": "MKT_ONE"
}

訂閱狀態定義

訂閱狀態	訂閱代碼	说明
1	SUBSCRIPTION_RECOVERED	定期支付已從保留狀態恢復。
2	SUBSCRIPTION_RENEWED	已更新定期支付。
3	SUBSCRIPTION_CANCELED	客戶要求解除定期支付。
4	SUBSCRIPTION_PURCHASED	您購買了新的定期支付商品。
5	SUBSCRIPTION_ON_HOLD	由於支付失敗，定期支付處於保留狀態。
6	SUBSCRIPTION_IN_GRACE_PERIOD	由於支付失敗，定期支付處於延期狀態。
7	SUBSCRIPTION_RESTARTED	客戶取消了解除定期支付的要求。
8	SUBSCRIPTION_PRICE_CHANGE_CONFIRMED	用戶同意变更定期支付的價格。
9	SUBSCRIPTION_DEFERRED	已延长定期支付的使用期限。
10	SUBSCRIPTION_PAUSED	已暫停定期支付。
11	SUBSCRIPTION_PAUSE_SCHEDULE_CHANGED	已变更暂停定期支付的日程。
12	SUBSCRIPTION_REVOKED	已立即解除定期支付。
13	SUBSCRIPTION_EXPIRED	定期支付已到期。

Notification傳輸方法

ONE store中的PNS伺服器通過HTTP(S)請求向開發公司伺服器發送notification。

此时，開發公司伺服器应以200回應HTTP Status Code，表示已正常接收notification。

如果由於網絡延遲而丢失，或者由於開發公司伺服器的異常情况，HTTP Status Code未能以200進行回應，PNS伺服器將認為notification傳輸失敗，並在3天内最多执行30次重傳。

Notification的重傳是在具有一定delay後執行，如下例所示，當重試次數增多時，delay會逐渐增加。 Example

次数	delay (秒)	重傳时间
0 (首次)	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
...	...	...