Google Play 帳款服務以外的後端整合指南

Google Play Developer API 新增了回報結帳和連結計畫交易的功能。本指南說明如何回報這些結帳方案的交易。

您可能需要幾個元件，才能從後端處理外部交易。如要建構這些元件，請按照「設定 Google Play Developer API」的說明，設定後端整合作業。如要建構並非專屬於結帳和連結計畫的開發人員後端功能，請參閱 Google Play 結帳系統。

詞彙解釋

以下說明本指南使用的詞彙：

• 帳單和連結計畫：這類計畫可讓使用者在 Google Play 以外的平台購買數位內容或下載應用程式。包括其他結帳系統和外部優惠計畫。
• 外部交易 API：用於回報符合資格的帳單和連結計畫交易的 API。
• 外部交易：符合計畫規定的交易，但並非透過應用程式進行。包括購買數位內容和下載應用程式。
• 外部交易憑證：當使用者完成外部交易時，透過 Play 帳款服務程式庫提供給您使用的憑證。這類權杖可用於向 Google Play 傳送外部交易成功通知。
• 外部交易 ID：您為了識別外部交易而產生的不重複 ID。

向 Google Play 回報新的外部交易

整合 externaltransactions API 後，即可回報支援國家/地區在 Google Play 結帳系統以外進行的交易，包括因申請免費試用和安裝應用程式而產生的 $0 美元交易。只有在其他結帳系統或外部優惠指南許可的情況下，才能在符合資格的使用者國家/地區啟動並回報結帳和連結計畫的交易，否則 API 呼叫將遭到拒絕。這項限制適用於所有交易，包括新交易、續訂、儲值、升級和降級，以及應用程式下載。

回報外部交易

當付款交易透過結帳和連結計畫完成授權後，您應呼叫 externaltransactions API 回報外部交易。這適用於所有交易，包括收取初始費用、續訂和退款等等。如需報表規定，請參閱各帳單和連結計畫的指南。

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

回報初始交易

每當在結帳和連結計畫中成功完成新交易或應用程式下載時，都必須呼叫 externaltransactions API。

如果是應用程式下載、一次性消費，或是週期性消費 (例如訂閱) 的首次交易，要求主體也必須包含應用程式透過 UserChoiceBillingListener、AlternativeBillingOnlyReportingDetailsListener 或 BillingProgramReportingDetailsListener 回呼所收到的 externalTransactionToken。這稱為「初始交易」。初始交易完成後，請提供新的不重複 externalTransactionId 回報後續交易 (例如訂閱項目續訂)。如要進一步瞭解如何回報後續交易，請參閱「回報消費後續的交易」。

範例：

1. 開發人員在應用程式中設定並啟用其他結帳系統。
2. 韓國為支援這項服務的國家/地區，其境內的使用者 1 想購買 product1，這項產品的費用為每月 12634.10 韓元，並提供一個月免費試用優惠。
3. 應用程式根據 product1 的 ProductDetails 和使用者選擇的方案，啟動購買流程。
4. 使用者 1 選擇開發人員的其他結帳系統。
5. UserChoiceBillingListener 收到 my_token 值做為 externalTransactionToken。
6. 接下來，開發人員將相關資訊 (externalTransactionToken 值和使用者所購產品) 傳送到後端，然後在其他結帳系統中啟動 product1 的購買流程。系統在開發人員端為此交易指派不重複的交易 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",
   "externalSubscription" {
     "subscriptionType": "RECURRING"
   }
 },
 "userTaxAddress" : {
   "regionCode": "KR"
 }
}

回報初始交易時，請注意下列事項：

• subscriptionType 可以是 RECURRING (適用於自動續訂的訂閱項目) 或 PREPAID (適用於預付訂閱項目)。
• OtherRecurringProduct 必須用於代表需要多次付款或延遲付款的一次性購買交易。舉例來說，預購交易可能一開始為 $0，之後在預購商品出貨時，再進行第二筆交易，收取 SKU 的價格。如要進一步瞭解如何回報後續交易，請參閱「回報消費後續的交易」。
• 回報初始外部優惠交易時，請務必提供 ExternalOfferDetails。後續交易則不需提供這項資訊。

如果與印度使用者交易，稅金會依各別行政區 (例如州或省) 而異，請將該行政區加進 userTaxAddress。請參閱 API 參考指南中適用行政區的預先定義字串清單。

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=123-456-789

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "0",
   "currency": "INR"
 },
 "originalTaxAmount" : {
   "priceMicros": "0",
   "currency": "INR"
 },
"transactionTime" : "2023-11-01T12:45:00Z",
 "recurringTransaction" : {
   "externalTransactionToken": "my_token",
   "externalSubscription" {
     "subscriptionType": "RECURRING"
   }
 },
 "userTaxAddress" : {
   # Tax varies in India based on state, so include that information in
   # administrativeArea
   "regionCode": "IN"
   "administrativeArea": "KERALA"
 }
}

外部優惠

如果回報的交易屬於外部優惠計畫，且為一次性交易或週期性交易系列的第一筆交易，則必須設定 externalOfferDetails 欄位：

• 回報應用程式下載交易時，請將 linkType 設為 LINK_TO_APP_DOWNLOAD，並為 installedAppPackage 和 installedAppCategory 提供適當的值。詳情請參閱「回報應用程式下載次數」。
• 回報數位內容優惠交易時，請將 linkType 設為 LINK_TO_DIGITAL_CONTENT。
• 透過外部優惠計畫安裝外部應用程式後，您必須回報在外部應用程式中進行的交易。回報這些交易時，請將交易連結至原始應用程式下載事件：
  • 提供應用程式下載事件的 externalTransactionToken。
  • 在 externalOfferDetails 欄位中，將 appDownloadEventExternalTransactionId 設為應用程式下載事件的 externalTransactionId。externalOfferDetails 中的其他欄位則為選填。

透過外部優惠下載的外部應用程式交易要求示例：

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=ABC-DEF-GHI

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "100000",
   "currency": "EUR"
 },
 "originalTaxAmount" : {
   "priceMicros": "10000",
   "currency": "EUR"
 },
"transactionTime" : "2025-11-22T12:45:00Z",
 "oneTimeTransaction" : {
   "externalTransactionToken": my_external_transaction_token_for_link_to_download_event"
 },
 "userTaxAddress" : {
   "regionCode": "DE"
 },
 "externalOfferDetails" : {
   "appDownloadEventExternalTransactionId": "my_external_transaction_id_for_link_to_download_event"
 }
}

如要瞭解不同交易類型的最新 Play 服務費詳細資料，請參閱歐洲經濟區使用者外部優惠計畫異動。

回報消費後續的交易

在某些情況下，使用者完成單筆外部購買交易後會多次支付相關聯的款項，例如訂閱項目續訂或預付方案儲值。您可以在 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",

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

回報訂閱項目的升級或降級情形

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

回報應用程式下載次數

如要在外部優惠結帳系統中回報應用程式安裝次數，請呼叫 Externaltransactions.createexternaltransaction，並傳送提供給應用程式的 externalTransactionToken。請將此回報為零成本的一次性交易，這個程序與回報初始交易類似。請務必在要求主體中加入 ExternalOfferDetails。

要求示例：

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=123-456-789

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "0",
   "currency": "USD"
 },
 "originalTaxAmount" : {
   "priceMicros": "0",
   "currency": "USD"
 },
"transactionTime" : "2025-12-22T12:45:00Z",
 "oneTimeTransaction" : {
   "externalTransactionToken": "my_token",
 },
 "userTaxAddress" : {
   "regionCode": "US"
 }
 "externalOfferDetails" : {
   "linkType" : "LINK_TO_APP_DOWNLOAD",
   "installedAppPackage" : "my.external.app",
   "installedAppCategory" : "APP"
 }
}

從手動回報其他結帳系統交易遷移

如要遷移在提供其他結帳系統期間開始訂閱但未自動回報的有效項目，請使用 migratedTransactionProgram 欄位建立新的零費用交易，而不要指定 initialExternalTransactionId 或 externalTransactionToken。將 transactionTime 設為使用者註冊各個有效訂閱項目的初始時間。之後，照常透過 API 回報這些訂閱項目的每筆後續交易，並提供先前用於建立續訂交易的 initialExternalTransactionId。訂閱項目遷移後，只要透過本頁所述的自動化方法回報訂閱項目的後續交易，就不再需要手動回報這類交易。

遷移訂閱項目時，請留意設定的配額限制，確認遷移作業不會導致配額服務中斷。如果需要遷移大量訂閱項目，請將訂閱項目分散在數日遷移，或是要求增加配額。

migratedTransactionProgram 欄位只能用於從手動回報功能進行遷移，並且會在系統不再支援手動回報時淘汰。

要求示例：

# Note that the externalTransactionId specified here will used to report
# subsequent transactions.

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

Body
 {
 # Be sure to set the price to 0 for this transaction since it does not reflect
 # an actual subscription renewal.
 "originalPreTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },

 # The transaction time should be set to when the user signed up for this
 # subscription.
 "transactionTime" : "2022-02-22T12:45:00Z",
  "recurringTransaction" : {
    "migratedTransactionProgram": "USER_CHOICE_BILLING",

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

Play 合作夥伴計畫資格條件

如果開發人員參與Play 媒體體驗計畫等合作夥伴計畫，在回報外部交易時，必須提供 transaction_program_code。如果您是符合資格的開發人員，請與業務開發經理聯絡，進一步瞭解如何設定這個欄位。

向 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.createexternaltransaction 或 Externaltransactions.refundexternaltransaction 發出呼叫時，每分鐘查詢數量 (QPM) 上限為 1,200。不過，向 Externaltransactions.getexternaltransaction 發出的呼叫不會計入 1,200 QPM 的限制。