# 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://iap-apis.onestore.net](https://iap-apis.onestore.net/) | {% hint style="info" %} 本文中使用的域名是，国内和全球通用的域名。 仅在韩国服务的现有App/游戏的域名则保持原有的。(apis.onestore.co.kr) {% endhint %} ### 市场分类 ● Request header中已新增市场分类代码（x-market-code）。 ● 如果在全球范围内提供服务，则必须在header中添加市场分类代码。 ● 如果没有市场分类代码，会议韩国服务（默认值）来调用。 | 市场分类代码 | 服务国家 | | -------- | ---- | | MKT\_ONE | 韩国 | | MKT\_GLB | 除韩国外 | {% hint style="danger" %} 根据市场区分代码，服务器 API 响应提供的时间标准有所不同。 MKT\_ONE : UTC+09 MKT\_GLC : UTC+00 {% endhint %} ## 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，调用示例如下： {% code overflow="wrap" %} ```json 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 ``` {% endcode %} {% hint style="info" %} Authorization Header与上述示例一样必须正确输入，Bearer + 空白 + AccessToken应区分大小写。 Bearer的值是通过调用getAccessToken()获得的AccessToken值。 {% endhint %} 错误示例 ```json 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** {% code overflow="wrap" %} ```bash 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= ``` {% endcode %} * **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** ```json { "client_id":"0000042301", "access_token":"680b3621-1234-1234-1234-8adfaef561b4", "token_type":"bearer", "expires_in":3010, "scope":"DEFAULT" } ``` * **发放示例** {% code overflow="wrap" %} ```json 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"} ``` {% endcode %} {% hint style="info" %} 因为验证（开发）环境和商用环境的AccessToken是独立管理的，因此需要根据不同环境分类管理AccessToken。 {% endhint %} ## **服务器API详情** {% hint style="info" %} 由于2025年3月20日开发者中心改版，服务器API请求中使用的`packageName`已更改为`clientId`。 * 对于2025年3月20日之前注册的应用，客户端ID与包名相同，因此此更改不会产生影响。 * 对于2025年3月20日之后注册的应用，客户端ID与PID相同，请参考相关信息。 {% endhint %} ### 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** ```json 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");
```json 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 } ``` {% hint style="info" %} 可根据以下条件判断客户是否有权使用包月型商品的内容。 * 如果当前时间小于或等于expiryTime（已购商品的使用终止时间），或者lastPurchaseState（最后自动支付的购买状态）为0（购买完成）状态， \ Ex) expiryTime >= 当前时间 AND lastPurchaseState == 0 {% endhint %} ### 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 :** ```json { "developerPayload": "your payload" } ``` * **Response Body :** JSON格式\ 传回以下格式的响应，以便在成功处理API时更直观地判断是否处理完成。如果API处理失败，将传回标准错误响应。 | **Element Name** | **Data Type** | **Data Size** | **Description** | | ---------------- | ------------- | ------------- | --------------- | | code | String | - | 响应代码 | | message | String | - | 响应信息 | | result | Object | - |


| * **Example :** ```json HTTP/1.1 200 OK Content-type: application/json;charset=UTF-8 { "result" : { "code" : "Success", "message" : "Request has been completed successfully." } } ``` {% hint style="info" %} ONE store自动取消3天内未调用acknowledgePurchase API的购买订单。 因此，开发公司必须调用相应API，可通过SDK API或服务器API进行处理。 但是，consumePurchase API被调用的购买订单会被判断为acknowledge，不会取消购买。 {% endhint %} ### 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 :** ```json { "developerPayload": "your payload" } ``` * **Response Body :** JSON 형식 传回以下格式的响应，以便在成功处理API时更直观地判断是否处理完成。如果API处理失败，将传回标准错误响应。 | Element Name | Data Type | Data Size | Description | | ------------ | --------- | --------- | ----------- | | code | String | - | 响应代码 | | message | String | - | 响应信息 | | result | Object | - |


| * **Example :** ```json 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 :** ```json 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 :** ```json 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 | 41 | 取消购买数量大于最大查询数量时返回。在后续请求中，通过设置接收的continuationKey进行调用，可以查询后续历史记录。 | | voidedPurchaseList |


| - |


| | purchaseId | String | 20 | 购买ID | | purchaseTime | Long | 13 | 购买时间(ms) | | voidedTime | Long | 13 | 购买取消时间(ms) | | purchaseToken | String | 20 | 购买Token | | marketCode | String | - | 市场分类代码 | * **Example :** ```json 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** ```java 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 :** ```json 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** ```java 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 :** ```json 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 (查询未确认的购买记录) {% hint style="warning" %} **本 API 仅支持韩国 ONE store 商品。** * 全球商品支持计划于 2026 年 4 月更新。 {% endhint %} * **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 |

当购买列表数量超过最大查询条数时返回结果。

| | startTime | Long | false |

查询购买记录的开始时间（毫秒）。

| | endTime | Long | false |

查询购买记录的结束时间（毫秒）。

| | maxResults | Integer | false |

最大查询条数（默认值：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** ```java 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 |


|

当购买列表数量超过最大查询条数时返回结果。

| | 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** ```java 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 | 1 | 购买确认状态( 0: Not Acknowledged, 1: Acknowledged) | | developerPayload | String | 200 | 开发公司提供的支付固有标识符 | | autoRenewing | boolean | - |

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

| | paymentState | Integer | 1 |

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

| | priceAmount | String | - | 购买金额 | | priceAmountMicros | Long | - | 购买金额 \* 100万 | | nextPriceAmount | String | - | 下一次购买金额 | | nextPriceAmountMicros | Long | - | 下一次购买金额 \* 100万 | | nextPaymentTimeMillis | Long | 13 | 下一次购买时间(ms) | | priceCurrencyCode | String | - | 货币代码 | | countryCode | String | - | 国家代码(KR 固定) | | startTimeMillis | Long | 13 | 订阅开始(第一次支付)时间(ms) | | expiryTimeMillis | Long | 13 | 订阅到期时间(ms) | | pauseStartTimeMillis | Long | 13 | 暂停开始日期（ms）-仅在暂停预约/暂停时存在 | | pauseEndTimeMillis | Long | 13 | 暂停开始日期（ms）-仅在暂停预约/暂停时存在 | | autoResumeTimeMillis | Long | 13 |

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

| | linkedPurchaseToken | String | 20 | 变更订阅商品时，如没有变更以前的purchaseToken, 则为null | | lastPurchaseId | String | 20 | 最后一次购买ID | | cancelledTimeMillis | Long | 13 | 订阅解除时间(ms) | | cancelReason | Integer | 1 |

订阅解除原因
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 | 13 | 适用日期(ms) | | priceChange.agreement | Boolean | - | 价格变动同意与否 | | priceChange.agreementDueDateTimeMillis | Long | 13 |

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

| * **Example :** ```json 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 :** ```json 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 :** ```json 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 :** ```json 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 :** ```json 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** ```json 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 | 全部商品 | 管理型商品 + 包月型商品 |