Skip to main content
Questa pagina illustra il pacchetto Flutter ufficiale di Dodo Payments, dodopayments_checkout su pub.dev. Esiste anche un pacchetto separato sviluppato dalla community. Consulta Progetti della community.

Checkout Sessions API

Crea dal tuo backend il checkout_url che questo SDK apre.

Mobile Integration Guide

Scopri come questo SDK si inserisce nel flusso completo dei pagamenti mobile.
dodopayments_checkout apre il checkout ospitato di Dodo Payments in SFSafariViewController su iOS e in una Custom Tab su Android, quindi restituisce un CheckoutResult tipizzato. Utilizza lo stesso codice nativo degli SDK standalone per iOS e Android, e tutta la logica del checkout risiede in quel codice nativo. Il livello Dart inoltra ogni chiamata attraverso un canale tipizzato Pigeon. Il pacchetto non contiene alcuna chiave API e non chiama mai l’API di Dodo Payments. Requisiti: Flutter 3.44 o versioni successive con Dart 3.12 o versioni successive, iOS 16 o versioni successive e Android minSdk 23.

Installazione

1

Add the Dependency

Aggiungi il pacchetto a pubspec.yaml:
pubspec.yaml
La personalizzazione dell’aspetto richiede la versione 1.1.0 o successive.Il plugin Android compila per impostazione predefinita con Android SDK 35. Se un altro plugin richiede un compileSdk superiore, imposta dodoCompileSdk nel gradle.properties della tua app.
2

Register a Callback URL Scheme

Registra uno schema URL affinché il sistema operativo reindirizzi l’URL di ritorno del checkout alla tua app. Usa questo schema nell’returnUrl che passi all’SDK e imposta lo stesso URL come return_url della sessione di checkout quando il backend crea la sessione. Non è necessario che l’URL carichi una pagina reale.
Aggiungi un tipo URL per il tuo schema in ios/Runner/Info.plist:
ios/Runner/Info.plist
SFSafariViewController non può intercettare il proprio URL di ritorno, quindi iOS apre l’URL nella tua app. Inoltra ogni URL in arrivo all’SDK, ad esempio da app_links:
Puoi inoltrare ogni URL. handleOpenURL agisce solo su un URL che corrisponde all’returnUrl del checkout in corso e risolve true per esso. Per qualsiasi altro URL, risolve false. Su Android, risolve sempre false.

Utilizzo

Chiama DodoCheckout.instance.start con il checkout_url dal tuo backend:
onEvent riceve eventi il cui type è CheckoutEventType.opened, returnReceived oppure closed. Usali solo per il logging, mai per decidere l’esito.

Significato del risultato

L’SDK crea CheckoutResult dai parametri di query presenti nell’URL di ritorno.
result.status è un suggerimento dell’interfaccia, non una prova del pagamento. Conferma ogni pagamento dal tuo backend, con il webhook payment.succeeded o subscription.active.
CheckoutStatus
obbligatorio
Uno di 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 del browser prima dell’arrivo dell’URL di ritorno. L’SDK non conosce l’esito e il pagamento potrebbe essere riuscito, quindi non mostrare una schermata di errore. Riconcilia invece la sessione abbandonata.
  • pending: il pagamento viene regolato in seguito (status=processing o qualsiasi valore payment_status), oppure il parametro status era assente o non riconosciuto. Riconcilialo come cancelled.
  • expired: la sessione di checkout è scaduta (status=expired).
String?
Il parametro di query payment_id, quando l’URL di ritorno lo include. Mostralo nell’interfaccia, ma non usarlo per concedere l’accesso. Consulta Verifica il pagamento.
String?
Il parametro di query subscription_id. Impostato per i checkout degli abbonamenti.
List<String>?
Il parametro di query license_key. Impostato quando il checkout include prodotti con chiavi di licenza.
String?
Il parametro di query email. Impostato quando il checkout acquisisce un indirizzo email.
Map<String, String>
Ogni parametro di query dell’URL di ritorno, alla lettera.

Verifica il pagamento

Webhooks

Dodo Payments chiama il tuo backend quando un pagamento ha esito positivo 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 elementi ha confermato il pagamento. Non affidarti solo a result.status.

Personalizzazione dell’aspetto

Per modificare la barra degli strumenti, i pulsanti e la combinazione di colori del browser del checkout, passa un BrowserCustomization come customization su CheckoutParams. Le Custom Tab Android e SFSafariViewController iOS espongono controlli nativi diversi, quindi le opzioni sono suddivise in AndroidBrowserOptions e IosBrowserOptions. Ogni piattaforma ignora le opzioni dell’altra. Ogni campo è facoltativo e per impostazione predefinita vale null. Per un campo null, l’SDK non imposta tale opzione e la piattaforma applica il proprio valore predefinito.
Color?
Colore di sfondo della barra degli strumenti.
Color?
Colore della barra di navigazione.
Color?
Colore del separatore sopra la barra di navigazione.
CloseButtonStyle?
standard mostra l’icona di sistema “X”. back mostra una freccia indietro disegnata dall’SDK.
CloseButtonPosition?
Il lato della barra degli strumenti in cui appare il pulsante di chiusura: start o end.
bool?
Mostra l’icona di condivisione della barra degli strumenti. false la nasconde.
bool?
Mostra il titolo della pagina sotto l’URL nella barra degli strumenti.
bool?
Nasconde automaticamente la barra degli strumenti mentre la pagina scorre.
bool?
Mostra “Aggiungi questa pagina ai segnalibri” nel menu overflow.
bool?
Mostra “Scarica pagina” nel menu overflow.
BrowserColorScheme?
light o dark forza quell’aspetto indipendentemente dall’impostazione di sistema del dispositivo. system segue l’impostazione di sistema.
DismissButtonStyle?
Stile del pulsante di chiusura: done, close o cancel. iOS decide se visualizzarlo come etichetta o icona.
PresentationStyle?
pageSheet (usato quando lasci questo null) presenta una scheda che il cliente può scorrere verso il basso per chiudere. fullScreen copre l’intero schermo.
bool?
Consente alla barra degli strumenti di comprimersi mentre la pagina scorre. Ha effetto visibile solo quando presentationStyle è fullScreen. Con pageSheet, le barre restano fisse indipendentemente da questa impostazione.
BrowserColorScheme?
light o dark forza quell’aspetto indipendentemente dall’impostazione di sistema del dispositivo. system segue l’impostazione di sistema.
iOS non dispone di un’opzione per il colore della barra degli strumenti, perché le proprietà tint sottostanti di SFSafariViewController sono deprecate a partire da iOS 26.

Errori

start genera CheckoutException solo in caso di uso errato o di un errore della piattaforma. Leggi il motivo da code, un CheckoutErrorCode. La stringa del codice nativo si trova in nativeCode. Un cliente che annulla, o un pagamento rifiutato, è sempre un risultato, mai un’eccezione.
  • invalidCheckoutUrl (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.
  • invalidReturnUrl (INVALID_RETURN_URL): returnUrl non è un URL assoluto con schema e host.
  • alreadyInProgress (ALREADY_IN_PROGRESS): è in esecuzione un altro checkout. È possibile eseguire un solo checkout alla volta.
  • platformError (PLATFORM_ERROR): errore imprevisto della piattaforma. Anche gli errori nativi sconosciuti vengono mappati su questo codice.

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 se l’app viene terminata durante il checkout e dopo un risultato cancelled o pending. Verificalo al successivo avvio e dopo ogni risultato cancelled o pending.
abandoned.sessionId è l’ID della sessione di checkout, che inizia con cks_. abandoned.createdAt è l’DateTime avviato dal checkout. 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 React Native.

Community Projects

Esiste anche un pacchetto Flutter separato sviluppato dalla community.
Ultima modifica il 26 settembre 2026