其他結帳系統的後端整合指南 (僅適用於韓國)

為了回報其他結帳系統的交易,Google Play Developer API 目前已新增功能。本指南將說明如何使用新功能回報其他結帳系統的交易。

您可能需要幾個元件,才能從後端處理應用程式內購交易。如要建構這些元件,請按照「設定 Google Play Developer API」的說明,設定後端整合作業。如需並非專屬於其他結帳系統 API 的所有開發人員後端功能,則可參考 Google Play 結帳系統說明文件的指示。

向 Google Play 回報新的外部交易

整合 Externaltransactions APIs 後,即可回報韓國境內在 Google Play 結帳系統以外進行的交易,包括因申請免費試用而產生的 ₩0 韓元交易。如有符合條件的使用者,您只應針對他們所在國家/地區回報其他結帳系統的交易,否則 API 呼叫就會失敗。這項限制適用於所有交易,包括新交易、續訂、儲值、升級和降級等等。

回報外部交易

付款透過其他結帳系統完成授權後,您應呼叫 Externaltransactions API 回報外部交易。這適用於所有交易,包括收取初始費用、續訂和退款等等。凡是進行任何交易後,都必須在 24 小時內回報。

每筆外部交易在回報時都應附上外部交易 ID。如果是週期性消費 (例如可自動續訂的訂閱項目),您需要傳送與這類消費中第一筆交易相關聯的外部交易 ID,做為退款等所有後續交易的參數。如此一來,就能記錄這類消費的一系列交易。如果產品有所變更 (例如升級或降級),或是使用者在週期性交易取消或過期後再次購買相同產品,請針對這些消費傳送新的外部交易 ID。這個外部交易 ID 不得包含任何個人識別資訊。

回報新交易

每當在外部結帳系統中完成新交易時,都必須呼叫 Externaltransactions API。針對新的購買交易,您需要在後端提供與交易相關聯的不重複 externalTransactionId 做為查詢參數。這個 externalTransactionId 不得在相同應用程式的套件 ID 中重複使用。

如果是一次性消費,或是週期性消費 (例如訂閱) 的首次交易,要求主體也必須包含應用程式透過 AlternativeBillingListener 回呼所收到的 externalTransactionToken。無論屬於上述哪種情況,一律稱為「初始交易」。初始交易完成後,您就不再需要用到 externalTransactionToken,而是應提供新的不重複 externalTransactionId 回報後續交易 (例如訂閱項目續訂)。如要進一步瞭解如何回報後續交易,請參閱「回報消費後續的交易」。

示例:

  1. 開發人員在應用程式中設定並啟用其他結帳系統。
  2. 韓國境內的使用者 1 想購買 product1,這項產品的費用為每月 12634.10 韓元,並提供一個月免費試用優惠。
  3. 應用程式根據 product1ProductDetails 和使用者選擇的方案,啟動購買流程。
  4. 使用者 1 選擇開發人員的其他結帳系統。
  5. AlternativeBillingListener 收到 my_token 值做為 externalTransactionToken
  6. 接下來,開發人員將相關資訊 (externalTransactionToken 值和使用者所購產品) 傳送到後端,然後在其他結帳系統中啟動 product 的購買流程。系統在開發人員端向此交易指派不重複的交易 ID (「123-456-789」),用於回報交易給 Google Play。雖然使用者享有免費試用期,但開發人員仍須提供交易 ID。
  7. 在其他結帳系統中進行販售商品的交易後,開發人員透過下列要求向 Google Play 回報交易。由於使用者可以免費試用一個月,因此最初回報的是零元交易。
POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=123-456-789

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },
"transactionTime" : "2022-02-22T12:45:00Z",
 "recurringTransaction" : {
   "externalTransactionToken": "my_token",
   "external_subscription" {
     "subscriptionType": "RECURRING"
   }
 },
 "userTaxAddress" : {
   "regionCode": "KR"
 }
}

回報消費後續的交易

在某些情況下,使用者完成單筆外部購買交易後會多次支付相關聯的款項,例如訂閱項目續訂或預付方案儲值。您可以在 Externaltransactions 中使用相同 API 回報這些後續交易。如「回報新交易」一節所述,回報後續交易時不必用到 externalTransactionToken,而是應針對每筆續訂或儲值交易傳送新的不重複 externalTransactionId 做為查詢參數,並在 initialExternalTransactionId 欄位中提供初始交易的 ID。

延續先前的例子:

  1. 使用者 1 在其他結帳系統中進行第一筆續訂交易。初始交易 ID 為「123-456-789」

  2. 開發人員在網址查詢參數中回報本次週期性新交易的外部交易 ID,並在 initialExternalTransactionId 欄位中參照初始交易的外部交易 ID。

要求示例:

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=abc-def-ghi

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "12634000000",
   "currency": "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros": "1263000000",
   "currency": "KRW"
 },
"transactionTime" : "2022-02-22T12:45:00Z",
 "recurringTransaction" : {
   "initialExternalTransactionId": "123-456-789",

   "external_subscription" {
     "subscriptionType": "RECURRING"
   }
 },
 "userTaxAddress" : {
   "regionCode": "KR"
 }
}

回報訂閱項目升級或降級

如要回報使用者在其他結帳系統中的訂閱項目升級或降級,請在 Externaltransactions API 中使用相同端點和函式,針對升級或降級交易傳送先前提供給應用程式的 externalTransactionToken。做法與回報新交易類似。

向 Google Play 回報交易退款

如要回報在 Google Play 結帳系統以外退款給使用者的交易,請整合 Externaltransactions API。為了讓 Google Play 正確識別已退款的交易,您應該在網址參數中加入先前所回報交易的相應 externalTransactionId

回報訂閱項目購買交易的退款時,請找出要退款的特定單次週期性訂閱交易,並參照該交易的 externalTransactionId

示例:假設訂閱項目包含下列交易:

  • 外部交易 ID 為「ABC.1234-5678-9012-34567」的初始交易

  • 外部交易 ID 為「ABC.1234-5678-9012-34567..0」的第一筆週期性交易

  • 外部交易 ID 為「ABC.1234-5678-9012-34567..1」的第二筆週期性交易

如要回報訂閱項目所有交易的退款,您需要分別提出三項要求:其中一項是初始交易的要求,另外兩項則是後續交易的要求。

這種做法適用於全額退款 (款項等同使用者在原先外部交易中支付的金額) 和部分退款 (款項少於使用者在原先外部交易中支付的金額)。辦理部分退款時,您需要指定退還的稅前金額。

API 配額

如同 Google Play Developer API 中的其他端點,Externaltransactions API 的所有呼叫都適用每日 API 配額限制。

此外,Externaltransactions API 向 Externaltransactions.createexternaltransactionExternaltransactions.refundexternaltransaction 發出呼叫時,每分鐘查詢數量 (QPM) 上限為 1,200。不過,向 Externaltransactions.getexternaltransaction 發出的呼叫不會計入 1,200 的 QPM 上限。