Gdy zakup w Google Play zostaje zwrócony lub obciążony zwrotnie, Voided Purchases API jest sposobem, w jaki się o tym dowiadujesz

Zwrot w Google Play nie puka do twoich drzwi. Pieniądze się przemieszczają, klient nadal ma otwartą aplikację i dopóki sam nie zajrzysz, po twojej stronie nic się nie zmienia. Voided Purchases API to miejsce, do którego zaglądasz. Podaje ci listę zamówień, które zostały anulowane, zwrócone lub obciążone zwrotnie, dzięki czemu możesz odebrać dostęp do tego, za co klient już nie zapłacił. Skieruj tam zaplanowane zadanie, odczytaj listę, odetnij uprawnienie. To cała pętla.

Jest jeden haczyk, o który potyka się większość zespołów, i nie ma go w kodzie. Pojawiają się tutaj tylko zamówienia, które zostały objęte revoke. Jeśli zwrócisz zakup w Play Console bez zaznaczenia opcji revoke, to zamówienie nigdy nie dotrze do tego API, a twoje zadanie działa bez zarzutu, podczas gdy zwrócony klient zachowuje wszystko, co mu sprzedałeś. Ten wpis omawia API pole po polu, liczby, które je ograniczają, oraz miejsce, w którym wyciekają pieniądze, gdy je pominiesz.

Co właściwie zwraca Voided Purchases API

API odpowiada na jedno pytanie: które zamówienia dla tej aplikacji zostały ostatnio unieważnione. Unieważnienie (void) obejmuje trzy wyniki, które wszystkie kończą się odzyskaniem pieniędzy przez klienta. Anulowanie, zwrot albo chargeback. Dotyczy jednorazowych produktów w aplikacji oraz subskrypcji, a zakres wybierasz jednym parametrem. Ustaw type na 0, a otrzymasz tylko unieważnione zakupy produktów w aplikacji, co jest wartością domyślną. Ustaw na 1, a otrzymasz razem unieważnione zakupy w aplikacji i unieważnione zakupy subskrypcji.

Każdy wpis na liście to obiekt voided purchase. Pól jest niewiele i każde z nich ma znaczenie.

Pola obiektu voided purchase

Przeczytaj voidedReason, zanim zaczniesz działać

voidedReason to pole, które zamienia surową listę w decyzję. Zwrot z powodu żalu kupującego i chargeback z banku trafiają na tę samą listę, ale nie są tym samym zdarzeniem, a sierpniowy cennik czyni jedno z nich kosztownym. Oto pełny zestaw.

Okno 30 dni to pułapka, która opróżnia twoją listę

Voided Purchases API może pokazać tylko unieważnione zakupy z ostatnich 30 dni. Parametr startTime domyślnie przyjmuje bieżący czas minus 30 dni i nie można ustawić go starszego. endTime domyślnie przyjmuje teraz. Zatem endpoint to przesuwane okno jednego miesiąca, a nie archiwum.

Konsekwencja jest dosadna. Jeśli twoje zadanie odpytujące się zepsuje i nikt tego nie zauważy przez pięć tygodni, unieważnienia z pierwszego tygodnia wypadły już z API. Nie ma wywołania, które je przywróci. Nie odbierzesz dostępu do tych zamówień, a nawet nie dowiesz się, że istniały, chyba że zarejestrowałeś je w inny sposób. To API to siatka bezpieczeństwa z dziurą wielkości twojej najgorszej awarii.

Opcja revoke decyduje, czy zamówienie w ogóle się pojawi

To najczęstszy powód, dla którego zespół zgłasza API jako zepsute. Zwracane są tylko zamówienia z revoke. Zwroty zainicjowane przez użytkownika, anulowania, chargebacki i zwroty zainicjowane przez Google zawsze mają revoke, więc zawsze się pojawiają. Zwrot zainicjowany przez dewelopera jest inny. Gdy sam zwracasz zamówienie, przez Play Console lub Orders API, wybierasz, czy je również objąć revoke. Zwróć bez revoke, a zamówienie jest rozliczone z klientem, ale nigdy nie pojawia się w Voided Purchases API.

Wynikająca z tego zasada jest prosta. Jeśli twoim zamiarem jest odebranie dostępu, dokonaj zwrotu z włączoną opcją revoke. W przeciwnym razie oddałeś pieniądze i zostawiłeś otwarte drzwi, a twoje zadanie odbierające dostęp, choćby najlepiej napisane, nie ma na czym działać.

Jak je odpytywać bez przekraczania limitu

Endpoint ma ograniczenie tempa, a limity są na tyle niskie, że naiwna pętla je osiągnie. Masz 6,000 zapytań dziennie, liczonych w czasie pacyficznym, i nie więcej niż 30 zapytań w dowolnym okresie 30 sekund. Ten budżet jest w porządku przy odpytywaniu oknami i wrogi wobec projektów typu jedno-żądanie-na-zamówienie.

Okna zapytań i continuation token

maxResults domyślnie wynosi 1,000, co jest zarazem górnym pułapem. Gdy okno zawiera więcej niż jedną stronę unieważnień, odpowiedź niesie obiekt tokenPagination z nextPageToken. Przekaż ten token z powrotem w kolejnym wywołaniu, aby przejść przez strony. Ustaw startTime i endTime, aby ograniczyć interesujące cię okno, przeglądaj strony, aż token się skończy, a potem przesuń okno. Ten wzorzec utrzymuje cię w obrębie zarówno limitu serii 30 sekund, jak i dziennego limitu.

Real-time developer notifications zamykają lukę

Odpytywanie codziennie wciąż zostawia do jednego dnia ślepoty, a okno 30 dni karze długie przerwy. Real-time developer notifications usuwają opóźnienie. Google publikuje VoidedPurchaseNotification do posiadanego przez ciebie tematu Cloud Pub/Sub w momencie unieważnienia zakupu, a twój backend odbiera go w ciągu sekund. Komunikat jest mały.

Ile cię to kosztuje w pieniądzach

API to instalacja hydrauliczna, ale powodem, by je podłączyć, jest rachunek. Każde unieważnienie na tej liście odwzorowuje się na realną liczbę, a dwa z nich stają się droższe.

Rachunek za chargeback spada na ciebie od 3 sierpnia 2026

Począwszy od 3 sierpnia 2026, Google przenosi koszt chargebacku na dewelopera. Tracisz cenę zakupu i na dodatek płacisz bankową opłatę za chargeback. voidedReason równy 7 to już nie tylko utracona sprzedaż, to pozycja z doliczoną opłatą. Nie możesz cofnąć chargebacku, jest ostateczny po stronie banku, ale możesz zatamować krwawienie po nim. Szybkie wychwycenie unieważnienia pozwala ci odebrać uprawnienie i, w przypadku wszystkiego, co wciąż dostarczasz, przestać wydawać na klienta, który został zwrócony, a potem cofnięty.

Wciąż płacisz za obsługę klienta, któremu zwrócono pieniądze

Cena zakupu przepada w chwili pojawienia się unieważnienia. To, co wciąż kontrolujesz, to koszt dalszego dostarczania. Każda godzina, w której zwrócone uprawnienie pozostaje aktywne, to płacenie za rzeczy, których klient już nie finansuje: moc obliczeniową, wywołania API modeli, przechowywanie oraz wszelkie wypłaty dla twórców lub partnerów powiązane z jego użyciem. System odbierania dostępu napędzany tym API to sposób, w jaki wyłączasz ten licznik. Pomiń go, a finansujesz produkt dla ludzi, których sklep już zaspokoił.

Friendly fraud to wzorzec wart śledzenia trendu

voidedReason równy 5 lub 6 to nie jednorazowy przypadek. Fraud i friendly fraud grupują się według konta, według urządzenia, a czasem według promocji. API daje ci voidedSource i voidedReason przy każdym unieważnieniu, co wystarcza, by śledzić trend nadużyć według konta, zamiast traktować każde cofnięcie jako odosobniony koszt. Klient, który dokonuje chargebacku dwukrotnie, mówi ci coś, czego nie powiedział pierwszy zwrot.

Podłączanie tego po sposobie RefundHalt

Model jest niewielki, gdy masz już wszystkie elementy. Nasłuchuj VoidedPurchaseNotification w czasie rzeczywistym, aby nic nie czekało całego dnia. Wywołuj Voided Purchases API jako źródło prawdy, kluczując po orderId, aby odnowienia subskrypcji nigdy się nie myliły. Odczytuj voidedSource i voidedReason, aby chargeback był obsługiwany inaczej niż zwrot z powodu żalu. Odpytuj według harmonogramu na tyle ścisłego, by okno 30 dni nigdy nie ugryzło, i dokonuj zwrotu z włączoną opcją revoke, ilekroć twoim zamiarem jest odcięcie dostępu.

To część, którą RefundHalt uruchamia za ciebie. Odbiera powiadomienia w czasie rzeczywistym, uzgadnia każde unieważnienie z API, odbiera dokładnie to zamówienie, a nie cały produkt, i oddziela bankowy chargeback od zwykłego zwrotu, aby te kosztowne zostały oznaczone, a nie pogrzebane. Dostajesz odebrany dostęp w ciągu sekund i zapis tego, kto co i dlaczego unieważnił, bez samodzielnego stawiania potoku Pub/Sub i zadania odpytującego.