备选结算系统的后端集成指南(仅限韩国)

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 位于韩国,并尝试以 12634.10 韩元/月的价格购买 product1(提供免费试用 1 个月的优惠)。
  3. 应用启动购买流程,并采用针对 product1ProductDetails 以及用户选择的优惠。
  4. 用户 1 选择开发者的备选结算系统。
  5. AlternativeBillingListener 收到 my_token 值作为 externalTransactionToken
  6. 然后,开发者将相关信息(externalTransactionToken 值和所购商品)发送到其后端,接着在备选结算系统中启动 product 的购买流程。此交易在开发者端获配一个唯一的交易 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",
   "external_subscription" {
     "subscriptionType": "RECURRING"
   }
 },
 "userTaxAddress" : {
   "regionCode": "KR"
 }
}

报告购买交易的后续交易

在某些情况下,同一外部购买交易有多笔相关联的用户付款(例如,续订或预付费方案充值)。您可以在 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",

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

报告升级或降级

若要当用户拥有一项订阅的情况下在备选结算系统中报告升级或降级,您可在 Externaltransactions API 中使用相同的端点和函数,发送为升级或降级交易而提供给应用的 externalTransactionToken。这与报告新购买交易类似。

向 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.createexternaltransactionExternaltransactions.refundexternaltransaction 时,Externaltransactions API 的每分钟查询数量 (QPM) 上限为 1200 个。对 Externaltransactions.getexternaltransaction 的调用不会计入此 1200 QPM 的限额。