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

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 中重复使用。

对于一次性购买交易和周期性购买交易（例如订阅）中的首次交易，请求正文中还必须包含应用通过 UserChoiceBillingListener、AlternativeBillingOnlyReportingDetailsListener 或 ExternalOfferReportingDetailsListener 回调收到的 externalTransactionToken。这两种情况都称为“初始交易”。完成初始交易后，系统不再需要 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"
 }
}

如果与印度境内的用户进行交易，由于该国税费因用户所在的行政区（例如州或省）而异，请务必在 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"
 }
}

报告购买交易的后续交易

在某些情况下，同一外部购买交易有多笔相关联的用户付款（例如，续订或预付费方案充值）。您可以在 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。这与报告新购买交易类似。

不再手动报告备选结算系统交易

如需迁移您以非自动化报告方式提供备选结算系统期间开始的有效订阅，请使用 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"
 }
}

向 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 的限额。