ONE store In-App支付服务器API (API V7)

概要

ONE store In-App支付服务器API是指用于查询在ONE store中支付的In-App商品的数据或变更支付状态的Open API。为了使用该API，需要进行OAuth认证。

HOST Domain

本文中使用的Host Domain如下：

ONE store环境

Host Domain

验证（开发）

https://sbpp.onestore.net

商用

https://iap-apis.onestore.net

本文中使用的域名是，国内和全球通用的域名。

仅在韩国服务的现有App/游戏的域名则保持原有的。(apis.onestore.co.kr)

市场分类

● Request header中已新增市场分类代码（x-market-code）。

● 如果在全球范围内提供服务，则必须在header中添加市场分类代码。

● 如果没有市场分类代码，会议韩国服务（默认值）来调用。

市场分类代码

服务国家

MKT_ONE

韩国

MKT_GLB

除韩国外

根据市场区分代码，服务器 API 响应提供的时间标准有所不同。

MKT_ONE : UTC+09

MKT_GLC : UTC+00

ONE store OAuth

OAuth概要

为了联动ONE store服务器Open API，需要进行OAuth认证。

ONE store OAuth V2的理解
- AccessToken是通过ONE store的Server Open API可以获得的值，在调用ONE store提供的Server Open API时作为认证value使用
- 默认情况下，AccessToken有效期为3600秒，如果有效期满或不足600秒时，可调用getAccessToken（）发放新的AccessToken。
  - 现有的AccessToken也可在有效期结束前使用。
  - 由于是多数AccessToken发行的方式，因此每个开发公司的服务instance都可以获取并使用不同的AccessToken。
一般联动流程如下

获得AccessToken的过程（1号）只需在API调用时发生认证错误时调用即可。

对于ONE store中的In-App支付服务器API的调用，可使用Authorization Bearer Scheme，调用示例如下：

GET /v7/apps/com.onestore.game.goindol/purchases/inapp/products/product01/SANDBOXT000120004476 HTTP/1.1
Host: sbpp.onestore.net
Authorization: Bearer 680b3621-1234-1234-1234-8adfaef561b4

Authorization Header与上述示例一样必须正确输入，Bearer + 空白 + AccessToken应区分大小写。 Bearer的值是通过调用getAccessToken()获得的AccessToken值。

错误示例

Authorization: 680b3621-1234-1234-1234-8adfaef561b4
Authorization: bearer 680b3621-1234-1234-1234-8adfaef561b4
Authorization: Bearer <680b3621-1234-1234-1234-8adfaef561b4>
Authorization:Bearer680b3621-1234-1234-1234-8adfaef561b4

OAuth API详情

确认client_id 及client_secret

Client_id 和 Client_secret 的值可以在“许可证管理”菜单中查看。

发放AccessToken

URI : /v7/oauth/token
Method: POST
Request Parameter: Form格式
Parameter Name
Description
Example
client_id
在开发者中心注册应用时发放的 Client ID 值
0000042301
client_secret
在开发者中心上架应用软件时发放的client secret 值
vxIMAGcVz3DAx20uDBr/IDWNJAPNHFl7YruF4uxB6BI=
grant_type
固定值
client_credentials

Request Header :
Parameter Name
Description
Example
Content-Type
Http请求时Content Type必须设置为application/x-www-form-urlencoded
Content-Type: application/x-www-form-urlencoded
x-market-code
市场分类代码
x-market-code: MKT_GLB
Example

POST /v7/oauth/token HTTP/1.1
Host: apis.onestore.com
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
x-market-code: MKT_GLB

grant_type=client_credentials&client_id=0000042301&client_secret=vxIMAGcVz3DAx20uDBr/IDWNJAPNHFl7YruF4uxB6BI=

Response Body : JSON格式
Element Name
Data Type
Data Size
Description
client_id
String
255
OAuth认证client_id
access_token
String
36
AccessToken
token_type
String
6
只提供bearer方式
expires_in
Integer
10
token有效期, 单位 : 秒(second)
scope
String
1024
token使用范围
Example

{    
    "client_id":"0000042301",
    "access_token":"680b3621-1234-1234-1234-8adfaef561b4",
    "token_type":"bearer",
    "expires_in":3010,
    "scope":"DEFAULT"
}

发放示例

curl -v -X POST -H "Content-Type: application/x-www-form-urlencoded" https://sbpp.onestore.net/v7/oauth/token -d "grant_type=client_credentials" -d "client_id=0000042301" -d 
"client_secret=vxIMAGcVz3DAx20uDBr/IDWNJAPNHFl7YruF4uxB6BI="
> POST /v7/oauth/token HTTP/1.1
> Host: sbpp.onestore.net
> User-Agent: curl/7.43.0
> Accept: */*
> Content-Type: application/x-www-form-urlencoded;charset=UTF-8
> Content-Length: 35
>
* upload completely sent off: 35 out of 35 bytes
< HTTP/1.1 200 200
< Date: Wed, 02 May 2018 02:52:42 GMT
< Server: Apache< Connection: close
< Transfer-Encoding: chunked
< Content-Type: application/json;charset=UTF-8
<
* Closing connection 0
{"client_id":"0000042301","access_token":"680b3621-1234-1234-1234-8adfaef561b4","token_type":"bearer","expires_in":3600,"scope":"DEFAULT"}

因为验证（开发）环境和商用环境的AccessToken是独立管理的，因此需要根据不同环境分类管理AccessToken。

服务器API详情

由于2025年3月20日开发者中心改版，服务器API请求中使用的packageName已更改为clientId。

对于2025年3月20日之前注册的应用，客户端ID与包名相同，因此此更改不会产生影响。
对于2025年3月20日之后注册的应用，客户端ID与PID相同，请参考相关信息。

getPurchaseDetails (购买商品详情查询)

Desc : 查询购买的ONE store管理型商品的详细信息。购买完成时，需使用收到的ONE store purchaseToken（购买token）查询。通过包月型商品的purchaseToken查询时，将接收查询失败（NoSuchData）的响应。
URI : /v7/apps/{clientId}/purchases/inapp/products/{productId}/{purchaseToken}
Method : GET
Request Parameter : Path Variable格式
- String clientId : 调用 API的应用软件 (Data Size : 128)
- String productId : 商品ID (Data Size : 150)
- String purchaseToken : 购买token (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 : 无
Response Body : JSON格式
Element Name
Data Type
Data Size
Description
consumptionState
Integer
1
已购商品的消费状态 (0: 未消费, 1: 消费)
developerPayload
String
200
开发公司提供的支付固有标识符
purchaseState
Integer
1
购买状态 ( 0: 购买完成, 1: 取消完成)
purchaseTime
Long
13
购买时间 (ms)
purchaseId
String
20
购买ID
acknowledgeState
Integer
1
确认购买状态( 0: Not Acknowledged, 1: Acknowledged)
quantity
Integer
2
购买数量
Example

HTTP/1.1 200 OK
Content-type: application/json;charset=UTF-8
{    
    "consumptionState": 0,
    "developerPayload": "developerPayload",
    "purchaseState": 0,
    "purchaseTime": 1345678900000,
    "purchaseId": "17070421461015116878",
    "acknowledgeState": 0,
    "quantity": 2
}

getRecurringPurchaseDetails (包月型商品订单详情查询)

Desc : 查询购买的ONE store包月型商品的自动支付状态和最后的购买状态的详细信息。购买完成时，需使用收到的ONE store purchaseToken（购买token）查询。通过管理型商品的purchaseToken查询时，将接收查询失败（NoSuchData）的响应。
URI : /v7/apps/{clientId}/purchases/auto/products/{productId}/{purchaseToken}
Method : GET
Request Parameter : Path Variable格式
- String clientId : 调用 API的应用软件客户端ID (Data Size : 128)
- String productId : 商品ID (Data Size : 150)
- String purchaseToken : 购买token (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");

HTTP/1.1 200 OK
Content-type: application/json;charset=UTF-8
{    
    "startTime": 1345678900000,
    "expiryTime": 1345678999999,
    "nextPaymentTime": 1345688000000,
    "autoRenewing": true,
    "cancelReason": 1,
    "cancelledTime": 1345679000000,
    "acknowledgeState": 0,
    "lastPurchaseId":"15081718460701027851",
    "lastPurchaseState": 0
}

可根据以下条件判断客户是否有权使用包月型商品的内容。

如果当前时间小于或等于expiryTime（已购商品的使用终止时间），或者lastPurchaseState（最后自动支付的购买状态）为0（购买完成）状态， Ex) expiryTime >= 当前时间 AND lastPurchaseState == 0

acknowledgePurchase (确认已购商品)

Desc : 将购买的管理型或包月型商品变更为购买确认状态。
URI : /v7/apps/{clientId}/purchases/all/products/{productId}/{purchaseToken}/acknowledge
Method : POST
Request Parameter : Path Variable格式
- String clientId : 调用 API的应用软件客户端ID (Data Size : 128)
- String productId : 商品ID (Data Size : 150)
- String purchaseToken : 购买token (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."
    }
}

ONE store自动取消3天内未调用acknowledgePurchase API的购买订单。

因此，开发公司必须调用相应API，可通过SDK API或服务器API进行处理。

但是，consumePurchase API被调用的购买订单会被判断为acknowledge，不会取消购买。

consumePurchase (消费已购商品)

Desc : 将购买的管理型商品状态更改为消费状态。
URI : /v7/apps/{clientId}/purchases/inapp/products/{productId}/{purchaseToken}/consume
Method : POST
Request Parameter : Path Variable格式
- String clientId :调用 API的应用软件客户端ID (Data Size : 128)
- String productId : 商品ID (Data Size : 150)
- String purchaseToken : 购买token (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."
    }
}

cancelRecurringPurchase (请求解除自动支付)

Desc : 请求解除包月型商品的自动支付。使用订阅型商品的purchaseToken查询时, 将接收查询失败(NoSuchData)响应。
URI : /v7/apps/{clientId}/purchases/auto/products/{productId}/{purchaseToken}/cancel
Method : POST
Request Parameter : Path Variable格式
- String clientId : 调用 API的应用软件客户端ID (Data Size : 128)
- String productId : 商品ID (Data Size : 150)
- String purchaseToken : 购买token (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 : 无
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."
    }
}

reactiveRecurringPurchase (请求取消解除自动支付)

Desc : 取消解除包月型商品的自动支付的请求。使用订阅型商品的purchaseToken查询时，将接收查询失败(NoSuchData)响应。
URI : /v7/apps/{clientId}/purchases/auto/products/{productId}/{purchaseToken}/reactivate
Method : POST
Request Parameter : Path Variable格式
- String clientId : 调用 API的应用软件客户端ID (Data Size : 128)
- String productId : 商品ID (Data Size : 150)
- String purchaseToken : 购买token (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 : 无
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."
    }
}

getVoidedPurchases (查询取消的订单)

Desc : 查询取消的订单
URI : /v7/apps/{clientId}/voided-purchases
Method : GET
Request Parameter : Path Variable格式
- String clientId : 调用 API的应用软件客户端ID (Data Size : 128)
Request Parameter (Optional) : Query String格式
- String continuationKey : 取消购买的数量较多时，ONE store服务器返回该值。当响应中有continuationKey时，通过再次调用getVoidedPurchases的同时传递continuationKey，可能会收到额外的取消购买历史记录。 (Data Size : 41)
- String startTime : 取消购买日期的搜索开始的时间 (milliseconds). 以当前时间为准，仅可设置到过去1个月内；单独使用startTime时，endTime设置成以startTime基准的未来1个月。 (Data Size : 13)
- String endTime : 取消购买日期的搜索结束的时间 (milliseconds). 不能超过当前时间，单独使用endTime时，startTime设置成以endTime为基准的过去1个月。 (Data Size : 13)
- unsigned integer maxResults : 最大查询次数 default 100 (Data Size : 3)
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 : 无
Response Body

Element Name

Data Type

Data Size

Description

continuationKey

String

取消购买数量大于最大查询数量时返回。在后续请求中，通过设置接收的continuationKey进行调用，可以查询后续历史记录。

voidedPurchaseList

purchaseId

String

购买ID

purchaseTime

Long

购买时间(ms)

voidedTime

Long

购买取消时间(ms)

purchaseToken

String

购买Token

marketCode

String

市场分类代码

Example :

HTTP/1.1 200 OK
Content-type: application/json;charset=UTF-8
{
    "continuationKey": "continuationKey",
    "voidedPurchaseList ": [
        {
            "purchaseId": "19062709124410111299",
            "purchaseTime": 1345678900000,
            "voidedTime": 1345688900000,
            "purchaseToken": "19062709124410111299",
            "marketCode": "MKT_ONE"
        },
        {
            "purchaseId": "19062709124410111300",
            "purchaseTime": 1345679900000,
            "voidedTime": 1345878900000,
            "purchaseToken": "19062709124410111299",
            "marketCode": "MKT_ONE"
        }
    ]
}

Desc : Checks the purchase cancellation details.
URI : /v7/apps/{clientId}/voided-purchases
Method : GET
Request Parameter : Path Variable format
- String clientId : Client ID of the app that calls API (Data Size : 128)
Request Parameter (Optional) : Query String format
- String continuationKey: The ONE store server returns this value if there are numerous purchase cancellations.If there is a continuationKey in the response, call getVoidedPurchases again. If there is continuationKey in the response, you can receive additional purchase cancellation histories if you call up getVoidedPurchases again and send continuationKey (data size: 41).
- String startTime: The search start time of purchase cancellation date (milliseconds).The start time can be set until only one month prior to the current time, and if startTime is used alone, endTime will be set until one month after startTime (data size: 13).
- String endTime : The search end time of purchase cancellation date (milliseconds).The end time cannot be bigger than the current time, and if endTime is used alone, the startTime will be set until one month prior to endTime.
- unsigned integer maxResults : The default maximum number of searches is 100 (Data Size : 3)
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_GLB");

Request Body : N/A
Response Body :
Element Name
Data Type
Data Size
Description
continuationKey
String
41
It returns when the number of purchase cancellations is higher than the maximum number of searches. After that, if you set and call continuationKey, which has been received upon request, you can search the history.
voidedPurchaseList

-

purchaseId
String
20
Purchase ID
purchaseTime
Long
13
Purchase time (ms)
voidedTime
Long
13
Purchase cancellation time (ms)
purchaseToken
String
20
Purchase token
marketCode
String
-
Market identification code

Example :

HTTP/1.1 200 OK
Content-type: application/json;charset=UTF-8
{
    "continuationKey": "continuationKey",
    "voidedPurchaseList ": [
        {
            "purchaseId": "19062709124410111299",
            "purchaseTime": 1345678900000,
            "voidedTime": 1345688900000,
            "purchaseToken": "19062709124410111299",
            "marketCode": "MKT_ONE"
        },
        {
            "purchaseId": "19062709124410111300",
            "purchaseTime": 1345679900000,
            "voidedTime": 1345878900000,
            "purchaseToken": "19062709124410111299",
            "marketCode": "MKT_ONE"
        }
    ]
}

Desc : 구매취소내역을 조회한다.
URI : /v7/apps/{clientId}/voided-purchases
Method : GET
Request Parameter : Path Variable 형식
- String clientId : API를 호출하는 앱의 클라이언트 ID (Data Size : 128)
Request Parameter (Optional) : Query String 형식
- String continuationKey : 구매취소 건이 많을 경우 원스토어 서버에서 이 값을 반환합니다. 응답에 continuationKey가 있을 경우, getVoidedPurchases를 다시 호출하면서 continuationKey를 전달하면 추가 구매취소 내역을 전달받을 수 있습니다. (Data Size : 41)
- String startTime : 구매취소일시 검색 시작시간 (milliseconds). 현재시간기준 과거 1개월까지만 설정가능하며 startTime 단독으로 사용할 경우 endTime은 startTime기준 미래 1개월로 설정됩니다. (Data Size : 13)
- String endTime : 구매취소일시 검색 종료시간 (milliseconds). 현재시간보다 클 수 없으며 endTime 단독으로 사용할 경우 startTime은 endTime기준 과거 1개월로 설정됩니다. (Data Size : 13)
- unsigned integer maxResults : 최대조회건수 default 100 (Data Size : 3)
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 : 없음
Response Body :
Element Name
Data Type
Data Size
Description
continuationKey
String
41
구매취소 건이 최대조회건수보다 많을 경우 반환. 이후 요청시 전달받은 continuationKey 를 셋팅하여 호출하면 이후 내역을 조회 할 수 있음
voidedPurchaseList

-

purchaseId
String
20
구매 ID
purchaseTime
Long
13
구매시간(ms)
voidedTime
Long
13
구매취소시간(ms)
purchaseToken
String
20
구매 토큰
marketCode
String
-
마켓 구분 코드

Example :

HTTP/1.1 200 OK
Content-type: application/json;charset=UTF-8
{
    "continuationKey": "continuationKey",
    "voidedPurchaseList ": [
        {
            "purchaseId": "19062709124410111299",
            "purchaseTime": 1345678900000,
            "voidedTime": 1345688900000,
            "purchaseToken": "19062709124410111299",
            "marketCode": "MKT_ONE"
        },
        {
            "purchaseId": "19062709124410111300",
            "purchaseTime": 1345679900000,
            "voidedTime": 1345878900000,
            "purchaseToken": "19062709124410111299",
            "marketCode": "MKT_ONE"
        }
    ]
}

getUnconfirmedPurchases (查询未确认的购买记录)

本 API 仅支持韩国 ONE store 商品。

全球商品支持计划于 2026 年 4 月更新。

Desc : 返回尚未完成购买确认（consume 或 acknowledge）的购买列表。
URI : /v7/apps/{clientId}/unconfirmed-purchases
Method : GET
Request Parameter : Path Variable 格式
- String clientId : 调用 API的应用软件客户端ID (Data Size : 128)
Request Parameter (Optional) : Query String 格式
Parameter Name
Data Type
Required
Description
continuationKey
String
false
当购买列表数量超过最大查询条数时返回结果。
在后续请求中设置返回的 continuationKey，即可查询后续记录。
startTime
Long
false
查询购买记录的开始时间（毫秒）。
仅可设置为当前时间起向前最多 1 个月。若仅设置 startTime，endTime 将自动设置为 startTime 起向后 1 个月。
endTime
Long
false
查询购买记录的结束时间（毫秒）。
不可设置为晚于当前时间。若仅设置 endTime，startTime 将自动设置为 endTime 起向前 1 个月。
maxResults
Integer
false
最大查询条数（默认值：100）
1 ~ 100
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 680b3512-1253-5642-1263-8adjbf651nb");
Request.setHeader("Content-Type", "application/json");

Request Body : N/A
Response Body:
Element Name
Data Type
Data Size
Description
continuationKey
String

当购买列表数量超过最大查询条数时返回结果。
在后续请求中设置返回的 continuationKey，即可查询后续记录。
unconfirmedPurchaseList [

{

type
String
-
商品类型
orderId
String
40
Payment ID
productId
String
150
In-App商品的商品ID
purchaseToken
String
20
购买token
purchaseId
String
20
购买ID
purchaseTime
Long
13
在ONE store支付系统中完成支付的时间(ms)
purchaseState
Integer
1
COMPLETED : 已支付 / CANCELED : 取消
developerPayload
String
200
由开发公司管理以标识购买件的标识符
quantity
Integer

购买商品的数量
marketCode
String
-
市场分类编码 ( MKT_ONE : ONE store, MKT_GLB : Global ONE store)
}

]

Example

HTTP/1.1 200 OK
Content-type: application/json;charset=UTF-8
{
	"continuationKey": "continuationKey",
	"unconfirmedPurchaseList ": [
		{
            "type": "inapp",
            "orderId": "01239349082349823489342",
            "productId": "다이아100_20170818000000",
 			"purchaseToken": "19062709124410111299",
			"purchaseId": "19062709124410111299",
			"purchaseTime": 1345678900000,
 			"purchaseState": 0,
            "developerPayload": "E23DEFB029F84F4383ECB0E53B46B6A2",
            "quantity": 1,
			"marketCode": "MKT_ONE"
		},
 		{
            "type": "inapp",
            "orderId": "01239349082349823489343",
            "productId": "루비300_20170818000000",
 			"purchaseToken": "19062709124410111299",
			"purchaseId": "19062709124410111300",
			"purchaseTime": 1345679900000,
 			"purchaseState": 0,
            "developerPayload": "T_RPAY_27_201707120110880",
            "quantity": 2,
			"marketCode": "MKT_ONE"
		}
	]
}

getSubscriptionDetail (订阅型商品订单详情查询)

Desc : 查询订阅型商品的订单详情。
URI : /v7/apps/{clientId}/purchases/subscription/products/{productId}/{purchaseToken}
Method : GET
Request Parameter : Path Variable格式
- String clientId : 调用 API的应用软件客户端ID (Data Size : 128)
- String productId : 商品ID (Data Size : 150)
- String purchaseToken : 购买token (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 : 无
Response Body

Element Name

Data Type

Data Size

Description

acknowledgementState

Integer

购买确认状态( 0: Not Acknowledged, 1: Acknowledged)

developerPayload

String

200

开发公司提供的支付固有标识符

autoRenewing

boolean

是否更新下一次支付 o 订阅解除预约，解除，到期 : false o 剩余 : true

paymentState

Integer

是否接收订阅支付 o null: 到期状态 o 0: 支付未完成状态 o 1: 请求支付后支付完成的状态 o 2: 处理为免费期间的状态 o 3: 商品升级/降级时处理为DEFERRED选项的状态

priceAmount

String

购买金额

priceAmountMicros

Long

购买金额 * 100万

nextPriceAmount

String

下一次购买金额

nextPriceAmountMicros

Long

下一次购买金额 * 100万

nextPaymentTimeMillis

Long

下一次购买时间(ms)

priceCurrencyCode

String

货币代码

countryCode

String

国家代码(KR 固定)

startTimeMillis

Long

订阅开始(第一次支付)时间(ms)

expiryTimeMillis

Long

订阅到期时间(ms)

pauseStartTimeMillis

Long

暂停开始日期（ms）-仅在暂停预约/暂停时存在

pauseEndTimeMillis

Long

暂停开始日期（ms）-仅在暂停预约/暂停时存在

autoResumeTimeMillis

Long

暂停后重新订阅时间 o 正常订阅中: null o 暂停预约/确定/暂停中: 下一次支付日 + 暂停日期

linkedPurchaseToken

String

变更订阅商品时，如没有变更以前的purchaseToken, 则为null

lastPurchaseId

String

最后一次购买ID

cancelledTimeMillis

Long

订阅解除时间(ms)

cancelReason

Integer

订阅解除原因 o 0 : 客户请求 o 1 : 其他

promotionPrice

Object

促销活动金额信息

promotionPrice.promotionPrice

String

促销活动金额

promotionPrice.promotionPriceMicros

Long

促销活动金额信息 * 100万

promotionPrice.promotionPeriod

Int

促销活动适用次数

priceChange

Object

价格变动信息

priceChange.seq

Integer

价格变动顺序

priceChange.previousPrice

String

之前价格

priceChange.previousPriceMicros

Long

之前价格 * 100万

priceChange.newPrice

String

新价格

priceChange.newPriceMicros

Long

新价格 * 100万

priceChange.applyTimeMillis

Long

适用日期(ms)

priceChange.agreement

Boolean

价格变动同意与否

priceChange.agreementDueDateTimeMillis

Long

对价格变动同意的截止时间(ms) (政策附加说明) Value = 价格变更日 +7+30日用户可以在同意到期日后的第一个自动支付时间点为止同意。

Example :

HTTP/1.1 200 OK
Content-type: application/json;charset=UTF-8
{
    "acknowledgementState":1,
    "autoRenewing":true,
    "paymentState":1,
    "lastPurchaseId": "20202394820938409234"
    "linkedPurchaseToken":null,
    "priceAmount":"100",
    "priceAmountMicros":100000000,
    "nextPriceAmount":"150",
    "nextPriceAmountMicros":150000000,
    "nextPaymentTimeMillis": 1623337199000,
    "priceCurrencyCode":"KRW",
    "countryCode":"KR",
    "startTimeMillis":1623337199000,
    "expiryTimeMillis":1625929199000,
    "pauseStartTimeMillis":1625929199000,
    "pauseEndTimeMillis":1625929199000,
    "autoResumeTimeMillis":1625878800000,
    "cancelledTimeMillis":1625929199000,
    "cancelReason":0,
    "promotionPrice":{
        "promotionPrice":"100",
        "promotionPriceMicros":100000000,
        "promotionPeriod":30
    },
    "priceChange":{
        "seq": 1,
        "previousPrice":"100",
        "previousPriceMicros":100000000,
        "newPrice":"500",
        "newPriceMicros":500000000,
        "applyTimeMillis":1625670000000,
        "agreement":false,
        "agreementDueDateTimeMillis": 1345678920000
    }
}

cancelSubscription (请求解除订阅支付)

Desc : 请求解除订阅型商品的自动支付。但在请求时，如果商品的订阅状态是暂时停止、延期支付、账户保留的话，会立即要求解除。
URI : /v7/apps/{clientId}/purchases/subscription/products/{productId}/{purchaseToken}/cancel
Method : POST
Request Parameter : Path Variable格式
- String clientId : 调用 API的应用软件客户端ID (Data Size : 128)
- String productId : 商品ID (Data Size : 150)
- String purchaseToken : 购买token (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 : 无
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."
    }
}

reactivateSubscription (请求取消解除订阅支付)

Desc : 取消订阅型商品的解除自动支付的要求。但，如果是立即解除的情况，就不能取消解除的请求。
URI : /v7/apps/{clientId}/purchases/subscription/products/{productId}/{purchaseToken}/reactivate
Method : POST
Request Parameter : Path Variable格式
- String clientId : 调用 API的应用软件客户端ID (Data Size : 128)
- String productId : 商品ID (Data Size : 150)
- String purchaseToken : 购买token (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 : 无
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."
    }
}

deferSubscription (请求延期订阅支付)

Desc : 延期订阅型商品的下一个支付日。
URI : /v7/apps/{clientId}/purchases/subscription/products/{productId}/{purchaseToken}/defer
Method : POST
Request Parameter : Path Variable格式
- String clientId : 调用 API的应用软件客户端ID (Data Size : 128)
- String productId : 商品ID (Data Size : 150)
- String purchaseToken : 购买token (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格式

Parameter Name

Data Type

Required

Description

deferPeriod

Integer

true

延期时间 o 商用: 日为单位(1~365日) o Sandbox: 分为单位

Example :

Content-type: application/json;charset=UTF-8
{
	"deferPeriod" : 3
}

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."
    }
}

标准响应规格

标准响应代码

Code

Message

Description

HTTP Status Code

有关API

AccessBlocked

The request was blocked.

请求被阻止。

403 - Fobidden

通用

AccessTokenExpired

Access token has expired.

Access token已过期。

401 - Unauthorized

通用

BadRequest

The request are invalid.

请求无效。

400 - Bad Request

通用

DeveloperPayloadNotMatch

The request developerPayload does not match the value passed in the purchase request.

与购买请求中传递的 developerPayload值不一致。

400 - Bad Request

acknowledgePurchase consumePurchase

InternalError

An undefined error has occurred.

发生了未定义的错误。

500 - Internal Server Error

通用

InvalidAccessToken

Access token is invalid.

Access token无效。

401 - Unauthorized

通用

InvalidAuthorizationHeader

Authorization header is invalid.

Authorization header值无效。

400 - Bad Request

通用

InvalidConsumeState

The purchase consumption status cannot be changed or has already been changed.

消费状态不能更改或已经更改。

409 - Conflict

consumePurchase

InvalidContentType

The request content-type is invalid.

无效的Content Type。

415 - Unsupported Media Type

通用

InvalidPurchaseState

Purchase history does not exist or is not completed.

购买订单不存在或不是购买完成状态。

409 - Conflict

acknowledgePurchase consumePurchase

InvalidRequest

Request parameters are invalid. [ field1, field2, ... ]

请求参数无效。 [ field1, field2, ... ]

400 - Bad Request

通用

MethodNotAllowed

HTTP method not supported.

不支持的HTTP Method。

405 - Method Not Allowed

通用

NoSuchData

The requested data could not be found.

查询的结果值不存在。

404 - Not Found

getPurchaseDetails getRecurringPurchaseDetails

RequiredValueNotExist

Request parameters are required. [ field1, field2, ... ]

必须值不存在。 [ field1, field2, ... ]

400 - Bad Request

通用

ResourceNotFound

The requested resource could not be found.

请求的资源不存在。

404 - Not Found

通用

ServiceMaintenance

System maintenance is in progress.

系统维护正在进行中。

503 - Service Temporarily Unavailable

通用

Success

The request has been completed successfully.

请求已成功完成。

200 - Success

acknowledgePurchase consumePurchase cancelRecurringPurchase reactivateRecurringPurchase

UnauthorizedAccess

Not authorized to this API.

没有该API的访问权限。

403 - Fobidden

通用

标准错误响应规格

除了正常响应外，发生错误时，服务器API还会传回以下Example格式的标准错误响应。请参考以下内容。

Response Body : JSON格式

Element Name

Data Type

Data Size

Description

code

String

响应代码

message

String

响应信息

error

Object

Example

HTTP/1.1 400 Bad Request
Content-type: application/json;charset=UTF-8
{
    "error" : {
        "code" : "NoSuchData",
        "message" : "The requested data could not be found."
    }
}

通用代码

商品类型代码

Code

Name

Description

inapp

管理型商品

消费性/永久性/固定期限商品

auto

包月型商品

每月自动支付的商品

subscription

订阅型商品

订阅型(自动支付)的商品

all

全部商品

管理型商品 + 包月型商品

Last updated 3 days ago

hashtag概要

hashtagHOST Domain

hashtag市场分类

hashtagONE store OAuth

hashtagOAuth概要

hashtagOAuth API详情

hashtag发放AccessToken

hashtag服务器API详情

hashtaggetPurchaseDetails (购买商品详情查询)

hashtaggetRecurringPurchaseDetails (包月型商品订单详情查询)

hashtagacknowledgePurchase (确认已购商品)

hashtagconsumePurchase (消费已购商品)

hashtagcancelRecurringPurchase (请求解除自动支付)

hashtagreactiveRecurringPurchase (请求取消解除自动支付)

hashtaggetVoidedPurchases (查询取消的订单)

hashtaggetUnconfirmedPurchases (查询未确认的购买记录)

hashtaggetSubscriptionDetail (订阅型商品订单详情查询)

hashtagcancelSubscription (请求解除订阅支付)

hashtagreactivateSubscription (请求取消解除订阅支付)

hashtagdeferSubscription (请求延期订阅支付)

hashtag标准响应规格

hashtag标准响应代码

hashtag标准错误响应规格

hashtag通用代码

hashtag商品类型代码

概要

HOST Domain

市场分类

ONE store OAuth

OAuth概要

OAuth API详情

发放AccessToken

服务器API详情

getPurchaseDetails (购买商品详情查询)

getRecurringPurchaseDetails (包月型商品订单详情查询)

acknowledgePurchase (确认已购商品)

consumePurchase (消费已购商品)

cancelRecurringPurchase (请求解除自动支付)

reactiveRecurringPurchase (请求取消解除自动支付)

getVoidedPurchases (查询取消的订单)

getUnconfirmedPurchases (查询未确认的购买记录)

getSubscriptionDetail (订阅型商品订单详情查询)

cancelSubscription (请求解除订阅支付)

reactivateSubscription (请求取消解除订阅支付)

deferSubscription (请求延期订阅支付)

标准响应规格

标准响应代码

标准错误响应规格

通用代码

商品类型代码