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，調用示例如下：

Authorization Header與上述示例一樣必須正確輸入，Bearer + 空白 + AccessToken應區分大小寫。 Bearer的值是通過調用getAccessToken()獲得的AccessToken值。

錯誤示例

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

  • 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

  • 發放示例

因为驗證（開發）環境和商用環境的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 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

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

可根據以下條件判断客戶是否有權使用包月型商品的内容。

  • 如果當前時間小於或等於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 Body : JSON 格式

    Element Name
    Data Type
    Required
    Description

    developerPayload

    String

    false

  • Example :

  • Response Body : JSON格式 傳回以下格式的回應，以便在成功處理API時更直觀地判斷是否處理完成，如果api處理失敗，將傳回標準錯誤回應。

    Element Name

    Data Type

    Data Size

    Description

    code

    String

    -

    回應代碼

    message

    String

    -

    回應訊息

    result

    Object

    -

  • Example :

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 Body : JSON 格式

    Element Name
    Data Type
    Required
    Description

    developerPayload

    String

    false

  • Example :

  • Response Body : JSON 格式

    傳回以下格式的回應，以便在成功處理API時直觀地判斷是否處理完成。如果API處理失败，將傳回標準錯誤回應情況。

    Element Name
    Data Type
    Data Size
    Description

    code

    String

    -

    回應代碼

    message

    String

    -

    回應訊息

    result

    Object

    -

  • Example :

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 Body : 无

  • Response Body : JSON格式 傳回以下格式的回應，以便在成功處理API時更直觀地判斷是否處理完成。如果API處理失敗，將傳回標準錯誤回應。

Element Name

Data Type

Data Size

Description

code

String

-

回應代碼

message

String

-

回應訊息

result

Object

-

  • Example :

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 Body : 無

  • Response Body : JSON格式 傳回以下格式的回應，以便在成功處理API時更直觀地判斷是否處理完成。如果API處理失敗，將傳回標準錯誤回應。

Element Name

Data Type

Data Size

Description

code

String

-

回應代碼

message

String

-

回應訊息

result

Object

-

  • Example :

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 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 :

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

訂閱到期時間

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 :

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 Body : 無

  • Response Body : JSON格式 傳回以下格式的回應，以便在成功處理API時更直觀地判斷是否處理完成。如果API處理失敗，將傳回標準錯誤回應。

Element Name

Data Type

Data Size

Description

code

String

-

回應代碼

message

String

-

回應訊息

result

Object

-

  • Example :

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 Body : 無

  • Response Body : JSON格式 傳回以下格式的回應，以便在成功處理API時更直觀地判斷是否處理完成。如果API處理失敗，將傳回標準錯誤回應。

Element Name

Data Type

Data Size

Description

code

String

-

回應代碼

message

String

-

回應訊息

result

Object

-

  • Example :

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 Body : JSON格式

Parameter Name

Data Type

Required

Description

deferPeriod

Integer

true

延期時間 o 商用: 日為單位(1~365日) o Sandbox: 分為單位

  • Example :

  • Response Body : JSON格式 傳回以下格式的回應，以便在成功處理API時更直觀地判斷是否處理完成。如果API處理失敗，將傳回標準錯誤回應。

Element Name

Data Type

Data Size

Description

code

String

-

回應代碼

message

String

-

回應訊息

result

Object

-

  • Example :

標準回應規格

標準回應代碼

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

通用代碼

商品類型代碼

Code

Name

Description

inapp

管理型商品

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

auto

包月型商品

每月自動支付的商品

subscription

訂閱型商品

訂閱型(自動支付)的商品

all

全部商品

管理型商品 + 包月型商品

Last updated