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.
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.
Installazione
1
Install the Package
- Android
- iOS
- Expo
Il pacchetto viene collegato automaticamente e recupera La dipendenza nativa viene risolta automaticamente, quindi non è necessaria alcun’altra fase di installazione.
com.dodopayments.api:checkout-android da Maven Central.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.Su ogni piattaforma, imposta lo stesso URL come
- Android (Gradle)
- iOS (Info.plist)
- Expo (both platforms)
Imposta lo schema come manifest placeholder in Sostituisci
android/app/build.gradle:android/app/build.gradle
"myapp" con lo schema della tua app.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
ChiamaDodoCheckout.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 listenerLinking 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.
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.CheckoutStatus
obbligatorio
Uno dei cinque valori:
succeeded: l’URL di ritorno contienestatus=succeeded(pagamento una tantum) ostatus=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=processingo qualsiasi valorerequires_*) oppure il parametrostatusera assente o non riconosciuto. Riconcilialo comecancelled.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.result.status.
Personalizzazione dell’aspetto
Per modificare la toolbar, i pulsanti e lo schema di colori del browser del checkout, passacustomization 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.
Android — Custom Tab
Android — Custom Tab
string
Colore di sfondo della toolbar, come stringa esadecimale:
"#RRGGBB" o "#AARRGGBB".Colore della barra di navigazione, come stringa esadecimale.
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.
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.iOS — SFSafariViewController
iOS — SFSafariViewController
'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.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:checkoutUrlnon è un URL di sessione di checkouthttps(percorso che inizia con/session/) sucheckout.dodopayments.comotest.checkout.dodopayments.com.INVALID_RETURN_URL:returnUrlnon è 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 consucceeded, 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.