|
| 商用 | [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 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.setHeader("Authorization", "Bearer 680b3621-1234-1234-1234-8adfaef561b4");
Request.setHeader("Content-Type", "application/json");
Request.setHeader("x-market-code", "MKT_GLB");
Request.setHeader("Authorization", "Bearer 680b3621-1234-1234-1234-8adfaef561b4");
Request.setHeader("Content-Type", "application/json");
Request.setHeader("x-market-code", "MKT_GLB");
|
* **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 (使用已購商品) Request.setHeader("Authorization", "Bearer 680b3621-1234-1234-1234-8adfaef561b4");
Request.setHeader("Content-Type", "application/json");
Request.setHeader("x-market-code", "MKT_GLB");
|
* **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 (請求解除自動支付) Request.setHeader("Authorization", "Bearer 680b3621-1234-1234-1234-8adfaef561b4");
Request.setHeader("Content-Type", "application/json");
Request.setHeader("x-market-code", "MKT_GLB");
|
* **Example :**
```json
HTTP/1.1 200 OK
Content-type: application/json;charset=UTF-8
{
"result" : {
"code" : "Success",
"message" : "Request has been completed successfully."
}
}
```
#### reactiveRecurringPurchase (請求取消解除自動支付) Request.setHeader("Authorization", "Bearer 680b3621-1234-1234-1234-8adfaef561b4");
Request.setHeader("Content-Type", "application/json");
Request.setHeader("x-market-code", "MKT_GLB");
|
* **Example :**
```json
HTTP/1.1 200 OK
Content-type: application/json;charset=UTF-8
{
"result" : {
"code" : "Success",
"message" : "Request has been completed successfully."
}
}
```
### getVoidedPurchases (查詢取消的訂單) Request.setHeader("Authorization", "Bearer 680b3621-1234-1234-1234-8adfaef561b4");
Request.setHeader("Content-Type", "application/json");
Request.setHeader("x-market-code", "MKT_GLB");
| - |
|
| 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 형식
| - |
|
| 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 (查詢未確認的購買記錄) 當購買清單數量超過最大查詢筆數時返回結果。
於後續請求中設定回傳的 continuationKey，即可查詢後續資料。 查詢購買紀錄的開始時間（毫秒）。
僅可設定為以目前時間往前最多 1 個月。startTime，endTime 將自動設定為 自 startTime 起往後 1 個月。 查詢購買紀錄的結束時間（毫秒）。
不可設定為晚於目前時間。endTime，startTime 將自動設定為 自 endTime 起往前 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**
```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 |
| 當購買清單數量超過最大查詢筆數時返回結果。
於後續請求中設定回傳的 continuationKey，即可查詢後續資料。
|
|
|
| { |
|
|
|
| type | String | - | 商品類型 |
| orderId | String | 40 | 支付 ID |
| productId | String
| 150 | 於開發者中心註冊商品時指定的應用內商品 ID |
| purchaseToken | String | 20 | 購買 token |
| purchaseId | String | 20 | 購買 ID |
| purchaseTime | Long | 13 | 購買時間
(ms)
|
| purchaseState | Integer | 1 | 購買狀態（0：購買完成，1：取消完成） |
| 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 (訂閱型商品訂單詳情查詢) Request.setHeader("Authorization", "Bearer 680b3621-1234-1234-1234-8adfaef561b4");
Request.setHeader("Content-Type", "application/json");
Request.setHeader("x-market-code", "MKT_GLB");
是否更新下一次支付
|
| paymentState | Integer | 1 | 是否接收 訂閱支付
|
| 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 | 訂閱到期時間 |
| pauseStartTimeMillis | Long | 13 | 暫停開始日期（ms）-僅在暫停預約/暫停時存在 |
| pauseEndTimeMillis | Long | 13 | 暫停開始日期（ms）-僅在暫停預約/暫停時存在 |
| autoResumeTimeMillis | Long | 13 | 暫停後重新訂閱時間间
|
| linkedPurchaseToken | String | 20 | 變更訂閱商品時，如沒有變更以前的purchaseToken, 則為null |
| lastPurchaseId | String | 20 | 最後一次購買ID |
| cancelledTimeMillis | Long | 13 | 訂閱解除時間(ms) |
| cancelReason | Integer | 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)
|
* **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 (請求解除訂閱支付) Request.setHeader("Authorization", "Bearer 680b3621-1234-1234-1234-8adfaef561b4");
Request.setHeader("Content-Type", "application/json");
Request.setHeader("x-market-code", "MKT_GLB");
|
* **Example :**
```json
HTTP/1.1 200 OK
Content-type: application/json;charset=UTF-8
{
"result" : {
"code" : "Success",
"message" : "Request has been completed successfully."
}
}
```
#### reactivateSubscription (請求取消解除訂閱支付) Request.setHeader("Authorization", "Bearer 680b3621-1234-1234-1234-8adfaef561b4");
Request.setHeader("Content-Type", "application/json");
Request.setHeader("x-market-code", "MKT_GLB");
|
* **Example :**
```json
HTTP/1.1 200 OK
Content-type: application/json;charset=UTF-8
{
"result" : {
"code" : "Success",
"message" : "Request has been completed successfully."
}
}
```
### deferSubscription (請求延期訂閱支付) Request.setHeader("Authorization", "Bearer 680b3621-1234-1234-1234-8adfaef561b4");
Request.setHeader("Content-Type", "application/json");
Request.setHeader("x-market-code", "MKT_GLB");
延期時間
|
* **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."
}
}
```
## 標準回應規格
|
* **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."
}
}
```
## 通用代碼 
