Cette page présente le SDK officiel de checkout React Native de Dodo Payments,
@dodopayments/react-native-checkout. Il ouvre le checkout hébergé de Dodo Payments dans une vue de navigateur native et renvoie un résultat typé. Un ancien package, dodopayments-react-native-sdk (non étendu), possède une API différente. Cette page documente uniquement le package étendu.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 au flux complet de paiement mobile.
SFSafariViewController sur iOS et un Custom Tab sur Android. Il ne contient aucune clé API et ne possède aucune logique de checkout propre : il n’appelle donc jamais l’API Dodo Payments. Le checkout s’exécute dans la vue de navigateur. Le SDK affiche et ferme cette vue, puis lit le résultat depuis l’URL de retour.
Installation
1
Install the Package
- Android
- iOS
- Expo
Le package est lié automatiquement et récupère La dépendance native est résolue automatiquement : aucune autre étape d’installation n’est nécessaire.
com.dodopayments.api:checkout-android depuis Maven Central.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.Sur chaque plateforme, définissez la même URL que celle de
- Android (Gradle)
- iOS (Info.plist)
- iOS (Info.plist)
- Expo (both platforms)
- Expo (both platforms)
Définissez le schéma comme espace réservé de manifeste dans
android/app/build.gradle :Remplacez "myapp" par le schéma de votre application.return_url de la session de checkout lors de sa création par votre backend. Le SDK compare le schéma, l’hôte et le chemin de l’URL de retour. L’URL n’a pas besoin de charger une page réelle.Utilisation
AppelezDodoCheckout.start avec le checkout_url provenant de votre backend :
onEvent reçoit des événements dont le type est checkout.opened, checkout.return_received ou checkout.closed. Utilisez-les uniquement pour la journalisation, jamais pour déterminer le résultat.
Transférer l’URL de retour
iOS nécessite l’écouteurLinking pour gérer l’URL de retour, car SFSafariViewController ne peut pas intercepter sa propre URL de retour. Sur Android, handleOpenURL n’effectue aucune action et résout false, car le SDK Android intercepte nativement sa redirection. Vous pouvez enregistrer l’écouteur sur les deux plateformes.
string
Défini lorsque l’URL de retour en contient un. Affichez-le dans l’interface, mais ne l’utilisez pas pour accorder l’accès. Consultez la section Vérifier le paiement ci-dessous.
handleOpenURL résout true lorsque l’URL appartient au checkout en cours, et false pour toute autre URL.
Signification du résultat
Le SDK construit le résultat à partir des paramètres de requête de l’URL de retour.CheckoutStatus
requis
L’une des cinq valeurs suivantes :
succeeded: l’URL de retour contientstatus=succeeded(paiement unique) oustatus=active(abonnement).failed: le paiement a été refusé (status=failed).cancelled: le client a fermé la vue de navigateur avant l’arrivée de l’URL de retour. Le SDK ne connaît pas le résultat et le paiement peut avoir été effectué ; 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=processingou toute valeurrequires_*), ou le paramètrestatusétait absent ou non reconnu. Réconciliez-le commecancelled.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.string[]
Le paramètre de requête
license_key. Défini lorsque le checkout inclut des produits avec clé de licence.string
Le paramètre de requête
email. Défini lorsque le checkout collecte une adresse e-mail.Record<string, string>
Chaque paramètre de requête de l’URL de retour, mot pour mot.
Vérifier le paiement
Webhooks
Dodo Payments appelle votre backend lorsqu’un paiement est effectué ou qu’un abonnement est activé.
Get Payment Detail
Recherchez
paymentId avec votre clé secrète pour vérifier son statut.result.status.
Personnalisation de l’apparence
Pour modifier la barre d’outils, les boutons et le jeu de couleurs du navigateur de checkout, transmettezcustomization à start(...). Les Custom Tabs Android et SFSafariViewController d’iOS exposent des contrôles natifs différents ; les options sont donc regroupées dans un objet android et un objet ios. Chaque plateforme ne lit que son propre objet. Tous les champs sont facultatifs. Lorsqu’un champ est omis, la plateforme applique sa propre valeur par défaut.
boolean
Affiche le titre de la page sous l’URL dans la barre d’outils.
Couleur d’arrière-plan de la barre d’outils, sous forme de chaîne hexadécimale :
"#RRGGBB" ou "#AARRGGBB".Couleur de la barre de navigation, sous forme de chaîne hexadécimale.
'default' | 'back'
Couleur du séparateur au-dessus de la barre de navigation, sous forme de chaîne hexadécimale.
'default' | 'back'
default affiche l’icône système « X ». back affiche une flèche de retour dessinée par le SDK.'start' | 'end'
Côté de la barre d’outils où apparaît le bouton de fermeture.
Affiche l’icône de partage de la barre d’outils.
false la masque.boolean
Affiche le titre de la page sous l’URL dans la barre d’outils.
boolean
Masque automatiquement la barre d’outils lorsque la page défile.
boolean
Affiche « Ajouter cette page aux favoris » dans le menu de débordement.
boolean
Affiche « Télécharger la page » dans le menu de débordement.
'system' | 'light' | 'dark'
light ou dark force cette apparence quel que soit le réglage système de l’appareil. system suit le réglage système.Erreurs
'done' | 'close' | 'cancel'
Style du bouton de fermeture. iOS décide s’il s’affiche sous forme de libellé ou d’icône.
'pageSheet' | 'fullScreen'
pageSheet (valeur par défaut) présente une carte que le client peut faire glisser vers le bas pour la fermer. fullScreen couvre tout l’écran.boolean
Permet à la barre d’outils de se réduire lorsque la page défile. Cela n’a d’effet visible que lorsque
presentationStyle vaut fullScreen. Avec pageSheet, les barres restent fixes, quel que soit ce réglage.'system' | 'light' | 'dark'
light ou dark force cette apparence quel que soit le réglage système de l’appareil. system suit le réglage système.SFSafariViewController sont obsolètes depuis iOS 26.
Mobile Integration Guide
Le même contrat pour Android, iOS et Flutter.
Expo Boilerplate
Un exemple Expo complet avec intégration de checkout.
Erreurs
start est rejeté avec un CheckoutError uniquement en cas de mauvaise utilisation ou d’échec de la plateforme. Lisez la raison dans error.code. L’annulation par un client ou un paiement refusé produit toujours un résultat, jamais un rejet.
INVALID_CHECKOUT_URL:checkoutUrln’est pas une URL de session de checkouthttps(chemin commençant par/session/) surcheckout.dodopayments.comoutest.checkout.dodopayments.com.INVALID_RETURN_URL:returnUrln’est pas une URL absolue avec un schéma et un hôte.ALREADY_IN_PROGRESS: un autre checkout est en cours. Un seul checkout peut être exécuté à la fois.PLATFORM_ERROR: échec inattendu de la plateforme. Le SDK signale également toute erreur native non reconnue avec ce code.
Sessions abandonnées
Le SDK natif enregistre la session de checkout au démarrage du checkout et n’efface cet enregistrement que lorsque le checkout se termine avecsucceeded, failed ou expired. L’enregistrement est conservé si l’application ou le bundle JavaScript est arrêté pendant le checkout, ce qui fait perdre la promesse start, ainsi qu’après un résultat cancelled ou pending. Vérifiez sa présence lors du prochain montage et après chaque résultat cancelled ou pending :
abandoned.sessionId est l’identifiant de la session de checkout, qui commence par cks_. abandoned.createdAt correspond au Date du démarrage du checkout. Votre backend peut rechercher la session avec Get Checkout Session, 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 Flutter.
Expo Boilerplate
Un exemple Expo complet avec intégration du checkout.