L'API Google Play Developer include funzionalità aggiuntive per segnalare le transazioni dei programmi di fatturazione e link. Questa guida descrive come segnalare le transazioni di questi programmi di fatturazione.
Esistono alcuni componenti che potrebbero essere necessari per gestire le transazioni esterne dal tuo backend. Per crearli, devi configurare l'integrazione del backend come indicato in Configura l'API Google Play Developer. Per creare funzionalità di backend per sviluppatori non specifiche per i programmi di fatturazione e collegamento, consulta la sezione Sistema di fatturazione di Google Play.
Glossario dei termini
Convenzioni dei termini seguite in questa guida:
- Programmi di fatturazione e link: programmi che facilitano gli acquisti di contenuti digitali o i download di app al di fuori di Google Play. Sono inclusi i programmi di fatturazione alternativa e per i contenuti esterni.
- API External Transactions: API utilizzate per segnalare le transazioni per i programmi di fatturazione e link idonei.
- Transazione esterna: una transazione idonea che avviene al di fuori dell'app, come definito dai programmi di fatturazione alternativa e contenuti esterni.
- Token di transazione esterno: un token fornito tramite la Libreria Fatturazione Play che puoi utilizzare quando l'utente avvia una transazione esterna. Questo token viene utilizzato per notificare a Google Play una transazione esterna autorizzata.
- ID transazione esterna: un identificatore univoco generato da te per identificare una transazione esterna.
Configura le autorizzazioni di Play Console
Per chiamare l'API externaltransactions per segnalare o rimborsare transazioni esterne, concedi al tuo service account l'autorizzazione Gestisci ordini e abbonamenti in Google Play Console. Puoi concedere
questa autorizzazione a livello di account o per app specifiche.
Per istruzioni sulla creazione di un service account e sulla concessione delle autorizzazioni in Play Console, consulta Utilizza un service account. Per ulteriori informazioni sulle autorizzazioni di Play Console, consulta l'articolo Aggiungi utenti all'account sviluppatore e gestisci le autorizzazioni.
Segnala nuove transazioni esterne a Google Play
Esegui l'integrazione con l'API externaltransactions per segnalare le transazioni che avvengono al di fuori del sistema di fatturazione di Google Play nei paesi supportati, incluse le transazioni da 0,00 $ derivanti da acquisti di prove senza costi e installazioni di app. Devi avviare e segnalare le transazioni solo nei programmi di fatturazione e link per i paesi degli utenti idonei, come consentito dai programmi di fatturazione alternativa e contenuti esterni; in caso contrario, la chiamata API viene rifiutata. Ciò vale per tutte le transazioni, inclusi nuovi acquisti, rinnovi, ricariche, upgrade, downgrade e download di app.
Report sulle transazioni esterne
Devi chiamare l'API externaltransactions per segnalare una transazione esterna
dopo che un pagamento è stato autorizzato tramite un programma di fatturazione e link.
Ciò vale per tutte le transazioni, inclusi addebiti iniziali, rinnovi, rimborsi e altro. Consulta le linee guida per il rispettivo programma di fatturazione e link per i requisiti di reporting.
Ogni transazione esterna viene segnalata con un ID transazione esterna. Per gli acquisti ricorrenti (come gli abbonamenti con rinnovo automatico), devi inviare l'ID transazione esterna associato alla prima transazione dell'acquisto ricorrente come parametro per tutte le transazioni successive, inclusi i rimborsi. In questo modo, viene registrata la serie di transazioni per l'acquisto. Devi inviare un nuovo ID transazione esterno per gli acquisti quando il prodotto cambia (ad esempio un upgrade o un downgrade) o se la transazione ricorrente viene annullata o scade e lo stesso prodotto viene acquistato di nuovo in un secondo momento. Non devi includere informazioni che consentono l'identificazione personale, informazioni proprietarie o riservate nell'ID transazione esterno.
Segnala una transazione iniziale
Ogni volta che viene autorizzato un nuovo acquisto o download di app nei programmi di fatturazione e link, devi chiamare l'API externaltransactions.
Il externalTransactionToken ricevuto dall'app tramite la Libreria Fatturazione Google Play è obbligatorio come parte del corpo della richiesta per i download di app, gli acquisti una tantum e le prime transazioni di un acquisto ricorrente (ad esempio un abbonamento). Questa operazione è chiamata transazione iniziale. Dopo la transazione iniziale, segnala le transazioni successive (ad esempio i rinnovi degli abbonamenti) fornendo un nuovo externalTransactionId univoco. Per saperne di più, consulta Segnala le transazioni successive per un acquisto.
Esempio:
- Uno sviluppatore configura e attiva la fatturazione alternativa nella sua app.
- L'utente 1 si trova in Corea del Sud, un paese supportato, e sta tentando di acquistare
product1, al prezzo di 12.634,10 KRW al mese, con un'offerta di prova senza costi di un mese. - L'app avvia il flusso di acquisto con
ProductDetailsperproduct1e l'offerta selezionata dall'utente. - L'utente 1 seleziona il sistema di fatturazione alternativo dello sviluppatore.
UserChoiceBillingListenerriceve il valoremy_tokencomeexternalTransactionToken.- Lo sviluppatore invia quindi le informazioni pertinenti al proprio backend (valore
externalTransactionTokene prodotti acquistati). Dopodiché, avviano il flusso di acquisto perproduct1nel sistema di fatturazione alternativo. A questa transazione viene assegnato un ID transazione univoco sul lato sviluppatore, che viene utilizzato per segnalarla a Google Play: 123-456-789. L'ID transazione è obbligatorio, anche se l'utente riceve una prova senza costi. - Dopo che la transazione per l'acquisto è stata eseguita nel sistema di fatturazione alternativo, lo sviluppatore la registra su Google Play con la seguente richiesta. Inizialmente viene registrata come una transazione da zero dollari, perché l'utente riceve un mese senza costi.
POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=123-456-789
Body
{
"originalPreTaxAmount" : {
"priceMicros" : "0",
"currency" : "KRW"
},
"originalTaxAmount" : {
"priceMicros" : "0",
"currency" : "KRW"
},
"transactionTime" : "2022-02-22T12:45:00Z",
"recurringTransaction" : {
"externalTransactionToken" : "my_token",
"externalSubscription" : {
"subscriptionType" : "RECURRING"
}
},
"userTaxAddress" : {
"regionCode" : "KR"
}
}
Quando segnali una transazione iniziale, tieni presente quanto segue:
subscriptionTypepuò essereRECURRING(per gli abbonamenti con rinnovo automatico) oPREPAID(per gli abbonamenti prepagati).OtherRecurringProductdeve essere utilizzato per rappresentare gli acquisti una tantum che richiedono più pagamenti o un pagamento posticipato. Ad esempio, una prenotazione potrebbe avere una transazione iniziale di 0 $seguita da una seconda transazione in una data successiva per il prezzo dello SKU al momento dell'evasione della prenotazione. Per maggiori dettagli sulla generazione di report sulle transazioni successive, consulta Genera report sulle transazioni successive per un acquisto.- Devi fornire
ExternalOfferDetailsquando segnali le transazioni iniziali relative alle offerte esterne. Questo non è necessario per le transazioni successive.
Se effettui una transazione con un utente in India in cui l'imposta dipende dalla sua area amministrativa (ad esempio uno stato o una provincia), includi l'area in userTaxAddress. Consulta l'elenco predefinito di stringhe nella guida di riferimento dell'API per le aree amministrative applicabili.
POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=123-456-789
Body
{
"originalPreTaxAmount" : {
"priceMicros" : "0",
"currency" : "INR"
},
"originalTaxAmount" : {
"priceMicros" : "0",
"currency" : "INR"
},
"transactionTime" : "2023-11-01T12:45:00Z",
"recurringTransaction" : {
"externalTransactionToken" : "my_token",
"externalSubscription" : {
"subscriptionType" : "RECURRING"
}
},
"userTaxAddress" : {
# Tax varies in India based on state, so include that information in
# administrativeArea
"regionCode" : "IN",
"administrativeArea" : "KERALA"
}
}
Offerte esterne
Se la transazione segnalata rientra nel programma per offerte esterne, devi impostare il campo externalOfferDetails se la transazione è una tantum o la prima transazione di una serie ricorrente:
- Quando generi report sulle transazioni di download di app, imposta
linkTypesuLINK_TO_APP_DOWNLOADe fornisci i valori appropriati perinstalledAppPackageeinstalledAppCategory. Per maggiori dettagli, consulta Segnalare il download di un'app. - Quando generi report sulle transazioni di offerte di contenuti digitali, imposta
linkTypesuLINK_TO_DIGITAL_CONTENT_OFFER. - Dopo aver installato un'app esterna tramite il programma per offerte esterne, devi segnalare le transazioni effettuate nell'app esterna. Quando segnali queste transazioni, collegale all'evento di download dell'app originale:
- Fornisci il
externalTransactionTokendall'evento di download dell'app. - Nel campo
externalOfferDetails, impostaappDownloadEventExternalTransactionIdsuexternalTransactionIddell'evento di download dell'app. Gli altri campi diexternalOfferDetailsnon sono obbligatori.
- Fornisci il
Esempio di richiesta di transazione in un'app esterna scaricata tramite offerte esterne:
POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=ABC-DEF-GHI
Body
{
"originalPreTaxAmount" : {
"priceMicros" : "990000", # 0.99 EUR
"currency" : "EUR"
},
"originalTaxAmount" : {
"priceMicros" : "90000", # 0.09 EUR
"currency" : "EUR"
},
"transactionTime" : "2025-11-22T12:45:00Z",
"oneTimeTransaction" : {
"externalTransactionToken" : "my_external_transaction_token_for_link_to_download_event"
},
"userTaxAddress" : {
"regionCode" : "DE"
},
"externalOfferDetails" : {
"appDownloadEventExternalTransactionId" : "my_external_transaction_id_for_link_to_download_event"
}
}
I dettagli aggiornati della commissione di servizio di Google Play per i diversi tipi di transazioni sono disponibili nella pagina Modifiche al programma per offerte esterne per gli utenti nello Spazio economico europeo (SEE).
Segnala le transazioni successive per un acquisto
In alcuni casi, allo stesso acquisto esterno sono associati più pagamenti dell'utente, ad esempio rinnovi di abbonamenti o ricariche di piani prepagati.
Puoi segnalare queste transazioni successive utilizzando la stessa API in
Externaltransactions. Come descritto in Segnala un nuovo acquisto, il parametro externalTransactionToken non è necessario per le transazioni successive. Invece,
viene inviato un nuovo externalTransactionId univoco come parametro di query per ogni
transazione di rinnovo o ricarica, con l'ID della transazione iniziale incluso
nel campo initialExternalTransactionId.
Seguendo l'esempio precedente:
- Il primo rinnovo dell'utente 1 avviene nel sistema di fatturazione alternativo. L'ID transazione iniziale era 123-456-789.
- Lo sviluppatore segnala la ricorrenza della transazione nel parametro di query dell'URL come ID transazione esterno per questa nuova transazione, facendo riferimento all'ID transazione esterno della transazione iniziale nel campo
initialExternalTransactionId.
Esempio di richiesta:
POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=abc-def-ghi
Body
{
"originalPreTaxAmount" : {
"priceMicros" : "12634000000", # 12634 KRW
"currency" : "KRW"
},
"originalTaxAmount" : {
"priceMicros" : "1263000000", # 1263 KRW
"currency" : "KRW"
},
"transactionTime" : "2022-02-22T12:45:00Z",
"recurringTransaction" : {
"initialExternalTransactionId" : "123-456-789",
"externalSubscription" : {
"subscriptionType" : "RECURRING"
}
},
"userTaxAddress" : {
"regionCode" : "KR"
}
}
Segnala un upgrade o un downgrade
Per segnalare un upgrade o un downgrade quando l'utente possiede un abbonamento nel sistema di fatturazione alternativo, utilizza lo stesso endpoint e la stessa funzione nell'API Externaltransactions, inviando il externalTransactionToken fornito all'app per la transazione di upgrade o downgrade. Questo funziona in modo simile alla segnalazione di un nuovo acquisto.
Segnala il download di un'app
Per segnalare un'installazione dell'app nel sistema di fatturazione per offerte esterne, devi chiamare Externaltransactions.createexternaltransaction, inviando il externalTransactionToken fornito all'app. Segnala questa transazione come una transazione una tantum a costo zero. Questa procedura è simile alla segnalazione di una transazione iniziale. Assicurati di includere ExternalOfferDetails nel corpo della richiesta.
Esempio di richiesta:
POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=123-456-789
Body
{
"originalPreTaxAmount" : {
"priceMicros" : "0",
"currency" : "USD"
},
"originalTaxAmount" : {
"priceMicros" : "0",
"currency" : "USD"
},
"transactionTime" : "2025-12-22T12:45:00Z",
"oneTimeTransaction" : {
"externalTransactionToken" : "my_token",
},
"userTaxAddress" : {
"regionCode" : "US"
},
"externalOfferDetails" : {
"linkType" : "LINK_TO_APP_DOWNLOAD",
"installedAppPackage" : "my.external.app",
"installedAppCategory" : "APP"
}
}
Esegui la migrazione dalla registrazione manuale delle transazioni con fatturazione alternativa
Per eseguire la migrazione degli abbonamenti attivi iniziati mentre offrivi la fatturazione alternativa senza segnalazione automatica, crea una nuova transazione a costo zero utilizzando il campo migratedTransactionProgram anziché specificare un initialExternalTransactionId o un externalTransactionToken. Imposta transactionTime sull'ora in cui l'utente si è registrato inizialmente per ogni abbonamento attivo. In seguito, segnala ogni transazione successiva per questi abbonamenti come di consueto tramite le API, fornendo il initialExternalTransactionId utilizzato in precedenza per creare le transazioni di rinnovo.
Una volta eseguita la migrazione dell'abbonamento, non dovrai più segnalare manualmente le transazioni successive per l'abbonamento, a condizione che vengano segnalate tramite i metodi automatici descritti in questa pagina.
Durante la migrazione delle sottoscrizioni, tieni presente i limiti di quota in vigore per verificare che la migrazione non causi un'interruzione della quota. Se è necessario eseguire la migrazione di molti abbonamenti, distribuiscili su più giorni o richiedi un aumento della quota.
Il campo migratedTransactionProgram può essere utilizzato solo durante la migrazione dai report manuali. Verrà ritirato quando i report manuali non saranno più supportati.
Esempio di richiesta:
# Note that the externalTransactionId specified here will used to report
# subsequent transactions.
POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=abc-def-ghi
Body
{
# Be sure to set the price to 0 for this transaction since it does not reflect
# an actual subscription renewal.
"originalPreTaxAmount" : {
"priceMicros" : "0",
"currency" : "KRW"
},
"originalTaxAmount" : {
"priceMicros" : "0",
"currency" : "KRW"
},
# The transaction time should be set to when the user signed up for this
# subscription.
"transactionTime" : "2022-02-22T12:45:00Z",
"recurringTransaction" : {
"migratedTransactionProgram" : "USER_CHOICE_BILLING",
"externalSubscription" : {
"subscriptionType" : "RECURRING"
}
},
"userTaxAddress" : {
"regionCode" : "KR"
}
}
Requisiti per i programmi partner di Google Play
Gli sviluppatori che partecipano a programmi partner come il programma Esperienza multimediale Play devono fornire il transaction_program_code quando segnalano transazioni esterne. Se sei uno sviluppatore idoneo, contatta il tuo responsabile dello sviluppo aziendale per ulteriori informazioni su come impostare questo campo.
Segnala i rimborsi degli acquisti a Google Play
Esegui l'integrazione con l'API externaltransactions per segnalare le transazioni rimborsate agli utenti al di fuori del sistema di fatturazione di Google Play. Affinché Play possa identificare correttamente la transazione rimborsata, devi includere il externalTransactionId corrispondente alla transazione segnalata in precedenza come parte dei parametri dell'URL.
Quando segnali i rimborsi degli acquisti di abbonamenti, fai riferimento al
externalTransactionId della ricorrenza specifica dell'abbonamento che viene
rimborsato.
Esempio: Supponiamo che un abbonamento abbia le seguenti transazioni:
Una transazione iniziale con ID transazione esterno ABC.1234-5678-9012-34567
La prima transazione ricorrente con ID transazione esterno ABC.1234-5678-9012-34567..0
La seconda transazione ricorrente con ID transazione esterno ABC.1234-5678-9012-34567..1
Per segnalare un rimborso di tutte le transazioni per l'abbonamento, devi effettuare tre richieste di rimborso separate: una per la transazione iniziale e due per le transazioni successive.
Questo metodo accetta sia i rimborsi totali (in cui l'importo è lo stesso pagato dall'utente nella transazione esterna originale) sia i rimborsi parziali (in cui l'importo è inferiore a quello pagato dall'utente nella transazione esterna originale). Per i rimborsi parziali, devi specificare l'importo rimborsato al lordo delle imposte.
Quote API
L'API Externaltransactions è soggetta alle quote delle API per tutte le chiamate, proprio come qualsiasi altro endpoint nell'API Google Play Developer.
Inoltre, l'API Externaltransactions ha un limite di 1200 query al minuto (QPM) per le chiamate a Externaltransactions.createexternaltransaction o Externaltransactions.refundexternaltransaction. Le chiamate a Externaltransactions.getexternaltransaction non vengono conteggiate ai fini di questo limite di 1200 QPM.