Skip to main content
Cette page présente le package Flutter officiel de Dodo Payments, dodopayments_checkout sur pub.dev. Un package distinct, développé par la communauté, existe également. Consultez Projets communautaires.

Checkout Sessions API

Créez depuis votre backend le checkout_url que ce SDK ouvre.

Mobile Integration Guide

Découvrez comment ce SDK s’intègre dans le flux complet de paiement mobile.
dodopayments_checkout ouvre le checkout hébergé de Dodo Payments dans SFSafariViewController sur iOS et dans un Custom Tab sur Android, puis renvoie un CheckoutResult typé. Il utilise le même code natif que les SDK autonomes iOS et Android, et toute la logique du checkout réside dans ce code natif. La couche Dart transmet chaque appel via un canal Pigeon typé. Le package ne contient aucune clé API et n’appelle jamais l’API Dodo Payments. Prérequis : Flutter 3.44 ou version ultérieure avec Dart 3.12 ou version ultérieure, iOS 16 ou version ultérieure, et Android minSdk 23.

Installation

1

Add the Dependency

Ajoutez le package à pubspec.yaml :
pubspec.yaml
La personnalisation de l’apparence nécessite la version 1.1.0 ou une version ultérieure.Le plugin Android compile par défaut avec Android SDK 35. Si un autre plugin nécessite un compileSdk supérieur, définissez dodoCompileSdk dans le gradle.properties de votre application.
2

Register a Callback URL Scheme

Enregistrez un schéma d’URL afin que le système d’exploitation redirige l’URL de retour du checkout vers votre application. Utilisez ce schéma dans le returnUrl transmis au SDK, et définissez la même URL comme return_url de la session de checkout lorsque votre backend crée la session. L’URL n’a pas besoin de charger une page réelle.
Ajoutez un type d’URL pour votre schéma dans ios/Runner/Info.plist :
ios/Runner/Info.plist
SFSafariViewController ne peut pas intercepter sa propre URL de retour. iOS ouvre donc l’URL dans votre application. Transmettez chaque URL entrante au SDK, par exemple depuis app_links :
Vous pouvez transmettre chaque URL. handleOpenURL agit uniquement sur une URL correspondant au returnUrl du checkout en cours et résout true pour celle-ci. Pour toute autre URL, il résout false. Sur Android, il résout toujours false.

Utilisation

Appelez DodoCheckout.instance.start avec le checkout_url provenant de votre backend :
onEvent reçoit les événements dont le type est CheckoutEventType.opened, returnReceived ou closed. Utilisez-les uniquement pour la journalisation, jamais pour déterminer le résultat.

Signification du résultat

Le SDK construit CheckoutResult à partir des paramètres de requête de l’URL de retour.
result.status est un indicateur d’interface, pas une preuve de paiement. Confirmez chaque paiement à partir de votre backend, avec le webhook payment.succeeded ou subscription.active.
CheckoutStatus
requis
L’une des cinq valeurs suivantes :
  • succeeded : l’URL de retour contient status=succeeded (paiement ponctuel) ou status=active (abonnement).
  • failed : le paiement a été refusé (status=failed).
  • cancelled : le client a fermé la vue du navigateur avant l’arrivée de l’URL de retour. Le SDK ne connaît pas le résultat et le paiement peut avoir abouti ; n’affichez donc pas d’écran d’échec. Réconciliez plutôt la session abandonnée.
  • pending : le paiement est réglé ultérieurement (status=processing ou toute valeur requires_*), ou le paramètre status était absent ou non reconnu. Réconciliez-le comme cancelled.
  • expired : la session de checkout a expiré (status=expired).
String?
Le paramètre de requête payment_id, lorsque l’URL de retour en contient un. Affichez-le dans votre interface, mais ne l’utilisez pas pour accorder l’accès. Consultez Vérifier le paiement.
String?
Le paramètre de requête subscription_id. Défini pour les checkouts d’abonnement.
List<String>?
Le paramètre de requête license_key. Défini lorsque le checkout inclut des produits avec des clés de licence.
String?
Le paramètre de requête email. Défini lorsque le checkout recueille une adresse e-mail.
Map<String, String>
Chaque paramètre de requête de l’URL de retour, textuellement.

Vérifier le paiement

Webhooks

Dodo Payments appelle votre backend lorsqu’un paiement réussit ou qu’un abonnement est activé.

Get Payment Detail

Recherchez paymentId avec votre clé secrète pour vérifier son statut.
Accordez l’accès uniquement après confirmation du paiement par l’un de ces éléments. Ne vous fiez pas uniquement à result.status.

Personnalisation de l’apparence

Pour modifier la barre d’outils, les boutons et le schéma de couleurs du navigateur de checkout, transmettez un BrowserCustomization comme customization à CheckoutParams. Les Custom Tabs Android et SFSafariViewController iOS exposent des contrôles natifs différents ; les options sont donc réparties entre AndroidBrowserOptions et IosBrowserOptions. Chaque plateforme ignore les options de l’autre. Tous les champs sont facultatifs et prennent par défaut la valeur null. Pour un champ null, le SDK ne définit pas cette option et la plateforme applique sa propre valeur par défaut.
Color?
Couleur d’arrière-plan de la barre d’outils.
Color?
Couleur de la barre de navigation.
Color?
Couleur du séparateur situé au-dessus de la barre de navigation.
CloseButtonStyle?
standard affiche l’icône système « X ». back affiche une flèche de retour dessinée par le SDK.
CloseButtonPosition?
Côté de la barre d’outils où apparaît le bouton de fermeture : start ou end.
bool?
Affiche l’icône de partage de la barre d’outils. false la masque.
bool?
Affiche le titre de la page sous l’URL dans la barre d’outils.
bool?
Masque automatiquement la barre d’outils lorsque la page défile.
bool?
Affiche « Ajouter cette page aux favoris » dans le menu de débordement.
bool?
Affiche « Télécharger la page » dans le menu de débordement.
BrowserColorScheme?
light ou dark impose cette apparence quel que soit le réglage système de l’appareil. system suit le réglage système.
DismissButtonStyle?
Style du bouton de fermeture : done, close ou cancel. iOS détermine s’il est affiché sous forme de libellé ou d’icône.
PresentationStyle?
pageSheet (utilisé lorsque vous laissez ce null) présente une carte que le client peut faire glisser vers le bas pour la fermer. fullScreen couvre tout l’écran.
bool?
Permet à la barre d’outils de se réduire lorsque la page défile. Cet effet n’est visible que lorsque presentationStyle est fullScreen. Avec pageSheet, les barres restent fixes quel que soit ce réglage.
BrowserColorScheme?
light ou dark impose cette apparence quel que soit le réglage système de l’appareil. system suit le réglage système.
iOS ne propose aucune option de couleur pour la barre d’outils, car les propriétés de teinte sous-jacentes de SFSafariViewController sont obsolètes depuis iOS 26.

Erreurs

start lève CheckoutException uniquement en cas de mauvaise utilisation ou d’échec de la plateforme. Lisez la cause dans code, un CheckoutErrorCode. La chaîne de code native se trouve dans nativeCode. L’annulation par un client ou le refus d’un paiement produit toujours un résultat, jamais une exception.
  • invalidCheckoutUrl (INVALID_CHECKOUT_URL) : checkoutUrl n’est pas une URL de session de checkout https (chemin commençant par /session/) sur checkout.dodopayments.com ou test.checkout.dodopayments.com.
  • invalidReturnUrl (INVALID_RETURN_URL) : returnUrl n’est pas une URL absolue avec un schéma et un hôte.
  • alreadyInProgress (ALREADY_IN_PROGRESS) : un autre checkout est en cours. Un seul checkout peut être exécuté à la fois.
  • platformError (PLATFORM_ERROR) : échec inattendu de la plateforme. Les erreurs natives inconnues sont également associées à ce code.

Sessions abandonnées

Le SDK natif enregistre la session de checkout au démarrage du checkout et n’efface l’enregistrement que lorsque le checkout se termine avec succeeded, failed ou expired. L’enregistrement est conservé si l’application est arrêtée pendant le checkout, ainsi qu’après un résultat cancelled ou pending. Recherchez-le au prochain lancement et après chaque résultat cancelled ou pending.
abandoned.sessionId est l’ID de session de checkout, qui commence par cks_. abandoned.createdAt correspond au moment où le checkout DateTime a commencé. Votre backend peut rechercher la session avec Obtenir la session de checkout, qui renvoie son payment_id et son payment_status. Tant que le paiement n’a pas atteint un statut final, considérez-le comme en attente et non comme échoué.

Pages associées

Mobile Integration Guide

Le même contrat pour Android, iOS et React Native.

Community Projects

Un package Flutter distinct, développé par la communauté, existe également.
Dernière modification le 26 septembre 2026