Una notifica di acquisto annullato consente al tuo server Google Play di revocare l'accesso nel momento in cui arriva un rimborso

Un rimborso su Google Play non deve per forza essere qualcosa che scopri più tardi in un report. Google Play può inviare al tuo server una notifica di acquisto annullato nell'istante in cui un acquisto viene annullato, che l'acquirente abbia ottenuto un rimborso self-service, che un addetto all'assistenza lo abbia concesso, che una banca abbia imposto un chargeback, o che tu stesso abbia rimborsato l'ordine con il flag di revoca attivo. Il messaggio è minuscolo, nomina l'acquisto esatto e trasporta una sola istruzione, restituisci il diritto, perché i soldi sono già andati.

Cos'è davvero una notifica di acquisto annullato

Una notifica di acquisto annullato è uno dei tipi di Real-time Developer Notifications di Google Play, ovvero RTDN. RTDN è un canale push. Google pubblica un messaggio su un topic Cloud Pub/Sub di tua proprietà, e il tuo backend lo riceve entro pochi istanti dall'evento, invece di scoprirlo al prossimo polling programmato. Questo è tutto il senso della notifica di acquisto annullato rispetto al vecchio percorso pull: vieni a conoscenza del rimborso mentre accade, non ore dopo.

Il percorso pull esiste ancora e conta ancora. La Voided Purchases API permette al tuo server di chiedere, secondo un tuo calendario, l'elenco degli acquisti annullati in un intervallo di tempo. I due sono complementari. La notifica ti dice l'istante in cui un acquisto cambia stato; l'API ti permette di riconciliare in blocco e di recuperare tutto ciò che un messaggio perso avrebbe lasciato indietro.

Viaggia dentro una Real-time Developer Notification

La notifica di acquisto annullato non arriva mai da sola. Sta dentro un wrapper DeveloperNotification, e quel wrapper viene consegnato come un'unica stringa codificata in base64 nel campo data del messaggio Pub/Sub. Il tuo handler decodifica quella stringa in JSON prima di poter leggere qualsiasi cosa. Il wrapper nomina sempre l'app e l'orario dell'evento, e contiene esattamente un oggetto di notifica tra i cinque che Google definisce. Sono mutuamente esclusivi, quindi un messaggio che trasporta un voidedPurchaseNotification non trasporterà anche un evento di abbonamento o una tantum.

I quattro campi che trasporta

Togli il wrapper e la notifica di acquisto annullato in sé è quattro campi. È volutamente essenziale. La posizione di Google è che se tutto ciò che ti serve è trovare l'acquisto giusto e regolare il diritto, questi quattro bastano, e non devi richiamare alcuna API per agire.

productType ti dice cosa è stato annullato

productType è un piccolo intero, e decide quale dei tuoi percorsi di revoca prendere. Un annullamento di abbonamento deve smontare un accesso in corso; un annullamento di acquisto una tantum rimuove semplicemente un singolo diritto.

refundType ti dice quanto è tornato indietro

refundType distingue un'inversione completa e pulita da una parziale. Il caso parziale è ristretto. Compare solo quando un acquisto una tantum a quantità multipla ha avuto rimborsata una parte, ma non tutta, della sua quantità.

Attivala prima, o non arriverà mai

Le notifiche di acquisto annullato non fluiscono per impostazione predefinita. Abiliti RTDN una volta, in Play Console, e la punti su un topic Pub/Sub che controlli. L'interruttore si trova sotto Monetize, poi Monetization setup, nella sezione Real-time developer notifications in cima alla pagina. Spunta Enable real-time notifications, poi incolla il nome completo del topic nella forma projects/{project_id}/topics/{topic_name}, e usa Send Test Message per confermare che il condotto funzioni prima di fidartene.

L'interruttore dei contenuti è il punto in cui le persone perdono gli acquisti annullati. Entrambe le scelte li includono, quindi non puoi rinunciare accidentalmente ai rimborsi mantenendo gli abbonamenti.

• Ricevi notifiche per gli abbonamenti e tutti gli acquisti annullati. Ricevi gli eventi di abbonamento e ogni acquisto annullato, ma non gli eventi di acquisto dei prodotti una tantum.
• Ricevi tutte le notifiche per gli abbonamenti e i prodotti una tantum. Ricevi quanto sopra più gli eventi dei prodotti una tantum come ONE_TIME_PRODUCT_PURCHASED e ONE_TIME_PRODUCT_CANCELED.

Quanto ti costa, in denaro

Un annullamento è una perdita già contabilizzata nel momento in cui la notifica ti raggiunge. Il prezzo di vendita è andato, e così anche tutto ciò che hai speso per servire quel cliente. Se ha generato immagini, effettuato chiamate ai tuoi modelli, usato spazio di archiviazione o innescato un pagamento a terzi, quei costi sono stati pagati in denaro reale e non tornano con il rimborso. La notifica non può recuperare nulla di tutto ciò. Ciò che può fare è fermare l'emorragia da qui in avanti, che è l'intero motivo per agire in fretta.

L'emorragia è peggiore sugli abbonamenti e peggiore sui chargeback. Un abbonamento che non revochi continua a costarti per essere servito, mese dopo mese, per un cliente che non paga più. E un chargeback è il tipo di annullamento più costoso. Dal 3 agosto 2026, la documentazione di Google afferma che un chargeback trasferisce allo sviluppatore il prezzo di acquisto più la commissione della banca. La notifica di acquisto annullato è spesso il primo luogo in cui i tuoi stessi sistemi vengono a sapere che un chargeback si è concluso, quindi un handler che revoca sul posto è ciò che impedisce a una vendita persa di trasformarsi in una vendita persa più settimane di servizio gratuito.

Come gestire una notifica di acquisto annullato, passo dopo passo

Verifica e deduplica il messaggio

• Conferma che il messaggio Pub/Sub provenga da Google e sia destinato al topic che hai configurato, poi decodifica il campo data base64 per ottenere il JSON DeveloperNotification.
• Usa il messageId di Pub/Sub per scartare i duplicati. Google avverte che la stessa notifica può essere consegnata più di una volta, quindi tratta la riconsegna come normale e rendi il tuo handler idempotente.
• Conferma il messaggio solo dopo averlo registrato in modo sicuro, così un crash a metà handler non perde l'evento.

Cerca l'acquisto

• Abbina il purchaseToken all'acquisto che hai salvato quando hai concesso per la prima volta il diritto. Ripiega su orderId per le ricerche dell'assistenza e la riconciliazione manuale.
• Leggi productType per scegliere il percorso di revoca dell'abbonamento o della tantum, e leggi refundType per decidere tra una revoca completa e una parziale.

Revoca e registra

• Rimuovi il diritto. Per un rimborso completo, taglia l'accesso all'articolo. Per un rimborso parziale basato sulla quantità, riduci la quantità concessa dell'importo rimborsato e lascia intatto il resto.
• Annota cosa hai fatto e quando, con chiave purchaseToken e orderId. Quel record è ciò che ti permette di rispondere a un ticket di assistenza più tardi, ed è ciò che permette alla Voided Purchases API di riconciliare in modo pulito con il tuo stato.

Dove si colloca tra gli altri segnali di rimborso

Una notifica di acquisto annullato è un avviso, non una trattativa. Ti comunica un esito già deciso. Vale la pena vederla accanto ai segnali con cui è facile confonderla, perché solo alcuni di essi chiedono mai la tua versione dei fatti.

Il punto da tenere a mente è semplice. Tra i due store esistono esattamente due flussi di rimborso in cui lo sviluppatore ha voce in capitolo, la CONSUMPTION_REQUEST di Apple e la revisione del chargeback di Google Play. Una notifica di acquisto annullato non è nessuno dei due. Quando ti raggiunge, la decisione è alle tue spalle e l'unica cosa che ti resta in mano è quanto in fretta revochi.