Google Play 开发者 API 现在包含其他功能，用于报告来自 替代计费 或 外部优惠 系统的交易。本指南介绍如何报告替代计费或外部优惠交易。
处理应用内购买可能需要一些后端组件。要构建它们，您需要按照 配置 Google Play 开发者 API 中的说明设置后端集成。对于不特定于替代计费或外部优惠 API 的所有开发者后端功能，均适用 Google Play 计费系统文档 中的说明。
向 Google Play 报告新的外部交易
与 Externaltransactions API 集成以报告在受支持国家/地区 Google Play 计费系统之外发生的交易，包括来自免费试用购买的 0 美元交易。仅应针对符合条件的用户国家/地区启动和报告替代计费或外部优惠系统上的交易，前提是根据 替代计费 或 外部优惠 计划允许，否则 API 调用将被拒绝。这适用于所有交易，包括新购买、续订、充值、升级、降级等。
外部交易报告
在通过替代计费或外部优惠系统授权付款后，您应调用 Externaltransactions API 来报告外部交易。这适用于所有交易，包括初始收费、续订、退款等。所有交易都必须在交易发生后 24 小时内报告。
每个外部交易都使用外部交易 ID 进行报告。对于经常性购买（例如自动续订订阅），您需要将与经常性购买中的第一笔交易关联的外部交易 ID 作为任何后续交易（包括退款）的参数发送。这会记录该购买的一系列交易。当产品发生更改（例如升级或降级）时，或者如果经常性交易被取消或过期且同一产品稍后再次购买，则您会为购买发送新的外部交易 ID。您不得将任何个人身份信息、专有信息或机密信息作为此外部交易 ID 的一部分。
报告新购买
每次在替代计费或外部优惠系统中成功进行新购买时，都需要调用 Externaltransactions API。对于这些新购买，您需要在后端提供与购买关联的唯一externalTransactionId 作为查询参数。externalTransactionId 不能在同一应用的包 ID 内重复使用。
通过 UserChoiceBillingListener、AlternativeBillingOnlyReportingDetailsListener 或 ExternalOfferReportingDetailsListener 回调收到的 externalTransactionToken 也是一次性购买和经常性购买（例如订阅）中的首次交易请求正文的一部分。在这两种情况下，这都称为初始交易。初始交易后，externalTransactionToken 将不再需要，您可以通过提供新的唯一 externalTransactionId 来报告后续交易（例如订阅续订）。有关如何报告后续交易的更多详细信息，请参阅报告购买的后续交易。
示例:
- 开发者在其应用中配置并启用替代计费。
- 用户1位于韩国（受支持国家/地区），正在尝试购买
product1，价格为12634.10韩元/月，并提供为期一个月的免费试用。 - 应用启动购买流程，其中包含
product1的ProductDetails以及用户选择的优惠。 - 用户1选择开发者的替代计费系统。
UserChoiceBillingListener接收值为my_token的externalTransactionToken。- 然后，开发者将其相关信息发送到其后端（
externalTransactionToken值和正在购买的产品）。然后，他们在替代计费系统中启动product1的购买流程。此交易在开发者端分配一个唯一的交易 ID 用于向 Google Play 报告：123-456-789。即使用户正在享受免费试用，也需要交易 ID。 - 在替代计费系统中完成购买交易后，开发者会使用以下请求向 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"
}
}
如果与居住在印度的用户进行交易，而税收因其行政区域（如州或省份）而异，则务必在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作为查询参数，并在initialExternalTransactionId字段中包含初始交易的 ID。
以下是之前的示例
- 用户1的第一次续订发生在替代计费系统中。初始交易 ID 为123-456-789。
- 开发者在 URL 查询参数中报告交易循环作为此新交易的外部交易 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。将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作为 URL 参数的一部分包含在内。
报告订阅购买退款时，请参考正在退款的订阅特定循环的externalTransactionId。
示例：假设订阅具有以下交易
- 具有外部交易 ID ABC.1234-5678-9012-34567 的初始交易
- 具有外部交易 ID ABC.1234-5678-9012-34567..0 的第一次循环交易
- 具有外部交易 ID ABC.1234-5678-9012-34567..1 的第二次循环交易
要报告订阅的所有交易的退款，您需要发出三个单独的退款请求：一个用于初始交易，两个用于后续交易。
此方法同时接受全额退款（其中金额与用户在原始外部交易中支付的金额相同）和部分退款（其中金额小于用户在原始外部交易中支付的金额）。对于部分退款，您需要指定已退款的税前金额。
API 配额
Externaltransactions API 适用于每日 API 配额，所有调用均如此，就像 Google Play 开发者 API 中的任何其他端点一样。
此外，Externaltransactions API 对Externaltransactions.createexternaltransaction或Externaltransactions.refundexternaltransaction的调用有每分钟 1200 次查询 (QPM) 的限制。Externaltransactions.getexternaltransaction 的调用不计入这 1200 次 QPM 限制。