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的值可通過點擊ONE store開發者中心註冊的App的In-App資訊 > "認證及許可證"按鈕確認。

發放AccessToken

• URI : /v7/oauth/token

• Method: POST

• Request Parameter: Form格式

  Parameter Name	Description	Example
  client_id	一般來說和packageName相同	com.onestore.game.goindol
  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=com.onestore.game.goindol&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":"com.onestore.game.goindol",
    "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=com.onestore.game.goindol" -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":"com.onestore.game.goindol","access_token":"680b3621-1234-1234-1234-8adfaef561b4","token_type":"bearer","expires_in":3600,"scope":"DEFAULT"}

因为驗證（開發）環境和商用環境的AccessToken是獨立管理的，因此需要根據不同環境分類管理AccessToken。

伺服器API詳情

getPurchaseDetails (購買商品詳情查詢)

• Desc : 查詢購買的ONE store管理型商品的詳細資訊。 購買完成時，需使用收到的ONE store purchaseToken（購買token）查詢。 通過包月型商品的purchaseToken查詢時，將接收查詢失敗（NoSuchData）的回應。

• URI : /v7/apps/{packageName}/purchases/inapp/products/{productId}/{purchaseToken}

• Method : GET

• Request Parameter : Path Variable格式

  • String packageName : 調用 API的應用軟件包名 (Data Size : 128)

  • String productId : 商品ID (Data Size : 150)

  • String purchaseToken : 購買token (Data Size : 20)

• Request Header

  Parameter Name	Data Type	Required	Description
  Authorization	String	true	通過Access Token API接收的access_token
  Content-Type	String	true	application/json
  x-market-code	String	false	市場分類代碼

• Example

  Request.setHeader("Authorization", "Bearer 680b3621-1234-1234-1234-8adfaef561b4");
  Request.setHeader("Content-Type", "application/json");
  Request.setHeader("x-market-code", "MKT_GLB");

• Request Body : 無

• Response Body : JSON格式

  Element Name	Data Type	Data Size	Description
  consumptionState	Integer	1	已購商品的使用状态 (0: 未使用, 1: 使用)
  developerPayload	String	200	開發公司提供的支付固有標示符
  purchaseState	Integer	1	購買狀態 ( 0: 購買完成, 1: 取消完成)
  purchaseTime	Long	13	購買时间 (ms)
  purchaseId	String	20	購買ID
  acknowledgeState	Integer	1	確認購買狀態( 0: Not Acknowledged, 1: Acknowledged)
  quantity	Integer	2	購買數量

• Example

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

getRecurringPurchaseDetails (包月型商品訂單詳情查詢)

• Desc : 查詢購買的ONE store包月型商品的自動支付狀態和最後的購買狀態的詳細資訊。 購買完成時，需使用收到的ONE store purchaseToken（購買token）查詢。通過管理型商品的purchaseToken查詢時，將接收查詢失敗（NoSuchData）的回應。

• URI : /v7/apps/{packageName}/purchases/auto/products/{productId}/{purchaseToken}

• Method : GET

• Request Parameter : Path Variable格式

  • String packageName : 調用 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");

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/{packageName}/purchases/all/products/{productId}/{purchaseToken}/acknowledge

• Method : POST

• Request Parameter : Path Variable格式

  • String packageName : 調用 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 : 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/{packageName}/purchases/inapp/products/{productId}/{purchaseToken}/consume

• Method : POST

• Request Parameter : Path Variable格式

  • String packageName :調用 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 : 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/{packageName}/purchases/auto/products/{productId}/{purchaseToken}/cancel

• Method : POST

• Request Parameter : Path Variable格式

  • String packageName : 調用 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格式 傳回以下格式的回應，以便在成功處理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/{packageName}/purchases/auto/products/{productId}/{purchaseToken}/reactivate

• Method : POST

• Request Parameter : Path Variable格式

  • String packageName : 調用 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格式 傳回以下格式的回應，以便在成功處理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/{packageName}/voided-purchases

• Method : GET

• Request Parameter : Path Variable格式

  • String packageName : 調用 API的應用軟件包名 (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 :

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

getSubscriptionDetail (訂閱型商品訂單詳情查詢)

• Desc : 查詢訂閱型商品的訂單詳情。

• URI : /v7/apps/{packageName}/purchases/subscription/products/{productId}/{purchaseToken}

• Method : GET

• Request Parameter : Path Variable格式

  • String packageName : 調用 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

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	-	貨幣代碼(KRW 固定)
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 :

  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/{packageName}/purchases/subscription/products/{productId}/{purchaseToken}/cancel

• Method : POST

• Request Parameter : Path Variable格式

  • String packageName : 調用 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格式 傳回以下格式的回應，以便在成功處理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/{packageName}/purchases/subscription/products/{productId}/{purchaseToken}/reactivate

• Method : POST

• Request Parameter : Path Variable格式

  • String packageName : 調用 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格式 傳回以下格式的回應，以便在成功處理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/{packageName}/purchases/subscription/products/{productId}/{purchaseToken}/defer

• Method : POST

• Request Parameter : Path Variable格式

  • String packageName : 調用 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 : 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	全部商品	管理型商品 + 包月型商品