웹샵 결제 연동

원웹샵 결제를 연동하기 위해선 PNS 수신과 구매확인 처리를 반드시 진행해야 합니다.

PNS(Payment Notification Service)
- 사용자가 원웹샵 아이템 결제가 완료되면, 결제 결과를 개발사 서버 URL로 전달합니다.
- 전달된 정보를 참고하여 사용자에게 아이템을 지급해주세요.
구매확인
- 사용자에게 아이템을 정상적으로 지급되었음을 원스토어 서버에 전달합니다.
- 목적에 따라 cosumePurchase 또는 acknowledgePurchase를 활용합니다.
- 구매확인이 3일 이내 완료되지 않으면, 아이템이 정상적으로 지급되지 않은 것으로 판단하여 해당 구매는 자동 취소됩니다.

1. PNS

아이템 결제 또는 결제취소가 발생하면 원스토어가 개발사 서버로 알림을 전송합니다.

PNS는 인앱결제 API V7과 동일한 규격으로 제공합니다. (참고. 07. PNS(Push Notification Service) 이용하기)

1.1 PNS 수신 서버 URL 설정

PNS를 수신 받을 개발사 서버의 URL은 개발자센터 > 웹샵 > 연동 관리 메뉴에서 등록할 수 있습니다.

자세한 방법은 연동 관리 가이드를 참고해주세요.

1.2 PNS 상세 규격

URI : 개발자센터에서 설정한 Payment Notification URL

Method : POST

Request Parameters : N/A

Request Header :

Name

Type

Value

Content-Type

String

application/json

Request Body : JSON 형식

Name

Type

Description

msgVersion

String

메시지 버전

개발(Sandbox) : 3.1.0D
상용(상용테스트) : 3.1.0

clientId

String

웹샵 타이틀 ID

productId

String

웹샵 아이템 ID

messageType

String

SINGLE_PAYMENT_TRANSACTION 고정

purchaseId

String

구매 ID

developerPayload

String

구매건을 식별하기 위해 개발사에서 관리하는 식별자

purchaseTimeMillis

Long

원스토어 결제 시스템에서 결제가 완료된 시간(ms)

purchaseState

String

COMPLETED : 결제완료 / CANCELED : 취소

price

String

결제 금액

priceCurrencyCode

String

결제 금액 통화코드(KRW, USD, ...)

productName

String

구매요청 시 개발사가 customized 인앱상품 제목을 설정한 경우 전달

paymentTypeList[]

List

결제 정보 목록

paymentTypeList[].paymentMethod

String

결제 수단 (상세 내용은 아래 paymentMethod 정의 참고)

paymentTypeList[].amount

String

결제 수단 별 금액

billingKey

String

확장 기능용 결제 키

isTestMdn

Boolean

시험폰 여부(true : 시험폰, false : 시험폰 아님)

purchaseToken

String

구매토큰

environment

String

결제환경

개발(샌드박스) : SANDBOX
상용 :COMMERCIAL

marketCode

String

마켓 구분코드 ( MKT_ONE : 원스토어, MKT_GLB : 원스토어 글로벌 )

웹샵의 경우, MKT_ONE 고정

signature

String

본 메시지에 대한 signature

serviceUserId

String

사용자의 게임 ID

serviceServerId

String

사용자의 서버 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"
}

paymentMethod(원스토어 결제수단) 정의

paymentMethod

결제수단 명칭

설명

DCB

휴대폰결제

통신사 요금청구서에 '정보이용료' 항목으로 청구

PHONEBILL

휴대폰 소액결제

통신사 요금청구서에 '소액결제' 항목으로 청구

ONEPAY

ONE pay

원스토어가 제공하는 간편결제

CREDITCARD

신용카드

일반 신용카드 결제

11PAY

11Pay

11번가에서 제공하는 신용카드 간편결제

NAVERPAY

N pay

네이버에서 제공하는 네이버페이 결제

CULTURELAND

컬쳐캐쉬

한국문화진흥에서 제공한는 컬쳐캐쉬 결제

OCB

OK cashbag

SK플래닛이 제공하는 OK캐쉬백 결제

ONESTORECASH

원스토어 캐쉬

원스토어 캐쉬 결제

COUPON

원스토어 쿠폰

원스토어 쿠폰 결제

POINT

원스토어 포인트

원스토어 포인트 결제

TELCOMEMBERSHIP

통신사멤버십

통신사에서 제공하는 멤버십 결제

EWALLET

e-Wallet

e-Wallet 결제

BANKACCT

계좌결제

일반 계좌결제

PAYPAL

페이팔

페이팔이 제공하는 결제

MYCARD

마이카드

소프트월드에서 제공하는 마이카드 결제

Signature 검증 방법

아래 코드를 사용하면 signature에 대한 위변조 여부를 확인할 수 있습니다.

코드 내 PublicKey는 '라이선스 관리'에서 제공되는 라이선스 키를 의미합니다.

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
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";
}
?>

# -*- 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 전송 정책

원스토어의 PNS 서버는 HTTP(S) 요청을 통하여 개발사 서버로 notification을 전송합니다.

이때 개발사 서버는 notification를 정상적으로 수신했다는 의미로 HTTP Status Code를 200으로 응답하여야 합니다.

만약 네트워크 지연으로 인한 유실 또는 개발사 서버의 비정상적인 상황으로 HTTP Status Code를 200으로 응답받지 못한 경우, PNS서버는 notification 전송이 실패했다고 판단하고 3일간 최대 30회의 재전송을 수행하게 됩니다.

notification의 재전송은 아래의 예시와 같이 일정한 delay를 가진 후 실행되며, 재시도 회수가 많아지면 delay가 점차 늘어나는 구조로 되어 있습니다.

Example

회차

delay (초)

재전송 시간

0 (최초)

2020-05-17 13:10:00

2020-05-17 13:10:30

120

2020-05-17 13:12:30

270

2020-05-17 13:17:00

480

2020-05-17 13:25:00

...

2. 구매확인

아이템이 정상적으로 지급되었음을 확인하기 위해 구매확인 처리는 반드시 진행해야 합니다.

구매확인은 원스토어 서버 Open API로 연동을 위해선 반드시 OAuth 인증이 필요합니다.

상세 가이드는 원스토어 OAuth 문서를 참고해주세요.

getUnconfirmedPurchases API를 통해 구매확인이 처리되지 않은 내역을 조회할 수 있습니다.

안정적인 결제 처리를 위해 해당 API 활용을 권장드립니다.

상세 가이드는 getUnconfirmedPurchases 문서를 참고해주세요.

2.1 consumePurchase

Path

(상용) https://iap-apis.onestore.net/v7/apps/{clientId}/purchases/inapp/products/{productId}/{purchaseToken}/consume (개발) https://sbpp.onestore.net/v7/apps/{clientId}/purchases/inapp/products/{productId}/{purchaseToken}/consume

Description

구매한 관리형 인앱 상품을 소비한 상태로 변경합니다. (소비성 상품만 사용 가능)
- 처리 후 사용자는 동일 상품을 다시 구매할 수 있습니다.
오류 코드 : 표준 응답코드 참조

Method : POST
Request Parameter : Path Variable 형식
- String clientId : API를 호출하는 앱의 클라이언트 ID (Data Size : 128)
- String productId : 상품 ID (Data Size : 150)
- String purchaseToken : 구매 토큰 (Data Size : 20)
Request Header:
Parameter Name
Data Type
Required
Description
Authorization
String
true
Access Token API를 통해 발급받은 access_token
Content-Type
String
true
application/json
x-market-code
String
false
마켓 구분 코드

Example

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

Request Body : JSON 형식
Element Name
Data Type
Required
Description
developerPayload
String
false

Example :

{
    "developerPayload": "your payload"
}

Response Body : JSON 형식
API 처리 성공 시 처리완료를 보다 직관적으로 판단할 수 있도록 아래 형식의 응답를 리턴합니다. 단, API 처리 실패 시에는 표준오류응답을 리턴합니다.
Element Name
Data Type
Data Size
Description
code
String
-
응답 코드
message
String
-
응답 메시지
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

(상용) https://iap-apis.onestore.net/v7/apps/{clientId}/purchases/all/products/{productId}/{purchaseToken}/acknowledge (개발) https://sbpp.onestore.net/v7/apps/{clientId}/purchases/all/products/{productId}/{purchaseToken}/acknowledge

Description

구매한 인앱 상품을 구매확인 상태로 변경합니다. (소멸성 상품, 월정액 상품 모두 지원)
- 처리 후 사용자는 동일 상품을 재구매할 수 없습니다.
오류 코드 : 표준 응답코드 참조

Method : POST
Request Parameter : Path Variable 형식
- String clientId : API를 호출하는 앱의 클라이언트 ID (Data Size : 128)
- String productId : 상품 ID (Data Size : 150)
- String purchaseToken : 구매 토큰 (Data Size : 20)
Request Header:
Parameter Name
Data Type
Required
Description
Authorization
String
true
Access Token API를 통해 발급받은 access_token
Content-Type
String
true
application/json
x-market-code
String
false
마켓 구분 코드

Example

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

Request Body : JSON 형식
Element Name
Data Type
Required
Description
developerPayload
String
false

Example :

{
    "developerPayload": "your payload"
}

Response Body : JSON 형식
API 처리 성공 시 처리완료를 보다 직관적으로 판단할 수 있도록 아래 형식의 응답를 리턴합니다. 단, API 처리 실패 시에는 표준오류응답을 리턴합니다.
Element Name
Data Type
Data Size
Description
code
String
-
응답 코드
message
String
-
응답 메시지
result
Object
-

Example :

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

Last updated 5 days ago

hashtag1. PNS

hashtag1.1 PNS 수신 서버 URL 설정

hashtag1.2 PNS 상세 규격

hashtagpaymentMethod(원스토어 결제수단) 정의

hashtagSignature 검증 방법

hashtag1.3 Notification 전송 정책

hashtag2. 구매확인

hashtag2.1 consumePurchase

hashtag2.2 acknowledgePurchase

1. PNS

1.1 PNS 수신 서버 URL 설정

1.2 PNS 상세 규격

paymentMethod(원스토어 결제수단) 정의

Signature 검증 방법

1.3 Notification 전송 정책

2. 구매확인

2.1 consumePurchase

2.2 acknowledgePurchase