Voided Purchases API

Google Play Voided Purchases API 提供了一个订单列表，这些订单与用户已作废的购买交易相关联。您可以利用此列表中的信息来实现一个撤消系统，阻止用户访问这些订单中的商品。

此 API 适用于一次性应用内订单和应用订阅。

在以下情况中，购买交易将被视为作废：

  • 用户针对其订单请求退款。
  • 用户取消其订单。
  • 订单遭到退单。

  • 开发者取消订单或针对订单办理退款。

  • Google 取消订单或针对订单办理退款。

通过使用此 API，您可以为应用的所有用户打造更平衡且公平的体验，尤其是当您的应用属于游戏时。

获得访问权限

如要使用 Voided Purchases API，您需要拥有查看财务信息的权限。您可以使用 OAuth 客户端或服务账号来提供授权。如果您使用的是服务账号，请在此账号中启用“查看财务报告”权限。

如要详细了解如何获得授权以访问 Google Play Developer API，请参阅以下指南：

查看已作废的购买交易

使用 GET 方法请求提供已作废购买交易的列表。在请求中，请加入您的应用的完全限定软件包名称（如 com.google.android.apps.maps），以及您在获取 API 访问权限时收到的授权令牌。

GET https://www.googleapis.com/androidpublisher/v3/applications/
your_package_name/purchases/voidedpurchases?access_token=your_auth_token

您还可以在请求中加入以下参数（各参数均为可选）：

startTime

您想在响应中看到的最早作废的购买交易的时间（以自 UNIX 纪元以来的毫秒数表示）。默认情况下，startTime 设为 30 天前。

此 API 只能显示在过去 30 天内发生的已作废购买交易。无论您将 startTime 设成什么值，更早的已作废购买交易都不会包含在响应中。

endTime

您想在响应中看到的最晚作废的购买交易的时间（以自 UNIX 纪元以来的毫秒数表示）。默认情况下，endTime 设为当前时间。

maxResults
每个响应中出现的已作废购买交易的数量上限。默认情况下，此值为 1,000。请注意，此参数的最大值也是 1,000。
token
之前响应中的续页令牌；可让您查看更多结果。
type

每个响应中出现的已作废购买交易的类型。如果设为 0，则系统只会返回已作废的应用内购买交易。如果设为 1，则系统将返回已作废的应用内购买交易和已作废的订阅购买交易。默认值为 0。

includeQuantityBasedPartialRefund

是否包括发生了基于数量的部分退款（仅适用于多件购买交易）的已作废购买交易。如果为 true，则可能会返回额外的已作废购买交易以及 voidedQuantity，后者表示基于数量的部分退款的退款数量。默认值为 false。

响应是一个 JSON 字符串，其中包含已作废购买交易的列表。如果结果数量超过了在 maxResults 请求参数中指定的数量，响应就会包含一个 nextPageToken 值，您可以将该值传递给后续请求来查看更多结果。列表中的第一个结果显示的是最早作废的购买交易。

{
  "tokenPagination": {
    "nextPageToken": "next_page_token"
  },
  "voidedPurchases": [
    {
      "kind": "androidpublisher#voidedPurchase",
      "purchaseToken": "some_purchase_token",
      "purchaseTimeMillis": "1468825200000",
      "voidedTimeMillis": "1469430000000",
      "orderId": "some_order_id",
      "voidedSource": "0",
      "voidedReason": "4"
    },
    {
      "kind": "androidpublisher#voidedPurchase",
      "purchaseToken": "some_other_purchase_token",
      "purchaseTimeMillis": "1468825100000",
      "voidedTimeMillis": "1470034800000",
      "orderId": "some_other_order_id",
      "voidedSource": "2",
      "voidedReason": "5"
    },
  ]
}

配额

Voided Purchases API 会针对每个软件包设置以下配额：

  • 每天查询不超过 6,000 次（一天是从太平洋时间午夜开始，并于次日同一时间结束）。
  • 在任何时长为 30 秒的期限内，查询不超过 30 次。

初次请求指南

初次提交 API 请求时，您可能需要获取应用的所有可用数据。此流程有可能会将您的每日配额消耗一空，不过这种情况不太可能出现。如需以更安全、更统一的方式获取已作废购买交易的相关数据，请按以下最佳实践进行操作：

  • 使用 maxResults 参数的默认值。这样一来，如果您将一天的查询配额全部用尽，便可检索 600 万笔已作废购买交易的详细信息。
  • 如果响应包含 nextPageToken 的值，请在下次提交请求期间将此值赋予 token 参数。

最佳实践

在您的应用中使用此 API 时，请注意，将购买交易作废的原因是多种多样的，并没有任何单一的解决方案可以适用于所有情况。设计撤消政策和策略时，应时刻为用户着想。为此，您可以采取以下推荐做法：

  • 使用此 API 作为综合策略中的众多要素之一来应对不良行为。在下列情况下，撤消对应用内商品的访问权限通常会更有效：应用的应用内购商品价格合理；应用设计有助于抑制不良行为；有一个强大的用户群，该用户群所接受的文化会摒弃不良行为；用户支持渠道响应迅速且富有效率。
  • 统一管理撤消政策，确保公平对待所有用户。
  • 解决不良行为时，考虑创建分阶段策略。例如，对早期违规行为进行应用内警告，并在用户继续进行不良行为时升级响应措施。作为终极措施，您可以彻底阻止用户与您的应用进行互动。
  • 引入撤消政策后，每次更新此政策时，均通过应用的推广渠道将相关更改通知给用户。先为用户留出充足的时间来清楚了解这些更改，然后再让更改在应用中生效。
  • 对用户开诚布公，并在每次采取措施（例如撤消用户对某个应用内商品的访问权限）时通知用户。理想情况下，用户应能针对您的决定提出异议，并且此类异议应受到公平对待。
  • 监控反馈表单和社区论坛，以了解导致用户出现不良行为的原因，及其采取此类行为的方式。根据这些数据分析采取措施，并以此作为第一道防线。