Skip to main content
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.
Le SDK React Native est un Turbo Module qui encapsule les SDK de checkout natifs iOS et Android. Il ouvre 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.
Ce SDK prend uniquement en charge la Nouvelle architecture. Il nécessite React Native 0.77 ou une version ultérieure, iOS 16 ou une version ultérieure, ainsi qu’Android minSdk 24. Votre application Android doit être compilée avec compileSdk 34 ou une version ultérieure.

Installation

1

Install the Package

Le package est lié automatiquement et récupère com.dodopayments.api:checkout-android depuis Maven Central.
La dépendance native est résolue automatiquement : aucune autre étape d’installation n’est nécessaire.
La personnalisation de l’apparence nécessite la version 1.2.0 ou une version ultérieure.
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.
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.
Sur chaque plateforme, définissez la même URL que celle de 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

Appelez DodoCheckout.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’écouteur Linking 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.
Sur iOS, 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.
result.status est un indicateur d’interface, et non une preuve de paiement. Confirmez chaque paiement depuis 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 unique) ou status=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=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.
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.
N’accordez l’accès qu’après confirmation du paiement par l’un de ces moyens. Ne vous fiez pas uniquement à result.status.

Personnalisation de l’apparence

Pour modifier la barre d’outils, les boutons et le jeu de couleurs du navigateur de checkout, transmettez customization à 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.
string
Couleur d’arrière-plan de la barre d’outils, sous forme de chaîne hexadécimale : "#RRGGBB" ou "#AARRGGBB".
string
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.
boolean
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.
iOS ne propose aucune option de couleur de barre d’outils, car les propriétés de teinte sous-jacentes 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 : 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.
  • INVALID_RETURN_URL : returnUrl n’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 avec succeeded, 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.
Dernière modification le 26 septembre 2026