웹샵 결제 연동

원웹샵 결제를 연동하기 위해선 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 문서를 참고해주세요.

2.1 consumePurchase

[ API Spec. ]

Protocol

HTTPS

Method

TPOSText

Content-Type

application/json

응답 포맷

application/json

Path

(상용) https://pcapis.onestore.net/pc/v7/apps/{clientId}/purchases/inapp/{purchaseToken}/consume (개발) https://sbpp.onestore.net/pc/v7/apps/{clientId}/purchases/inapp/{purchaseToken}/consume

Description

구매한 관리형 인앱 상품을 소비한 상태로 변경합니다. (소비성 상품만 사용 가능)
오류 코드 : 표준 응답코드 참조

[ Request ]

Parameter

Parameter Name

Data Type

Required

Description

clientId

String

API를 호출하는 웹샵 타이틀 ID

purchaseToken

String

구매토큰

Header

Parameter Name

Data Type

Required

Description

Authorization

String

User Access Token 발급 API를 통해 발급받은 User Access Token

x-market-code

String

마켓 구분 코드

MKT_ONE: 원스토어 (대한민국)
MKT_GLB: 원스토어 (대한민국 외)

Body

Parameter Name

Data Type

Data Size

Required

Description

developerPayload

String

200

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

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

응답코드(정상처리)

message

String

300

응답메시지(정상처리)

}

Example

/// 성공 시

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



// 실패 시

{
    "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

응답 포맷

application/json

Path

(상용) https://pcapis.onestore.net/pc/v7/apps/{clientId}/purchases/all/{purchaseToken}/acknowledge

(개발) https://sbpp.onestore.net/pc/v7/apps/{clientId}/purchases/all/{purchaseToken}/acknowledge

Description

구매한 인앱 상품을 구매확인 상태로 변경합니다. (소멸성 상품, 월정액 상품 모두 지원)
오류 코드 : 표준 응답코드 참조

[ Request ]

Parameter

Parameter

Data Type

Required

Description

clientId

String

API를 호출하는 웹샵 타이틀 ID

purchaseToken

String

구매토큰

Header

Parameter Name

Data Type

Required

Description

Authorization

String

User Access Token 발급 API를 통해 발급받은 User Access Token

x-market-code

String

마켓 구분 코드

MKT_ONE: 원스토어 (대한민국)
MKT_GLB: 원스토어 (대한민국 외)

Body

Element Name

Data Type

Data Size

Required

Description

developerPayload

String

200

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

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

응답코드(정상처리)

message

String

300

응답메시지(정상처리)

}

Example

// 성공 시

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



// 실패 시

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

Last updated 1 day ago

hashtag1. PNS

hashtag1.1 PNS 수신 서버 URL 설정

hashtag1.2 PNS 상세 규격

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

hashtagSignature 검증 방법

hashtag1.3 Notification 전송 정책

hashtag2. 구매확인

hashtag2.1 consumePurchase

hashtag[ API Spec. ]

hashtag[ Request ]

hashtag[ Response ]

hashtag2.2 acknowledgePurchase

hashtag[ API Spec. ]

hashtag[ Request ]

hashtag[ Response ]

1. PNS

1.1 PNS 수신 서버 URL 설정

1.2 PNS 상세 규격

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

Signature 검증 방법

1.3 Notification 전송 정책

2. 구매확인

2.1 consumePurchase

[ API Spec. ]

[ Request ]

[ Response ]

2.2 acknowledgePurchase

[ API Spec. ]

[ Request ]

[ Response ]