Khi một giao dịch mua trên Google Play được hoàn tiền hoặc bị chargeback, Voided Purchases API là cách bạn biết được điều đó

Một khoản hoàn tiền trên Google Play không gõ cửa nhà bạn. Tiền được chuyển đi, khách hàng vẫn mở ứng dụng, và trừ khi bạn đi tìm, không có gì thay đổi ở phía bạn. Voided Purchases API là nơi bạn đi tìm. Nó đưa cho bạn một danh sách các đơn hàng đã bị hủy, hoàn tiền hoặc chargeback, để bạn có thể thu hồi quyền truy cập vào thứ mà khách hàng không còn trả tiền nữa. Hướng một scheduled job vào đó, đọc danh sách, cắt entitlement. Đó là toàn bộ vòng lặp.

Có một cái bẫy khiến hầu hết các nhóm vấp phải, và nó không nằm trong code. Chỉ những đơn hàng đã được revoke mới hiển thị ở đây. Nếu bạn hoàn tiền một giao dịch mua trong Play Console mà không tích tùy chọn revoke, đơn hàng đó sẽ không bao giờ đến được API này, và job của bạn chạy trơn tru trong khi một khách hàng đã được hoàn tiền vẫn giữ mọi thứ bạn đã bán cho họ. Bài viết này đi qua API theo từng field, những con số giới hạn nó, và nơi tiền rò rỉ khi bạn bỏ qua nó.

Voided Purchases API thực sự trả về những gì

API trả lời một câu hỏi: những đơn hàng nào của ứng dụng này gần đây đã bị hủy. Một lần hủy (void) bao gồm ba kết cục đều kết thúc bằng việc khách hàng lấy lại tiền. Một lần hủy, một lần hoàn tiền, hoặc một lần chargeback. Nó áp dụng cho các sản phẩm trong ứng dụng mua một lần và cho các đăng ký, và bạn chọn phạm vi bằng một tham số duy nhất. Đặt type bằng 0 và bạn chỉ nhận được các giao dịch mua sản phẩm trong ứng dụng bị hủy, đây là mặc định. Đặt bằng 1 và bạn nhận được cả các giao dịch mua trong ứng dụng bị hủy lẫn các giao dịch mua đăng ký bị hủy.

Mỗi mục trong danh sách là một đối tượng voided purchase. Các field thì ít và mỗi field đều quan trọng.

Các field trên một voided purchase

Đọc voidedReason trước khi bạn hành động

voidedReason là field biến một danh sách thô thành một quyết định. Một khoản hoàn tiền do hối tiếc của người mua và một khoản chargeback từ ngân hàng đều rơi vào cùng một danh sách, nhưng chúng không phải là cùng một sự kiện, và bảng giá tháng Tám khiến một trong số chúng trở nên đắt đỏ. Đây là bộ đầy đủ.

Cửa sổ 30 ngày là cái bẫy làm rỗng danh sách của bạn

Voided Purchases API chỉ có thể hiển thị các giao dịch mua bị hủy trong 30 ngày qua. Tham số startTime mặc định bằng thời điểm hiện tại trừ đi 30 ngày, và không thể đặt cũ hơn thế. endTime mặc định là bây giờ. Vì vậy endpoint là một cửa sổ một tháng cuộn, không phải một kho lưu trữ.

Hệ quả rất thẳng thừng. Nếu polling job của bạn hỏng và không ai nhận ra trong năm tuần, các lần hủy từ tuần đầu tiên đã hết hạn khỏi API. Không có lệnh gọi nào mang chúng trở lại. Bạn sẽ không thu hồi những đơn hàng đó, và bạn thậm chí sẽ không biết chúng từng tồn tại trừ khi bạn đã ghi lại chúng bằng cách khác. API là một tấm lưới an toàn với một cái lỗ có kích cỡ bằng lần gián đoạn tồi tệ nhất của bạn.

Tùy chọn revoke quyết định liệu một đơn hàng có xuất hiện hay không

Đây là lý do phổ biến nhất khiến một nhóm báo cáo API bị hỏng. Chỉ những đơn hàng đã revoke mới được trả về. Các khoản hoàn tiền do người dùng khởi tạo, các lần hủy, các lần chargeback, và các khoản hoàn tiền do Google khởi tạo luôn được revoke, vì vậy chúng luôn xuất hiện. Một khoản hoàn tiền do nhà phát triển khởi tạo thì khác. Khi bạn tự hoàn tiền một đơn hàng, qua Play Console hoặc Orders API, bạn chọn có revoke nó hay không. Hoàn tiền mà không revoke, và đơn hàng được giải quyết với khách hàng nhưng không bao giờ hiện ra trong Voided Purchases API.

Quy tắc theo sau rất đơn giản. Nếu ý định của bạn là rút quyền truy cập, hãy hoàn tiền với tùy chọn revoke được bật. Nếu không, bạn đã trả lại tiền và để ngỏ cửa, và revocation job của bạn, dù được viết tốt đến đâu, cũng không có gì để hành động.

Cách poll mà không vượt hạn mức

Endpoint bị giới hạn tốc độ, và các giới hạn đủ thấp để một vòng lặp ngây thơ sẽ chạm phải chúng. Bạn có 6,000 truy vấn mỗi ngày, tính theo Pacific Time, và không quá 30 truy vấn trong bất kỳ khoảng 30 giây nào. Ngân sách đó ổn cho việc poll theo cửa sổ và không thân thiện với các thiết kế một-yêu-cầu-cho-mỗi-đơn-hàng.

Các cửa sổ truy vấn và continuation token

maxResults mặc định là 1,000, cũng chính là giới hạn trên. Khi một cửa sổ chứa nhiều hơn một trang các lần hủy, phản hồi mang theo một đối tượng tokenPagination với một nextPageToken. Gửi lại token đó ở lệnh gọi tiếp theo để đi qua các trang. Đặt startTime và endTime để giới hạn cửa sổ bạn quan tâm, phân trang cho đến khi hết token, rồi tiến cửa sổ tới. Mẫu đó giữ bạn nằm trong cả giới hạn burst 30 giây lẫn hạn mức hằng ngày.

Real-time developer notifications lấp đầy khoảng trống

Poll mỗi ngày vẫn để lại tối đa một ngày mù, và cửa sổ 30 ngày trừng phạt những khoảng trống dài. Real-time developer notifications loại bỏ độ trễ đó. Google phát hành một VoidedPurchaseNotification tới một chủ đề Cloud Pub/Sub mà bạn sở hữu ngay khi một giao dịch mua bị hủy, và backend của bạn tiêu thụ nó trong vài giây. Thông điệp thì nhỏ.

Điều này khiến bạn tốn bao nhiêu tiền

API là hệ thống ống dẫn, nhưng lý do để lắp đặt nó là một hóa đơn. Mỗi lần hủy trong danh sách đó ánh xạ tới một con số thật, và hai trong số chúng đang trở nên đắt hơn.

Hóa đơn chargeback rơi vào bạn từ ngày 3 tháng 8 năm 2026

Bắt đầu từ ngày 3 tháng 8 năm 2026, Google chuyển chi phí của một khoản chargeback sang nhà phát triển. Bạn mất giá mua và bạn phải trả thêm phí chargeback của ngân hàng. Một voidedReason bằng 7 không còn chỉ là một giao dịch bán bị mất, nó là một mục có kèm phí. Bạn không thể đảo ngược một khoản chargeback, nó chung cuộc với ngân hàng, nhưng bạn có thể cầm máu sau đó. Bắt kịp lần hủy nhanh cho phép bạn thu hồi entitlement và, đối với bất cứ thứ gì bạn vẫn đang cung cấp, ngừng chi tiêu cho một khách hàng đã được hoàn tiền rồi bị đảo ngược.

Bạn vẫn tiếp tục trả tiền để phục vụ một khách hàng đã được hoàn tiền

Giá mua biến mất ngay khi một lần hủy xuất hiện. Thứ bạn vẫn kiểm soát là chi phí tiếp tục cung cấp. Mỗi giờ một entitlement đã được hoàn tiền còn hoạt động, bạn vẫn trả tiền cho những thứ mà khách hàng không còn tài trợ nữa: điện toán, các lệnh gọi API mô hình, lưu trữ, và bất kỳ khoản chi trả cho nhà sáng tạo hay đối tác nào gắn với việc sử dụng của họ. Một hệ thống thu hồi được vận hành bởi API này là cách bạn tắt cái đồng hồ đo đó. Bỏ qua nó, và bạn tài trợ cho sản phẩm dành cho những người mà cửa hàng đã bồi hoàn xong.

Friendly fraud là một mẫu hình đáng để theo dõi xu hướng

Một voidedReason bằng 5 hoặc 6 không phải là chuyện xảy ra một lần. Fraud và friendly fraud kết cụm theo tài khoản, theo thiết bị, và đôi khi theo chương trình khuyến mãi. API cung cấp cho bạn voidedSource và voidedReason trên mỗi lần hủy, đủ để theo dõi xu hướng lạm dụng theo tài khoản thay vì coi mỗi lần đảo ngược như một chi phí riêng lẻ. Một khách hàng chargeback hai lần đang nói với bạn điều gì đó mà lần hoàn tiền đầu tiên không nói.

Lắp đặt theo cách của RefundHalt

Mô hình rất nhỏ một khi bạn nắm được tất cả các mảnh ghép. Lắng nghe VoidedPurchaseNotification theo thời gian thực để không có gì phải chờ trọn một ngày. Gọi Voided Purchases API làm nguồn sự thật, khóa theo orderId để các lần gia hạn đăng ký không bao giờ bị nhầm lẫn. Đọc voidedSource và voidedReason để một khoản chargeback được xử lý khác với một khoản hoàn tiền do hối tiếc. Poll theo một lịch đủ chặt để cửa sổ 30 ngày không bao giờ cắn, và hoàn tiền với tùy chọn revoke được bật bất cứ khi nào ý định của bạn là cắt quyền truy cập.

Đây là phần RefundHalt chạy thay cho bạn. Nó tiêu thụ các thông báo thời gian thực, đối soát mọi lần hủy với API, thu hồi đúng đơn hàng thay vì toàn bộ sản phẩm, và tách một khoản chargeback ngân hàng khỏi một khoản hoàn tiền thông thường để những khoản đắt đỏ được đánh dấu, không bị chôn vùi. Bạn được thu hồi quyền truy cập trong vài giây và một bản ghi về việc ai đã hủy cái gì và tại sao, mà không phải tự dựng lên một pipeline Pub/Sub và một polling job.