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
每個回應中顯示的作廢交易數量上限。根據預設,這個值為 1000。請注意,此參數的最大值也是 1000。
權杖
先前回應的接續權杖,可讓您檢視更多結果。
類型

每筆回應中顯示的作廢交易類型。如果設為 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 參數的預設值。這樣一來,如果當天使用全部的查詢配額,即可擷取 6,000,000 筆無效購買交易的詳細資料。
  • 如果回應包含 nextPageToken 的值,請在下次要求時將這個值指派給 token 參數。

最佳做法

在應用程式中使用這個 API 時,請記住停止購買交易有許多原因,而且沒有任何單一解決方案適用於所有情況。設計撤銷政策和策略時,建議您以使用者為考量。做法如下:

  • 制定全方位策略時,請將這個 API 做為眾多元素之一,以解決不尋常的行為。撤銷應用程式內產品的存取權通常會更有效,如果與具有合理價格的應用程式內購應用程式搭配使用的應用程式設計、應用程式設計防止不合適的行為、建立龐大使用者族群,並拒絕這類行為,以及回應迅速又有效的使用者支援管道,通常會更為有效。
  • 統一管理撤銷政策,確保所有使用者都能享有公平的體驗。
  • 考慮建立階段式政策來處理不當行為時。例如,從針對早期犯罪行為的應用程式內警告開始,再提報使用者的不當行為。在萬不得已的情況下,您可以完全禁止使用者與您的應用程式互動。
  • 當您推出撤銷政策時,每次更新時,請使用應用程式的外聯管道通知使用者相關異動。變更在應用程式中生效前,請讓使用者有時間瞭解。
  • 請向使用者公開透明,並在您採取動作時通知他們,例如撤銷使用者對應用程式內商品的存取權。在理想情況下,使用者應能夠對您的決定提出爭議,進而公平地處理這類爭議。
  • 監控意見回饋表單和社群論壇,瞭解使用者產生不當行為的原因和做法。根據這些深入分析採取行動,做為第一道防線。