Voided Purchases API

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

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

在以下情况中,购买交易视为作废:

  • 用户针对其订单请求退款。
  • 用户取消其订单。
  • 订单被退款。
  • 开发者取消订单或针对订单办理退款。注意: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
每个响应中出现的已作废购买交易的数量上限。默认情况下,此值为 1000。请注意,此参数的最大值也是 1000。
token
之前响应中的继续令牌;可让您查看更多结果。
type

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

响应是一个 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 会针对每个软件包设置以下配额:

  • 每天 6000 次查询(一天是从太平洋时间午夜开始,并于次日同一时间结束)。
  • 在任何时长为 30 秒的期限内查询 30 次。

初次请求指南

在初次提交 API 请求时,您可能需要获取您应用的所有可用数据。虽然不太可能发生,但此流程还是有可能会将您的每日配额消耗一空。如需以更安全、更统一的方式来取得已作废购买交易的相关数据,请按以下最佳做法操作:

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

最佳做法

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

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