Skip to main content
Questa pagina tratta l’SDK ufficiale di checkout React Native di Dodo Payments, @dodopayments/react-native-checkout. Apre il checkout ospitato di Dodo Payments in una vista browser nativa e restituisce un risultato tipizzato. Un pacchetto precedente, dodopayments-react-native-sdk (senza scope), ha un’API diversa. Questa pagina documenta solo il pacchetto con scope.

Checkout Sessions API

Crea checkout_url che questo SDK apre, dal tuo backend.

Mobile Integration Guide

Scopri come questo SDK si inserisce nel flusso completo dei pagamenti mobile.
L’SDK React Native è un Turbo Module che esegue il wrapping degli SDK di checkout nativi iOS e Android. Apre SFSafariViewController su iOS e una Custom Tab su Android. Non contiene alcuna API key né logica di checkout propria, quindi non chiama mai l’API di Dodo Payments. Il checkout viene eseguito nella vista browser. L’SDK presenta e chiude questa vista e legge il risultato dall’URL di ritorno.
Questo SDK supporta solo la New Architecture. Richiede React Native 0.77 o versioni successive, iOS 16 o versioni successive e Android minSdk 24. La tua app Android deve essere compilata con compileSdk 34 o versioni successive.

Installazione

1

Install the Package

Il pacchetto viene collegato automaticamente e recupera com.dodopayments.api:checkout-android da Maven Central.
La dipendenza nativa viene risolta automaticamente, quindi non è necessaria alcun’altra fase di installazione.
La personalizzazione dell’aspetto richiede la versione 1.2.0 o successive.
2

Register a Callback URL Scheme

Registra uno schema URL in modo che il sistema operativo reindirizzi l’URL di ritorno del checkout alla tua app.
Imposta lo schema come manifest placeholder in android/app/build.gradle:
android/app/build.gradle
Sostituisci "myapp" con lo schema della tua app.
Su ogni piattaforma, imposta lo stesso URL come return_url della sessione di checkout quando il backend crea la sessione. L’SDK confronta schema, host e percorso dell’URL di ritorno. Non è necessario che l’URL carichi una pagina reale.

Utilizzo

Chiama DodoCheckout.start con checkout_url dal tuo backend:
onEvent riceve eventi con un type di checkout.opened, checkout.return_received o checkout.closed. Usali solo per il logging, mai per decidere l’esito.

Inoltro dell’URL di ritorno

iOS richiede il listener Linking per gestire l’URL di ritorno, perché SFSafariViewController non può intercettare il proprio URL di ritorno. Su Android, handleOpenURL non fa nulla e risolve false, perché l’SDK Android intercetta nativamente il redirect. Puoi registrare il listener su entrambe le piattaforme.
Su iOS, handleOpenURL risolve true quando l’URL appartiene al checkout in corso e false per qualsiasi altro URL.

Significato del risultato

L’SDK costruisce il risultato a partire dai query parameter presenti nell’URL di ritorno.
result.status è un’indicazione per l’interfaccia, non una prova del pagamento. Conferma ogni pagamento dal tuo backend, utilizzando il webhook payment.succeeded o subscription.active.
CheckoutStatus
obbligatorio
Uno dei cinque valori:
  • succeeded: l’URL di ritorno contiene status=succeeded (pagamento una tantum) o status=active (abbonamento).
  • failed: il pagamento è stato rifiutato (status=failed).
  • cancelled: il cliente ha chiuso la vista browser prima dell’arrivo dell’URL di ritorno. L’SDK non conosce l’esito e il pagamento potrebbe essere andato a buon fine, quindi non mostrare una schermata di errore. Riconcilia invece la sessione abbandonata.
  • pending: il pagamento viene regolato in un secondo momento (status=processing o qualsiasi valore requires_*) oppure il parametro status era assente o non riconosciuto. Riconcilialo come cancelled.
  • expired: la sessione di checkout è scaduta (status=expired).
string
Il query parameter payment_id, quando l’URL di ritorno lo include. Mostralo nella tua interfaccia, ma non utilizzarlo per concedere l’accesso. Consulta Verifica il pagamento.
string
Il query parameter subscription_id. Viene impostato per i checkout con abbonamento.
string[]
Il query parameter license_key. Viene impostato quando il checkout include prodotti con license key.
string
Il query parameter email. Viene impostato quando il checkout acquisisce un indirizzo email.
Record<string, string>
Ogni query parameter dell’URL di ritorno, alla lettera.

Verifica il pagamento

Webhooks

Dodo Payments chiama il tuo backend quando un pagamento va a buon fine o un abbonamento viene attivato.

Get Payment Detail

Cerca paymentId con la tua secret key per verificarne lo stato.
Concedi l’accesso solo dopo che uno di questi metodi ha confermato il pagamento. Non affidarti al solo result.status.

Personalizzazione dell’aspetto

Per modificare la toolbar, i pulsanti e lo schema di colori del browser del checkout, passa customization a start(...). Le Custom Tabs di Android e SFSafariViewController di iOS espongono controlli nativi diversi, quindi le opzioni sono raggruppate in un oggetto android e in un oggetto ios. Ogni piattaforma legge solo il proprio oggetto. Ogni campo è facoltativo. Quando ometti un campo, la piattaforma applica il proprio valore predefinito.
string
Colore di sfondo della toolbar, come stringa esadecimale: "#RRGGBB" o "#AARRGGBB".
string
Colore della barra di navigazione, come stringa esadecimale.
string
Colore del divisore sopra la barra di navigazione, come stringa esadecimale.
'default' | 'back'
default mostra l’icona di sistema “X”. back mostra una freccia indietro disegnata dall’SDK.
'start' | 'end'
Il lato della toolbar in cui compare il pulsante di chiusura.
boolean
Mostra l’icona di condivisione della toolbar. false la nasconde.
boolean
Mostra il titolo della pagina sotto l’URL nella toolbar.
boolean
Nasconde automaticamente la toolbar mentre la pagina scorre.
boolean
Mostra “Aggiungi questa pagina ai segnalibri” nel menu overflow.
boolean
Mostra “Scarica pagina” nel menu overflow.
'system' | 'light' | 'dark'
light o dark forza questo aspetto indipendentemente dall’impostazione di sistema del dispositivo. system segue l’impostazione di sistema.
'done' | 'close' | 'cancel'
Stile del pulsante di chiusura. iOS decide se visualizzarlo come etichetta o icona.
'pageSheet' | 'fullScreen'
pageSheet (il valore predefinito) presenta una scheda che il cliente può chiudere scorrendo verso il basso. fullScreen occupa l’intero schermo.
boolean
Consente alla toolbar di comprimersi mentre la pagina scorre. Ha effetto visibile solo quando presentationStyle è fullScreen. Con pageSheet, le barre restano fisse indipendentemente da questa impostazione.
'system' | 'light' | 'dark'
light o dark forza questo aspetto indipendentemente dall’impostazione di sistema del dispositivo. system segue l’impostazione di sistema.
iOS non dispone di un’opzione per il colore della toolbar, perché le proprietà tint di SFSafariViewController sottostanti sono deprecate a partire da iOS 26.

Errori

start viene rifiutato con un CheckoutError solo in caso di uso errato o di un errore della piattaforma. Leggi il motivo da error.code. L’annullamento da parte del cliente o un pagamento rifiutato producono sempre un risultato, mai un rifiuto.
  • INVALID_CHECKOUT_URL: checkoutUrl non è un URL di sessione di checkout https (percorso che inizia con /session/) su checkout.dodopayments.com o test.checkout.dodopayments.com.
  • INVALID_RETURN_URL: returnUrl non è un URL assoluto con schema e host.
  • ALREADY_IN_PROGRESS: è in esecuzione un altro checkout. È possibile eseguire un solo checkout alla volta.
  • PLATFORM_ERROR: errore imprevisto della piattaforma. L’SDK segnala con questo codice anche qualsiasi errore nativo non riconosciuto.

Sessioni abbandonate

L’SDK nativo registra la sessione di checkout quando il checkout inizia e cancella il record solo quando il checkout termina con succeeded, failed o expired. Il record rimane quando l’app o il bundle JavaScript vengono terminati durante il checkout, causando la perdita della promise start, e dopo un risultato cancelled o pending. Verifica la presenza del record al successivo mount e dopo ogni risultato cancelled o pending:
abandoned.sessionId è l’ID della sessione di checkout, che inizia con cks_. abandoned.createdAt indica quando è iniziato il checkout Date. Il tuo backend può cercare la sessione con Get Checkout Session, che restituisce payment_id e payment_status. Finché il pagamento non raggiunge uno stato finale, consideralo in sospeso, non fallito.

Correlati

Mobile Integration Guide

Lo stesso contratto per Android, iOS e Flutter.

Expo Boilerplate

Un esempio Expo completo con integrazione del checkout.
Ultima modifica il 26 settembre 2026