Wanneer een Google Play-aankoop wordt terugbetaald of teruggeboekt, is de Voided Purchases API hoe je erachter komt

Een terugbetaling op Google Play klopt niet bij je aan. Het geld verschuift, de klant houdt de app open, en tenzij je gaat kijken, verandert er aan jouw kant niets. De Voided Purchases API is waar je gaat kijken. Hij geeft je een lijst van bestellingen die zijn geannuleerd, terugbetaald of teruggeboekt, zodat je de toegang kunt intrekken tot waar de klant niet langer voor betaalt. Richt een geplande taak erop, lees de lijst, snijd het recht af. Dat is de hele lus.

Er is één addertje dat de meeste teams laat struikelen, en het zit niet in de code. Alleen bestellingen die met revoke zijn behandeld, verschijnen hier. Als je een aankoop in de Play Console terugbetaalt zonder de revoke-optie aan te vinken, bereikt die bestelling deze API nooit, en jouw taak draait smetteloos terwijl een terugbetaalde klant alles houdt wat je hem hebt verkocht. Dit artikel loopt de API veld voor veld door, de getallen die haar begrenzen, en waar het geld weglekt als je haar overslaat.

Wat de Voided Purchases API daadwerkelijk retourneert

De API beantwoordt één vraag: welke bestellingen voor deze app zijn onlangs ongeldig gemaakt. Een ongeldigmaking (void) omvat drie uitkomsten die allemaal eindigen met de klant die zijn geld terugkrijgt. Een annulering, een terugbetaling of een chargeback. Het geldt voor eenmalige in-app-producten en voor abonnementen, en je kiest de reikwijdte met één parameter. Zet type op 0 en je krijgt alleen ongeldig gemaakte in-app-productaankopen, wat de standaard is. Zet het op 1 en je krijgt ongeldig gemaakte in-app-aankopen en ongeldig gemaakte abonnementsaankopen samen.

Elk item in de lijst is een voided purchase-object. De velden zijn weinig in aantal en elk ervan telt.

De velden van een voided purchase

Lees voidedReason voordat je handelt

voidedReason is het veld dat een ruwe lijst in een beslissing verandert. Een terugbetaling door spijt van de koper en een chargeback van de bank belanden beide in dezelfde lijst, maar het zijn niet dezelfde gebeurtenis, en de augustusprijzen maken een van beide duur. Hier is de volledige set.

Het venster van 30 dagen is de valkuil die je lijst leegmaakt

De Voided Purchases API kan alleen ongeldig gemaakte aankopen van de afgelopen 30 dagen tonen. De parameter startTime is standaard de huidige tijd min 30 dagen en kan niet ouder worden ingesteld. endTime is standaard nu. Het endpoint is dus een voortschuivend venster van één maand, geen archief.

Het gevolg is bot. Als je pollingtaak stukgaat en niemand het vijf weken lang merkt, zijn de ongeldigmakingen van week één uit de API verouderd. Er is geen aanroep die ze terugbrengt. Je trekt die bestellingen niet in, en je zult zelfs niet weten dat ze hebben bestaan, tenzij je ze op een andere manier hebt vastgelegd. De API is een vangnet met een gat zo groot als je ergste storing.

De revoke-optie bepaalt of een bestelling überhaupt verschijnt

Dit is de allervaakst voorkomende reden waarom een team de API als defect meldt. Alleen bestellingen met revoke worden geretourneerd. Door de gebruiker geïnitieerde terugbetalingen, annuleringen, chargebacks en door Google geïnitieerde terugbetalingen krijgen altijd revoke, dus ze verschijnen altijd. Een door de ontwikkelaar geïnitieerde terugbetaling is anders. Wanneer je een bestelling zelf terugbetaalt, via de Play Console of de Orders API, kies je of je die ook wilt revoken. Betaal terug zonder revoke, en de bestelling is met de klant afgewikkeld maar duikt nooit op in de Voided Purchases API.

De regel die daaruit volgt, is simpel. Als het je bedoeling is toegang in te trekken, betaal dan terug met de revoke-optie aan. Anders heb je het geld teruggegeven en de deur open laten staan, en heeft je intrekkingstaak, hoe goed ook geschreven, niets om op te handelen.

Hoe je het pollt zonder de quota te overschrijden

Het endpoint is rate-limited, en de limieten zijn laag genoeg dat een naïeve lus ze zal raken. Je krijgt 6,000 query's per dag, geteld in Pacific Time, en niet meer dan 30 query's in elke periode van 30 seconden. Dat budget is prima voor pollen met vensters en vijandig voor ontwerpen met één verzoek per bestelling.

Queryvensters en de continuation token

maxResults is standaard 1,000, wat ook het plafond is. Wanneer een venster meer dan één pagina met ongeldigmakingen bevat, draagt de respons een tokenPagination-object met een nextPageToken. Geef dat token terug bij de volgende aanroep om door de pagina's te lopen. Stel startTime en endTime in om het venster af te bakenen waar het je om gaat, blader tot het token op is, en schuif dan het venster op. Dat patroon houdt je binnen zowel de burstlimiet van 30 seconden als de daglimiet.

Real-time developer notifications dichten het gat

Elke dag pollen laat nog steeds tot een dag blindheid over, en het venster van 30 dagen straft lange onderbrekingen af. Real-time developer notifications halen de vertraging weg. Google publiceert een VoidedPurchaseNotification naar een Cloud Pub/Sub-onderwerp dat jij bezit op het moment dat een aankoop ongeldig wordt gemaakt, en je backend verwerkt die binnen seconden. Het bericht is klein.

Wat dit je in geld kost

De API is leidingwerk, maar de reden om haar aan te sluiten is een rekening. Elke ongeldigmaking in die lijst komt overeen met een echt getal, en twee ervan worden duurder.

De chargeback-rekening komt vanaf 3 augustus 2026 bij jou terecht

Vanaf 3 augustus 2026 verschuift Google de kosten van een chargeback naar de ontwikkelaar. Je verliest de aankoopprijs en je betaalt daarbovenop de chargeback-vergoeding van de bank. Een voidedReason van 7 is niet langer alleen een verloren verkoop, het is een post met een vergoeding eraan vast. Je kunt een chargeback niet terugdraaien, hij is definitief bij de bank, maar je kunt het bloeden erna wel stoppen. De ongeldigmaking snel opvangen laat je het recht intrekken en, voor alles wat je nog levert, stoppen met uitgeven aan een klant die is terugbetaald en daarna teruggeboekt.

Je blijft betalen om een terugbetaalde klant te bedienen

De aankoopprijs is weg op het moment dat een ongeldigmaking verschijnt. Wat je nog wel in de hand hebt, is de kost van blijven leveren. Elk uur dat een terugbetaald recht actief blijft, blijf je betalen voor de dingen die de klant niet langer financiert: rekenkracht, model-API-aanroepen, opslag en elke uitbetaling aan makers of partners die aan zijn gebruik gekoppeld is. Een intrekkingssysteem dat door deze API wordt aangedreven, is hoe je die meter uitzet. Sla het over, en je financiert het product voor mensen die de store al schadeloos heeft gesteld.

Friendly fraud is een patroon dat het waard is om te volgen

Een voidedReason van 5 of 6 is geen eenmalig geval. Fraud en friendly fraud clusteren per account, per apparaat, en soms per promotie. De API geeft je de voidedSource en voidedReason bij elke ongeldigmaking, wat genoeg is om misbruik per account te volgen in plaats van elke terugboeking als een op zichzelf staande kost te behandelen. Een klant die twee keer een chargeback doet, vertelt je iets wat de eerste terugbetaling niet deed.

Het aansluiten op de RefundHalt-manier

Het model is klein zodra je alle stukjes vasthebt. Luister in real time naar VoidedPurchaseNotification zodat er niets een hele dag wacht. Roep de Voided Purchases API aan als bron van waarheid, gesleuteld op orderId zodat abonnementsverlengingen nooit verward raken. Lees voidedSource en voidedReason zodat een chargeback anders wordt afgehandeld dan een spijt-terugbetaling. Poll volgens een schema dat strak genoeg is dat het venster van 30 dagen nooit bijt, en betaal terug met de revoke-optie aan wanneer het je bedoeling is toegang af te snijden.

Dit is het deel dat RefundHalt voor je uitvoert. Het verwerkt de real-time meldingen, verzoent elke ongeldigmaking met de API, trekt precies de bestelling in in plaats van het hele product, en scheidt een bankchargeback van een gewone terugbetaling zodat de dure worden gemarkeerd, niet begraven. Je krijgt toegang binnen seconden ingetrokken en een registratie van wie wat en waarom ongeldig maakte, zonder zelf een Pub/Sub-pijplijn en een pollingtaak op te zetten.