L'API Google Play Developer include funzionalità aggiuntive per segnalare le transazioni dai programmi di fatturazione e collegamento. 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 backend. Per crearli, devi configurare l'integrazione del backend come indicato in Configurare l'API Google Play Developer. Per creare funzionalità di backend per sviluppatori non specifiche per la fatturazione e i programmi di collegamento, consulta Sistema di fatturazione di Google Play.
Glossario dei termini
Convenzioni terminologiche seguite da questa guida:
- Programmi di fatturazione e collegamento: 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 offerte esterne.
- API per transazioni esterne: API utilizzate per segnalare le transazioni per i programmi di fatturazione e collegamento idonei.
- Transazione esterna: una transazione idonea che si verifica al di fuori dell'app, come definito dai requisiti del programma. Sono inclusi acquisti di contenuti digitali e download di app.
- Token di transazione esterna: un token fornito tramite la libreria Play Billing da utilizzare quando l'utente completa una transazione esterna. Questo token viene utilizzato per comunicare a Google Play l'esito positivo di una transazione esterna.
- ID transazione esterno: un identificatore univoco generato da te per identificare una transazione esterna.
Segnalare 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 $ derivanti da acquisti di prove senza costi e
installazioni di app. Devi avviare e segnalare le transazioni nei programmi di fatturazione e collegamento
solo per i paesi degli utenti idonei, come consentito dalle linee guida
relative alla fatturazione alternativa o alle offerte esterne;
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 collegamento.
Ciò vale per tutte le transazioni, inclusi addebiti iniziali, rinnovi, rimborsi
e altro ancora. Consulta le linee guida per i rispettivi programmi di fatturazione e collegamento 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 nell'acquisto ricorrente come parametro per 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 è scaduta e lo stesso prodotto viene acquistato di nuovo in un secondo momento. Non devi includere informazioni che consentono l'identificazione personale, proprietarie o riservate come parte di questo ID transazione esterno.
Segnalare una transazione iniziale
Ogni volta che un nuovo acquisto o download di app va a buon fine nei programmi di fatturazione e collegamento, devi chiamare l'API externaltransactions.
externalTransactionToken ricevuta dall'app tramite i callback
UserChoiceBillingListener, AlternativeBillingOnlyReportingDetailsListener o BillingProgramReportingDetailsListener è obbligatoria come parte
del corpo della richiesta per i download di app, gli acquisti singoli e le transazioni
iniziali in 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 maggiori dettagli su come segnalare le transazioni successive, consulta la sezione Segnalare 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, per 12.634,10 KRW al mese, con un'offerta di prova senza costi di un mese. - L'app avvia il flusso di acquisto con il
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 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 aggiuntivi. - Dopo che la transazione per l'acquisto avviene nel sistema di fatturazione alternativo, lo sviluppatore segnala la transazione a Google Play con la seguente richiesta. Inizialmente viene segnalata come transazione a 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, un preordine potrebbe avere una transazione iniziale di 0 € seguita da una seconda transazione in un secondo momento per il prezzo dello SKU quando il preordine viene completato. Per ulteriori dettagli sulla segnalazione delle transazioni successive, consulta la sezione Segnalare le transazioni successive per un acquisto.- Devi fornire
ExternalOfferDetailsquando invii report sulle transazioni iniziali di offerte esterne. Questa operazione non è necessaria per le transazioni successive.
Se effettui transazioni con un utente in India in cui l'imposta dipende dalla sua
area amministrativa (ad esempio uno stato o una provincia), includi quest'area in
userTaxAddress. Per le aree amministrative applicabili, consulta l'elenco predefinito di
stringhe nella guida di riferimento dell'API.
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 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, vedi Segnalare il download di un'app. - Quando segnali le transazioni relative a offerte di contenuti digitali, imposta
linkTypesuLINK_TO_DIGITAL_CONTENT. - Dopo l'installazione di un'app esterna tramite il programma per offerte esterne, devi
segnalare le transazioni effettuate nell'app esterna. Quando le segnali, collega queste transazioni all'evento di download dell'app originale:
- Fornisci
externalTransactionTokendall'evento di download dell'app. - Nel campo
externalOfferDetails, impostaappDownloadEventExternalTransactionIdsuexternalTransactionIddell'evento di download dell'app. Gli altri campi inexternalOfferDetailsnon sono obbligatori.
- Fornisci
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": "100000",
"currency": "EUR"
},
"originalTaxAmount" : {
"priceMicros": "10000",
"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 transazione sono disponibili nella sezione Modifiche al programma per offerte esterne per gli utenti dello Spazio economico europeo (SEE).
Segnalare transazioni successive per un acquisto
In alcuni casi, a uno stesso acquisto esterno sono associati più pagamenti 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
externalTransactionToken non è necessario per le transazioni successive. Al contrario,
un nuovo externalTransactionId univoco viene inviato 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 sul 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",
"currency": "KRW"
},
"originalTaxAmount" : {
"priceMicros": "1263000000",
"currency": "KRW"
},
"transactionTime" : "2022-02-22T12:45:00Z",
"recurringTransaction" : {
"initialExternalTransactionId": "123-456-789",
"externalSubscription" {
"subscriptionType": "RECURRING"
}
},
"userTaxAddress" : {
"regionCode": "KR"
}
}
Segnalare un upgrade o un downgrade
Per segnalare un upgrade o un downgrade quando l'utente possiede un abbonamento nel
sistema di fatturazione alternativo, utilizzi lo stesso endpoint e la stessa funzione nell'API
Externaltransactions, inviando externalTransactionToken fornito
all'app per la transazione di upgrade o downgrade. Il funzionamento è simile a quello della segnalazione di un nuovo acquisto.
Segnalare il download di un'app
Per segnalare un'installazione di app nel sistema di fatturazione delle offerte esterne, devi
chiamare Externaltransactions.createexternaltransaction e inviare
externalTransactionToken fornito all'app. Segnala questa operazione come
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 generazione manuale di report sulle transazioni di fatturazione alternativa
Per eseguire la migrazione degli abbonamenti attivi iniziati mentre offrivi la fatturazione alternativa
senza report automatizzati, 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 ha eseguito la registrazione iniziale per ogni abbonamento attivo. Successivamente, segnala ogni transazione successiva per questi
abbonamenti normalmente 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 degli abbonamenti, 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 dalla
reportistica manuale. Verrà ritirato quando il reporting manuale non sarà più
supportato.
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 l'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.
Segnalare 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. Per consentire a Google Play di identificare correttamente la transazione rimborsata, devi includere il externalTransactionId corrispondente alla transazione segnalata in precedenza come parte dei parametri 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 relative all'abbonamento, devi effettuare tre richieste di rimborso distinte: una per la transazione iniziale e due per le transazioni successive.
Questo metodo accetta sia i rimborsi completi (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 al lordo delle imposte che è stato rimborsato.
Quote API
L'API Externaltransactions è soggetta a quote API per
tutte le chiamate, proprio come qualsiasi altro endpoint dell'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.