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 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
pubspec.yaml:pubspec.yaml
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.- iOS
- Android
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
ChiamaDodoCheckout.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 creaCheckoutResult dai parametri di query presenti nell’URL di ritorno.
CheckoutStatus
obbligatorio
Uno di 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 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=processingo qualsiasi valorepayment_status), oppure il parametrostatusera assente o non riconosciuto. Riconcilialo comecancelled.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.result.status.
Personalizzazione dell’aspetto
Per modificare la barra degli strumenti, i pulsanti e la combinazione di colori del browser del checkout, passa unBrowserCustomization 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.
Android — Custom Tab
Android — Custom Tab
Color?
Colore di sfondo della barra degli strumenti.
Colore della barra di navigazione.
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.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.iOS — SFSafariViewController
iOS — SFSafariViewController
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.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):checkoutUrlnon è un URL di sessione di checkouthttps(percorso che inizia con/session/) sucheckout.dodopayments.comotest.checkout.dodopayments.com.invalidReturnUrl(INVALID_RETURN_URL):returnUrlnon è 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.