Quando un acquisto su Google Play viene rimborsato o subisce un chargeback, la Voided Purchases API è come lo scopri

Un rimborso su Google Play non bussa alla tua porta. Il denaro si muove, il cliente tiene l'app aperta e, a meno che tu non vada a cercare, dalla tua parte non cambia nulla. La Voided Purchases API è dove vai a cercare. Ti consegna un elenco di ordini che sono stati annullati, rimborsati o soggetti a chargeback, così puoi revocare l'accesso a ciò che il cliente non paga più. Punta un job pianificato su di essa, leggi l'elenco, taglia il diritto. Questo è tutto il ciclo.

C'è un'insidia che fa inciampare la maggior parte dei team, e non è nel codice. Qui compaiono solo gli ordini che sono stati revocati. Se rimborsi un acquisto nella Play Console senza selezionare l'opzione di revoca, quell'ordine non raggiunge mai questa API, e il tuo job gira pulito mentre un cliente rimborsato conserva tutto ciò che gli hai venduto. Questo articolo percorre l'API campo per campo, i numeri che la delimitano e dove si perde il denaro quando la salti.

Cosa restituisce davvero la Voided Purchases API

L'API risponde a una sola domanda: quali ordini di questa app sono stati annullati di recente. Un annullamento copre tre esiti che finiscono tutti con il cliente che riottiene i propri soldi. Una cancellazione, un rimborso o un chargeback. Si applica ai prodotti in-app una tantum e agli abbonamenti, e scegli l'ambito con un singolo parametro. Imposta type a 0 e ottieni solo gli acquisti di prodotti in-app annullati, che è il valore predefinito. Impostalo a 1 e ottieni insieme gli acquisti in-app annullati e gli acquisti di abbonamenti annullati.

Ogni voce dell'elenco è un oggetto voided purchase. I campi sono pochi e ognuno di essi conta.

I campi di un voided purchase

Leggi voidedReason prima di agire

voidedReason è il campo che trasforma un elenco grezzo in una decisione. Un rimborso per pentimento dell'acquirente e un chargeback bancario finiscono entrambi nello stesso elenco, ma non sono lo stesso evento, e i prezzi di agosto ne rendono uno costoso. Ecco l'insieme completo.

La finestra di 30 giorni è la trappola che svuota il tuo elenco

La Voided Purchases API può mostrare solo gli acquisti annullati degli ultimi 30 giorni. Il parametro startTime ha come valore predefinito l'ora corrente meno 30 giorni, e non può essere impostato più vecchio di così. endTime ha come valore predefinito adesso. Quindi l'endpoint è una finestra mobile di un mese, non un archivio.

La conseguenza è netta. Se il tuo job di polling si rompe e nessuno se ne accorge per cinque settimane, gli annullamenti della prima settimana sono scaduti dall'API. Non c'è alcuna chiamata che li riporti indietro. Non revocherai quegli ordini, e non saprai nemmeno che sono esistiti a meno che tu non li abbia catturati in qualche altro modo. L'API è una rete di sicurezza con un buco della dimensione del tuo peggior disservizio.

L'opzione di revoca decide se un ordine compare del tutto

Questo è il motivo più comune per cui un team segnala l'API come difettosa. Vengono restituiti solo gli ordini revocati. I rimborsi avviati dall'utente, le cancellazioni, i chargeback e i rimborsi avviati da Google vengono sempre revocati, quindi compaiono sempre. Un rimborso avviato dallo sviluppatore è diverso. Quando rimborsi un ordine tu stesso, tramite la Play Console o le Orders API, scegli se revocarlo anche. Rimborsa senza revoca, e l'ordine è saldato con il cliente ma non emerge mai nella Voided Purchases API.

La regola che ne consegue è semplice. Se la tua intenzione è togliere l'accesso, rimborsa con l'opzione di revoca attivata. Altrimenti hai restituito il denaro e lasciato la porta aperta, e il tuo job di revoca, per quanto ben scritto, non ha nulla su cui agire.

Come interrogarla senza far scattare la quota

L'endpoint ha un limite di frequenza, e i limiti sono abbastanza bassi da far scattare un loop ingenuo. Ottieni 6,000 query al giorno, conteggiate in ora del Pacifico, e non più di 30 query in un qualsiasi periodo di 30 secondi. Quel budget va bene per il polling a finestre ed è ostile ai progetti con una richiesta per ordine.

Finestre di query e il token di continuazione

maxResults ha come valore predefinito 1,000, che è anche il tetto massimo. Quando una finestra contiene più di una pagina di annullamenti, la risposta porta un oggetto tokenPagination con un nextPageToken. Passa quel token nella chiamata successiva per scorrere le pagine. Imposta startTime e endTime per delimitare la finestra che ti interessa, scorri le pagine finché il token non si esaurisce, poi avanza la finestra. Quel pattern ti tiene dentro sia il limite di burst di 30 secondi sia il tetto giornaliero.

Le Real-time developer notifications colmano il divario

Interrogare ogni giorno lascia comunque fino a un giorno di cecità, e la finestra di 30 giorni punisce le lunghe interruzioni. Le Real-time developer notifications eliminano il ritardo. Google pubblica una VoidedPurchaseNotification su un topic Cloud Pub/Sub di tua proprietà nel momento in cui un acquisto viene annullato, e il tuo backend la consuma in pochi secondi. Il messaggio è piccolo.

Cosa ti costa in denaro

L'API è impiantistica, ma la ragione per collegarla è una fattura. Ogni annullamento in quell'elenco corrisponde a un numero reale, e due di essi stanno diventando più costosi.

La fattura del chargeback ricade su di te dal 3 agosto 2026

A partire dal 3 agosto 2026, Google sposta il costo di un chargeback sullo sviluppatore. Perdi il prezzo d'acquisto e paghi in più la commissione di chargeback della banca. Un voidedReason pari a 7 non è più solo una vendita persa, è una voce di costo con una commissione allegata. Non puoi annullare un chargeback, è definitivo con la banca, ma puoi fermare l'emorragia dopo. Cogliere l'annullamento in fretta ti permette di revocare il diritto e, per tutto ciò che stai ancora erogando, di smettere di spendere per un cliente che è stato rimborsato e poi stornato.

Continui a pagare per servire un cliente rimborsato

Il prezzo d'acquisto è perso nel momento in cui compare un annullamento. Ciò che controlli ancora è il costo di continuare a erogare. Ogni ora in cui un diritto rimborsato resta attivo, continui a pagare per le cose che il cliente non finanzia più: calcolo, chiamate alle API dei modelli, archiviazione, e qualsiasi pagamento a creatori o partner legato al suo utilizzo. Un sistema di revoca guidato da questa API è il modo per spegnere quel contatore. Saltalo, e finanzi il prodotto per persone che lo store ha già risarcito.

Il friendly fraud è uno schema di cui vale la pena seguire l'andamento

Un voidedReason pari a 5 o 6 non è un caso isolato. Fraud e friendly fraud si concentrano per account, per dispositivo e a volte per promozione. L'API ti fornisce voidedSource e voidedReason su ogni annullamento, il che basta a seguire l'andamento degli abusi per account invece di trattare ogni storno come un costo isolato. Un cliente che fa due chargeback ti sta dicendo qualcosa che il primo rimborso non aveva detto.

Collegarla alla maniera di RefundHalt

Il modello è piccolo una volta che hai in mano tutti i pezzi. Resta in ascolto delle VoidedPurchaseNotification in tempo reale così che nulla aspetti un giorno intero. Chiama la Voided Purchases API come fonte di verità, con chiave orderId così che i rinnovi degli abbonamenti non vengano mai confusi. Leggi voidedSource e voidedReason così che un chargeback venga gestito diversamente da un rimborso per pentimento. Interroga con una pianificazione abbastanza serrata da non far mai mordere la finestra di 30 giorni, e rimborsa con l'opzione di revoca attivata ogni volta che la tua intenzione è tagliare l'accesso.

Questa è la parte che RefundHalt gestisce per te. Consuma le notifiche in tempo reale, riconcilia ogni annullamento con l'API, revoca l'ordine esatto invece dell'intero prodotto, e separa un chargeback bancario da un rimborso ordinario così che quelli costosi vengano segnalati, non sepolti. Ottieni l'accesso revocato in pochi secondi e un registro di chi ha annullato cosa e perché, senza dover allestire tu stesso una pipeline Pub/Sub e un job di polling.