Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang
Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.
API Giao dịch mua vô hiệu trên Google Play cung cấp danh sách các đơn đặt hàng
được liên kết với các giao dịch mua mà người dùng đã vô hiệu. Bạn có thể dùng thông tin
từ danh sách này để triển khai hệ thống thu hồi nhằm ngăn người dùng
truy cập vào sản phẩm trong các đơn đặt hàng đó.
API này áp dụng cho các đơn đặt hàng một lần trong ứng dụng và Gói thuê bao trong ứng dụng.
Một giao dịch mua có thể được vô hiệu theo các cách sau:
Người dùng yêu cầu hoàn tiền cho đơn đặt hàng.
Người dùng huỷ đơn đặt hàng.
Đơn đặt hàng được hoàn tiền.
Nhà phát triển huỷ hoặc hoàn tiền cho đơn đặt hàng.
Google huỷ hoặc hoàn tiền cho đơn đặt hàng.
Bằng cách sử dụng API này, bạn có thể tạo ra trải nghiệm cân bằng và công bằng hơn cho tất cả người dùng ứng dụng, đặc biệt nếu ứng dụng của bạn là một trò chơi.
Giành được quyền truy cập
Để làm việc với Voided Purchases API, bạn cần có quyền xem
thông tin tài chính. Bạn cấp quyền bằng ứng dụng OAuth hoặc
tài khoản dịch vụ của bạn. Nếu bạn đang sử dụng tài khoản dịch vụ, hãy bật nút "Xem thông tin tài chính
báo cáo" quyền trong tài khoản này.
Để tìm hiểu thêm về cách nhận quyền truy cập được cấp phép vào API Nhà phát triển Google Play, hãy xem
các hướng dẫn sau:
Sử dụng phương thức GET để yêu cầu danh sách các giao dịch mua vô hiệu. Trong yêu cầu của bạn,
đưa vào tên gói đủ điều kiện cho ứng dụng của bạn, chẳng hạn như
com.google.android.apps.maps—và mã thông báo uỷ quyền
nhận được khi có quyền truy cập vào API.
GET https://www.googleapis.com/androidpublisher/v3/applications/
your_package_name/purchases/voidedpurchases?access_token=your_auth_token
Bạn cũng có thể thêm các thông số sau vào yêu cầu của mình, mỗi thông số
tuỳ chọn:
startTime
Thời gian tính bằng mili giây kể từ thời gian bắt đầu của hệ thống Unix của thời gian
giao dịch mua vô hiệu mà bạn muốn xem trong phản hồi. Theo mặc định,
startTime được đặt thành 30 ngày trước.
API chỉ có thể hiển thị các giao dịch mua vô hiệu đã xảy ra trong quá khứ
30 ngày. Các giao dịch mua hàng cũ vô hiệu sẽ không được đưa vào phản hồi, bất kể
giá trị bạn đã cung cấp cho startTime.
endTime
Thời gian tính bằng mili giây kể từ thời gian bắt đầu của hệ thống Unix của
giao dịch mua vô hiệu mà bạn muốn xem trong phản hồi. Theo mặc định,
endTime đã được đặt thành thời gian hiện tại.
kết quả tối đa
Số lượng giao dịch mua vô hiệu tối đa xuất hiện trong mỗi câu trả lời. Theo
mặc định, giá trị này là 1000. Xin lưu ý rằng giá trị tối đa cho thông số này là
1000.
mã thông báo
Mã thông báo tiếp tục từ câu trả lời trước, cho phép bạn xem thêm
kết quả.
loại
Loại giao dịch mua vô hiệu xuất hiện trong mỗi câu trả lời. Nếu đặt là 0,
chỉ những giao dịch mua hàng trong ứng dụng vô hiệu mới được trả lại. Nếu bạn đặt chính sách này là 1, thì cả hai giá trị này trong ứng dụng đều bị vô hiệu
các giao dịch mua và giao dịch mua gói thuê bao vô hiệu sẽ được trả lại. Giá trị mặc định là
0.
includeQuantityBasedPartialRefund
Liệu có bao gồm các giao dịch mua hàng vô hiệu đối với khoản hoàn tiền một phần theo số lượng hay không,
Ưu đãi này chỉ áp dụng cho giao dịch mua số lượng nhiều. Nếu giá trị là true,
voidedQuantity có thể trả lại các giao dịch mua vô hiệu bổ sung
cho biết số tiền hoàn lại của một khoản tiền hoàn lại một phần theo số lượng. Chiến lược phát hành đĩa đơn
giá trị mặc định là false.
Phản hồi là một chuỗi JSON chứa danh sách các giao dịch mua vô hiệu. Nếu có
có nhiều kết quả hơn số kết quả đã chỉ định trong tham số yêu cầu maxResults
, phản hồi sẽ bao gồm giá trị nextPageToken mà bạn có thể chuyển vào
để yêu cầu xem thêm kết quả. Kết quả đầu tiên trong danh sách cho thấy
giao dịch mua vô hiệu cũ nhất.
Voided Purchases API đặt các hạn mức sau đây cho từng gói:
6000 truy vấn mỗi ngày. (Ngày bắt đầu và kết thúc lúc nửa đêm theo Giờ Thái Bình Dương.)
30 truy vấn trong khoảng thời gian 30 giây bất kỳ.
Nguyên tắc đối với các yêu cầu ban đầu
Trong yêu cầu API ban đầu của mình, bạn có thể muốn tìm nạp tất cả dữ liệu có sẵn cho
ứng dụng của bạn. Mặc dù ít có khả năng nhưng quá trình này có thể làm cạn kiệt hạn mức hằng ngày của bạn. Người nhận
thu thập dữ liệu về các giao dịch mua hàng vô hiệu theo cách an toàn và nhất quán hơn, hãy làm theo
các phương pháp hay nhất:
Sử dụng giá trị mặc định cho tham số maxResults. Bằng cách đó, nếu bạn sử dụng
toàn bộ hạn mức truy vấn của bạn trong một ngày, bạn có thể truy xuất thông tin chi tiết là 6.000.000
các giao dịch mua hàng vô hiệu.
Nếu câu trả lời có chứa giá trị cho nextPageToken, hãy chỉ định giá trị này cho
token trong yêu cầu tiếp theo.
Các phương pháp hay nhất
Khi sử dụng API này trong ứng dụng của bạn, hãy nhớ rằng có rất nhiều
lý do để vô hiệu hoá một giao dịch mua và không có giải pháp nào hiệu quả trong
mọi trường hợp. Bạn nên cân nhắc đến người dùng khi thiết kế
quy trình thu hồi
chính sách và chiến lược của mình. Để làm như vậy, bạn có thể áp dụng các phương pháp được đề xuất sau:
Sử dụng API này như một trong nhiều yếu tố trong một chiến lược toàn diện để giải quyết
hành vi không mong muốn. Việc thu hồi quyền truy cập vào sản phẩm trong ứng dụng thường hiệu quả hơn
khi được kết hợp với một ứng dụng có mức giá hợp lý cho lượt mua hàng trong ứng dụng,
thiết kế ứng dụng ngăn chặn hành vi không mong muốn, một cơ sở người dùng mạnh mẽ
văn hoá từ chối hành vi như vậy và hỗ trợ người dùng phản hồi nhanh chóng và hiệu quả
các kênh.
Quản lý chính sách thu hồi của bạn một cách thống nhất để đảm bảo sự công bằng cho tất cả người dùng.
Hãy cân nhắc tạo một chính sách theo giai đoạn khi xử lý các hành vi không mong muốn. Cho
Ví dụ: bắt đầu bằng các cảnh báo trong ứng dụng
đối với các trường hợp vi phạm sớm, sau đó báo cáo
các phản hồi khi hành vi không mong muốn của người dùng vẫn tiếp tục. Khi không còn cách nào khác, bạn có thể
ngăn người dùng tương tác với ứng dụng của bạn.
Khi bạn đưa ra chính sách thu hồi và mỗi lần cập nhật chính sách này, hãy sử dụng
các kênh tiếp cận khác của ứng dụng để thông báo cho người dùng về các thay đổi. Cung cấp cho người dùng của bạn
bạn cần dành thời gian để hiểu rõ những thay đổi này trước khi chúng có hiệu lực trong ứng dụng của bạn.
Hãy minh bạch với người dùng và thông báo cho họ bất cứ khi nào bạn thực hiện hành động, chẳng hạn như
thu hồi quyền truy cập của họ vào sản phẩm trong ứng dụng. Tốt nhất là người dùng có thể
tranh chấp quyết định của mình và những tranh chấp đó sẽ được xử lý công bằng.
Theo dõi các biểu mẫu phản hồi và diễn đàn cộng đồng để nắm được những điều thúc đẩy người dùng
chúng hành xử theo cách không mong muốn và cách chúng thực hiện hành vi đó. Hành động dựa trên các
thông tin chuyên sâu là tuyến phòng vệ đầu tiên.
[null,null,["Cập nhật lần gần đây nhất: 2025-07-26 UTC."],[[["\u003cp\u003eThe Google Play Voided Purchases API lets you track voided in-app purchases and subscriptions to implement revocation systems, ensuring a fair user experience.\u003c/p\u003e\n"],["\u003cp\u003eVoided purchases include user refunds, cancellations, chargebacks, and cancellations/refunds by the developer or Google.\u003c/p\u003e\n"],["\u003cp\u003eAccess the API using OAuth or a service account with "View financial reports" permission and make requests with your package name and authorization token.\u003c/p\u003e\n"],["\u003cp\u003eTailor your revocation policies to be fair and transparent, escalating responses as needed while informing users of any actions taken.\u003c/p\u003e\n"],["\u003cp\u003eCombine this API with other strategies and real-time notifications for a comprehensive approach to managing user entitlements and addressing undesirable behaviors.\u003c/p\u003e\n"]]],["The Google Play Voided Purchases API lists orders linked to user-voided purchases, including refunds, cancellations, chargebacks, and developer/Google-initiated voids. This API helps developers implement revocation systems to prevent access to products from voided orders. To use it, developers need \"View financial reports\" permission and can use a `GET` method to request voided purchases, filtering by time, quantity, or type. It has quotas, provides best practices and advises using it along side RTDN.\n"],null,["# Voided Purchases API\n\nThe Google Play Voided Purchases API provides a list of orders that\nare associated with purchases that a user has voided. You can use information\nfrom this list to implement a revocation system that prevents the user from\naccessing products from those orders.\n\nThis API applies to one-time in-app orders and App Subscriptions.\n\nA purchase can be voided in the following ways:\n\n- The user requests a refund for their order.\n- The user cancels their order.\n- An order is charged back.\n- Developer cancels or refunds order.\n\n | **Note:** only revoked orders will be shown in the Voided Purchases API. If a developer refunds a purchase without setting the revoke option, the order will not be returned by the API.\n- Google cancels or refunds order.\n\nBy using this API, you help create a more balanced and fair experience for all\nof your app's users, particularly if your app is a game.\n| **Note:** Unlike other order-related data sources, the Voided Purchases API includes purchases that are charged back by payment processors. Therefore, you might see inconsistencies between the information from this API and information from other order-related data sources.\n| **Note:** The Voided Purchases API returns voided purchases only when they need to be revoked. Developers can use this API as an indication for when to take additional action on their end. However, some purchases may be refunded with reason that the purchase was never acknowledged by the developer, and therefore may not exist in the developer's records.\n\nGaining Access\n--------------\n\nTo work with the Voided Purchases API, you need to have permission to view\nfinancial information. You provide authorization using an OAuth client or a\nservice account. If you're using a service account, enable the \"View financial\nreports\" permission within this account.\n\nTo learn more about gaining authorized access to Google Play Developer APIs, see\nthe following guides:\n\n- [Setting Up API Access Clients](/android-publisher/getting_started#setting_up_api_access_clients)\n- [Add developer account users \\& manage permissions](https://support.google.com/googleplay/android-developer/answer/2528691)\n\nViewing Voided Purchases\n------------------------\n\nUse the `GET` method to request a list of voided purchases. In your request,\ninclude the fully-qualified package name for your app---such as\n`com.google.android.apps.maps`---and the authorization token you\nreceived when [gaining access](#gaining_access) to the API. \n\n```\nGET https://www.googleapis.com/androidpublisher/v3/applications/\nyour_package_name/purchases/voidedpurchases?access_token=your_auth_token\n```\n\nYou can also include the following parameters in your request, each of which is\noptional:\n\nstartTime\n\n: The time, in milliseconds since the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time), of the oldest\n voided purchase that you want to see in the response. By default,\n `startTime` is set to 30 days ago.\n\n The API can only show voided purchases that have occurred during the past\n 30 days. Older voided purchases are not included in the response, regardless\n of the value that you've provided for `startTime`.\n | **Note:** The voided purchases within the response are filtered based on the time at which a given record is seen as voided by the API, not by the value of `voidedTimeMillis` returned in the response.\n\nendTime\n\n: The time, in milliseconds since the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time), of the newest\n voided purchase of that you want to see in the response. By default,\n `endTime` is set to the current time.\n\n | **Note:** The voided purchases within the response are filtered based on the time at which a given record is seen as voided by the API, not by the value of `voidedTimeMillis` returned in the response.\n\nmaxResults\n: The maximum number of voided purchases that appear in each response. By\n default, this value is 1000. Note that the maximum value for this parameter is\n also 1000.\n\ntoken\n: A continuation token from a previous response, allowing you to view more\n results.\n\ntype\n\n: The type of voided purchases that appear in each response. If set to 0,\n only voided in-app purchases will be returned. If set to 1, both voided in-app\n purchases and voided subscription purchases will be returned. Default value is\n 0.\n\n | **Note:** Before requesting to receive voided subscription purchases, you must switch to use orderId in the response which uniquely identifies one-time purchases and subscriptions. Otherwise, you will receive multiple subscription orders with the same PurchaseToken.\n\nincludeQuantityBasedPartialRefund\n\n: Whether to include voided purchases of quantity-based partial refunds,\n which are applicable only to multi-quantity purchases. If `true`,\n additional voided purchases may be returned with `voidedQuantity`\n that indicates the refund quantity of a quantity-based partial refund. The\n default value is `false`.\n\n | **Note:** When the remaining total quantity of a purchase is refunded, the corresponding voided purchase won't have `voidedQuantity`, which serves as a signal that the purchase has been fully refunded. For example, if a purchase of quantity 10 is refunded 3 times with quantities 2, 3 and 5, there will be 3 voided purchases. The first two voided purchases will have a `voidedQuantity` of 2 and 3, while the third voided purchase *will not* have a `voidedQuantity`.\n\nThe response is a JSON string that contains a list of voided purchases. If there\nare more results than the number specified in the `maxResults` request parameter\n, the response includes a `nextPageToken` value, which you can pass into a\nsubsequent request to view more results. The first result in the list shows the\noldest voided purchase. \n\n```\n{\n \"tokenPagination\": {\n \"nextPageToken\": \"next_page_token\"\n },\n \"voidedPurchases\": [\n {\n \"kind\": \"androidpublisher#voidedPurchase\",\n \"purchaseToken\": \"some_purchase_token\",\n \"purchaseTimeMillis\": \"1468825200000\",\n \"voidedTimeMillis\": \"1469430000000\",\n \"orderId\": \"some_order_id\",\n \"voidedSource\": \"0\",\n \"voidedReason\": \"4\"\n },\n {\n \"kind\": \"androidpublisher#voidedPurchase\",\n \"purchaseToken\": \"some_other_purchase_token\",\n \"purchaseTimeMillis\": \"1468825100000\",\n \"voidedTimeMillis\": \"1470034800000\",\n \"orderId\": \"some_other_order_id\",\n \"voidedSource\": \"2\",\n \"voidedReason\": \"5\"\n },\n ]\n}\n```\n\nQuotas\n------\n\nThe Voided Purchases API sets the following quotas on a per-package basis:\n\n- 6000 queries per day. (The day begins and ends at midnight Pacific Time.)\n- 30 queries during any 30-second period.\n\n### Guidelines for initial requests\n\nDuring your initial API request, you may want to fetch all available data for\nyour app. Although unlikely, this process could exhaust your daily quota. To\nobtain voided purchases data in a safer, more consistent manner, follow these\nbest practices:\n\n- Use the default value for the `maxResults` parameter. That way, if you use your entire query quota for a day, you can retrieve the details of 6,000,000 voided purchases.\n- If a response includes a value for `nextPageToken`, assign this value to the `token` parameter during your next request.\n\nBest Practices\n--------------\n\n| **Note:** In addition to using this API, developers should integrate with [Real-time developer notifications (RTDN)](https://developer.android.com/google/play/billing/getting-ready#configure-rtdn). With RTDN, you receive notifications from Google whenever there is a change in a user's entitlement within your app, including when a user [voids a purchase](https://developer.android.com/google/play/billing/rtdn-reference#voided-purchase).\n\nWhen using this API in your app, remember that there are many\nreasons to void a purchase and that there is no single solution that works in\nall cases. You should keep your users in mind when designing your revocation\npolicies and strategies. To do so, you can apply these recommended practices:\n\n- Use this API as one of many elements in a comprehensive strategy to address undesired behavior. Revoking access to in-app products is usually more effective when combined with an app that has reasonable prices for in-app purchases, an app design that discourages undesirable behavior, a strong user base whose culture rejects such behavior, and responsive and efficient user support channels.\n- Administer your revocation policy uniformly to ensure fairness for all users.\n- Consider creating a staged policy when addressing undesired behavior. For example, start with in-app warnings for early offenses, then escalate your responses as a user's undesired behavior continues. As a last resort, you can prevent a user from interacting with your app at all.\n- When you introduce a revocation policy, and each time you update it, use your app's outreach channels to inform your users about the changes. Give your users time to clearly understand these changes before they take effect in your app.\n- Be transparent to your users and inform them whenever you take action, such as revoking their access to an in-app product. Ideally, users should be able to dispute your decisions, and such disputes should be treated fairly.\n- Monitor feedback forms and community forums to understand what drives users to behave in undesirable ways and how they carry out such behavior. Act on these insights as a first line of defense."]]
