Indicazioni per l'integrazione del backend per la monetizzazione al di fuori di Fatturazione Google Play

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:

  1. Uno sviluppatore configura e attiva la fatturazione alternativa nella sua app.
  2. 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.
  3. L'app avvia il flusso di acquisto con ProductDetails per product1 e l'offerta selezionata dall'utente.
  4. L'utente 1 seleziona il sistema di fatturazione alternativo dello sviluppatore.
  5. UserChoiceBillingListener riceve il valore my_token come externalTransactionToken.
  6. Lo sviluppatore invia quindi le informazioni pertinenti al proprio backend (valore externalTransactionToken e prodotti acquistati). Dopodiché, avviano il flusso di acquisto per product1 nel 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.
  7. 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:

  • subscriptionType può essere RECURRING (per gli abbonamenti con rinnovo automatico) o PREPAID (per gli abbonamenti prepagati).
  • OtherRecurringProduct deve 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 ExternalOfferDetails quando 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 linkType su LINK_TO_APP_DOWNLOAD e fornisci i valori appropriati per installedAppPackage e installedAppCategory. Per maggiori dettagli, consulta Segnalare il download di un'app.
  • Quando generi report sulle transazioni di offerte di contenuti digitali, imposta linkType su LINK_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 externalTransactionToken dall'evento di download dell'app.
    • Nel campo externalOfferDetails, imposta appDownloadEventExternalTransactionId su externalTransactionId dell'evento di download dell'app. Gli altri campi di externalOfferDetails non sono obbligatori.

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:

  1. Il primo rinnovo dell'utente 1 avviene nel sistema di fatturazione alternativo. L'ID transazione iniziale era 123-456-789.
  2. 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.