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日之前註冊的應用程式，Client ID 與 Package Name 相同，因此此更改不會產生影響。
對於2025年3月20日之後註冊的應用程式，Client 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的應用軟件Client 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格式
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的應用軟件Client 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的應用軟件Client 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的應用軟件Client 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的應用軟件Client 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的應用軟件Client 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的應用軟件Client 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的應用軟件Client 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
支付 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

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的應用軟件Client 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

訂閱到期時間

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的應用軟件Client 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的應用軟件Client 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的應用軟件Client 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 (請求延期訂閱支付)

標準回應規格

標準回應代碼

標準錯誤回應規格

通用代碼

商品類型代碼