Skip to main content
Cette page présente le SDK officiel de checkout iOS de Dodo Payments pour Swift. Il ouvre le checkout hébergé de Dodo Payments dans une vue de navigateur native et renvoie un résultat typé.

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 de paiement mobile complet.
Le SDK iOS ouvre le checkout hébergé de Dodo Payments dans SFSafariViewController et renvoie un CheckoutResult lorsque le client termine ou quitte le checkout. Il ne contient aucune clé API ni aucun code réseau, et n’appelle donc jamais l’API Dodo Payments. Le checkout s’exécute dans la vue de navigateur. Le SDK présente et ferme cette vue, puis lit le résultat à partir de l’URL de retour. Prérequis : iOS 16 ou version ultérieure, et Swift 6.2 ou version ultérieure (le package déclare swift-tools-version: 6.2). Le SDK n’a aucune dépendance tierce.

Installation

1

Add the Package

Dans Xcode, accédez à File → Add Package Dependencies et saisissez l’URL du package :
Sélectionnez la version 1.1.0 ou une version ultérieure. La personnalisation de l’apparence nécessite la version 1.1.0.Pour ajouter le package dans Package.swift à la place, ajoutez cette dépendance :
Package.swift
Le produit de bibliothèque est DodoCheckout.
2

Register a Callback URL Scheme

Enregistrez un schéma d’URL afin qu’iOS redirige l’URL de retour du checkout vers votre app. Ajoutez un type d’URL à votre Info.plist :
Info.plist
Vous pouvez également ajouter le type d’URL dans Xcode sous Info → URL Types.Utilisez ce schéma dans le returnUrl que vous transmettez au SDK, par exemple myapp://checkout/return, et définissez la même URL comme return_url de la session de checkout lorsque votre backend crée la session. Le SDK compare l’URL de retour selon le schéma, l’hôte et le chemin. L’URL n’a pas besoin de charger une page réelle.

Utilisation

DodoCheckout.start est une fonction async qui s’exécute sur l’acteur principal. Transmettez checkoutUrl sous la forme d’un URL construit à partir du checkout_url renvoyé par votre backend :
onEvent reçoit les événements .opened, .returnReceived et .closed. Leurs valeurs name sont checkout.opened, checkout.return_received et checkout.closed. Utilisez les événements uniquement pour la journalisation, jamais pour déterminer le résultat.

Transmettre l’URL de retour

SFSafariViewController ne peut pas intercepter sa propre URL de retour ; iOS ouvre donc l’URL dans votre app. Transmettez chaque URL entrante à DodoCheckout.handleOpenURL(_:). Dans une app sans scènes, appelez cette fonction depuis application(_:open:options:) de votre délégué d’application.
Vous pouvez transmettre chaque URL. handleOpenURL agit uniquement sur une URL correspondant à returnUrl du checkout en cours et renvoie true pour celle-ci. Pour toute autre URL, il renvoie false ; gérez donc cette URL vous-même.

Signification du résultat

Le SDK construit CheckoutResult à partir des paramètres de requête de l’URL de retour.
result.status est un indice 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 ponctuel) ou status=active (abonnement).
  • failed : le paiement a été refusé (status=failed).
  • cancelled : le client a fermé la feuille 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. Effectuez plutôt le rapprochement de 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. Effectuez le rapprochement comme pour 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 des clés de licence.
String?
Le paramètre de requête email. Défini lorsque le checkout collecte une adresse e-mail.
[String: String]
Chaque paramètre de requête de l’URL de retour, tel quel.

Vérifier le paiement

Webhooks

Dodo Payments appelle votre backend lorsqu’un paiement est réussi 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 moyens. Ne vous fiez pas au seul result.status.

Personnalisation de l’apparence

Pour modifier le bouton de fermeture de la feuille, le style de présentation et le schéma de couleurs, transmettez un BrowserCustomization comme customization à start(...). Chaque champ est facultatif. Pour un champ nil, le SDK ne définit pas cette option et iOS applique sa propre valeur par défaut. L’exception est presentationStyle, pour laquelle nil signifie pageSheet.
DismissButtonStyle?
Style du bouton de fermeture : done, close ou cancel. iOS détermine s’il doit être affiché sous forme de libellé ou d’icône.
PresentationStyle?
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 et ne propose aucun geste de fermeture.
Bool?
Permet à la barre d’outils de se réduire lors du défilement de la page. Cet effet est visible uniquement lorsque presentationStyle vaut fullScreen. Avec pageSheet, les barres restent fixées quelle que soit cette configuration.
ColorScheme?
light ou dark force cette apparence quels que soient les réglages système de l’appareil. system suit les réglages système. Cette option applique le thème uniquement aux contrôles natifs autour de la page. Le mode clair ou sombre de la page de checkout elle-même provient de customization.theme sur la session de checkout, et ses couleurs proviennent de customization.theme_config.
iOS ne propose aucune option de couleur pour la barre d’outils. Les propriétés de teinte sous-jacentes de SFSafariViewController sont obsolètes depuis iOS 26.

Erreurs

start lance CheckoutError uniquement en cas de mauvaise utilisation ou de défaillance de la plateforme. Lisez la raison dans error.code. L’annulation par un client ou un paiement refusé produit toujours un résultat, jamais une erreur lancée.
  • 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) : défaillance inattendue de la plateforme, par exemple lorsqu’aucun contrôleur de vue ne permet d’effectuer la présentation.
Après une erreur lancée, vérifiez également la présence d’une session abandonnée. Si la feuille n’a pas confirmé son affichage, le SDK conserve la session, car le checkout peut être encore ouvert. L’exception est alreadyInProgress : l’enregistrement trouvé appartient alors au checkout toujours en cours.

Sessions abandonnées

Le SDK enregistre la session de checkout lorsqu’il présente le checkout et ne supprime cet enregistrement que lorsque le checkout se termine avec succeeded, failed ou expired. L’enregistrement est conservé si l’app est arrêtée pendant le checkout, ainsi qu’après un résultat cancelled ou pending. Vérifiez sa présence au prochain lancement 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 checkout Date lancé. Votre backend peut rechercher la session avec Get Checkout Session, qui renvoie ses valeurs payment_id et payment_status. Tant que le paiement n’a pas atteint un statut final, considérez-le comme en attente et non comme échoué.

Contenu associé

Mobile Integration Guide

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

React Native SDK

Encapsule ce même noyau Swift sur iOS.
Dernière modification le 26 septembre 2026