有关 Google Play 结算服务之外的变现的后端集成指南

Google Play Developer API 包含额外的功能，可报告来自结算和关联计划的交易。本指南介绍了如何报告这些结算计划中的交易。

从后端处理外部交易时，可能需要用到一些组件。如需构建这些组件，您需要按照配置 Google Play Developer API 中的说明设置后端集成。如需构建并非特定于结算和关联计划的开发者后端功能，请参阅 Google Play 结算系统。

术语词汇表

本指南使用的惯用术语：

  • 结算和链接计划：有助于在 Google Play 之外购买数字内容或下载应用的计划。这包括备选结算系统和外部优惠计划。
  • 外部交易 API：用于报告符合条件的结算和关联计划的交易的 API。
  • 外部交易：根据计划要求，在应用之外发生的符合条件的交易。包括数字内容购买交易和应用下载。
  • 外部交易令牌：通过 Play 结算库向您提供的令牌，供您在用户完成外部交易时使用。此令牌用于通知 Google Play 有一笔外部交易已成功完成。
  • 外部交易 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 韩元/月，并可获得 1 个月的免费试用优惠。
  3. 应用启动购买流程，并采用针对 product1 的 ProductDetails 以及用户选择的优惠。
  4. 用户 1 选择开发者的备选结算系统。
  5. UserChoiceBillingListener 收到 my_token 值作为 externalTransactionToken。
  6. 然后，开发者将相关信息（externalTransactionToken 值和所购商品）发送到其后端，接着在备选结算系统中启动 product1 的购买流程。此交易在开发者端获配一个唯一的交易 ID (123-456-789)，用于向 Google Play 报告。即使用户正在免费试用商品，开发者也必须提供交易 ID。
  7. 在备选结算系统中发生购买交易后，开发者会使用以下请求向 Google Play 报告该交易。最初报告一笔金额为 0 美元的交易，因为用户会免费享用一个月。
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 服务费详情，请参阅面向欧洲经济区 (EEA) 用户的外部优惠计划的变更。

报告购买交易的后续交易

在某些情况下，同一外部购买交易有多笔相关联的用户付款，例如续订或预付费方案充值。 您可以在 Externaltransactions 中使用同一 API 报告这些后续交易。如报告新购买交易中所述，后续交易不需要 externalTransactionToken。不过，系统会为每笔续订或充值交易发送新的唯一 externalTransactionId 作为查询参数，并将初始交易的 ID 包含在 initialExternalTransactionId 字段中。

接着之前的示例：

  1. 用户 1 的首次续订发生在备选结算系统中。初始交易 ID 为 123-456-789。
  2. 开发者将网址查询参数中的周期性交易 ID 报告为这笔新交易的外部交易 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）创建一笔新的 0 费用交易。将每项有效订阅的 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 报告购买交易退款

与 externaltransactions API 集成后，您可报告在 Google Play 结算系统以外向用户退款的交易。为了让 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.createexternaltransaction 或 Externaltransactions.refundexternaltransaction 时，Externaltransactions API 的每分钟查询数量 (QPM) 上限为 1,200 个。对 Externaltransactions.getexternaltransaction 的调用不会计入此 1,200 QPM 的限额。