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