Checkout Sessions
Payment Links
Webhooks
API Reference
Prérequis
Avant de commencer, vous avez besoin des éléments suivants :- Un compte Dodo Payments.
- Au moins un produit. Créez-le sous Products dans le dashboard. Un produit d’abonnement avec un prix non nul doit respecter le minimum d’abonnement pour la devise dans laquelle le client paie : $1.00 pour USD. Les devises autres que USD, EUR et GBP doivent également représenter au moins $1.00. Un abonnement à $0 est également pris en charge.
- Une clé API. Créez-la sous Developer → API Keys et stockez-la dans la variable d’environnement
DODO_PAYMENTS_API_KEY. Créez la clé en mode test pendant le développement : les exemples de cette page utilisent le mode test, et une clé en mode test ne fonctionne qu’avec le mode test. Consultez Authentication. - Le SDK correspondant à votre langage. Le SDK Node.js nécessite Node.js 20 ou une version ultérieure, le SDK Python nécessite Python 3.9 ou une version ultérieure, et le SDK Go nécessite Go 1.22 ou une version ultérieure. Les exemples cURL ne nécessitent aucun SDK.
standardwebhooks. Installez-le avec npm install standardwebhooks.
Choisir une méthode d’intégration
Le checkout Overlay et le checkout Inline fonctionnent uniquement dans une page web. Dans une application mobile native, créez la session Checkout sur votre serveur et ouvrez son
checkout_url avec un SDK de checkout mobile.
Pour qu’un agent de programmation crée cette intégration pour vous, installez le plugin Agent.
Sessions Checkout
Créez une expérience de checkout sécurisée et hébergée. Vous créez une session sur votre serveur, puis redirigez le client vers lecheckout_url renvoyé.
Créer une session Checkout
- Node.js SDK
- Python SDK
- cURL
Rediriger vers le checkout
Après avoir créé une session, redirigez le client vers lecheckout_url :
Gérer les erreurs
Lorsqu’une requête échoue, l’API renvoie un code d’état HTTP et un corps JSON contenant uncode et un message. Fondez votre gestion des erreurs sur code, et non sur message. Pour connaître chaque code, sa cause et la manière de le résoudre, consultez Error Codes. Un paiement échoué est signalé séparément : le status du paiement vaut failed, son error_code indique la raison, et vous recevez un webhook payment.failed. Pour décider s’il faut réessayer, consultez Handle Payment Failures.
Payment Links
Un payment link est une URL qui ouvre le checkout pour un produit, afin que vous puissiez collecter des paiements sans écrire de code. Les paramètres de requête préremplissent les informations du client et contrôlent le formulaire de checkout. Lorsqu’un client ouvre le lien, le checkout stocke les paramètres dans une session et raccourcit l’URL en un paramètresession, afin qu’un actualisation de la page les conserve.
Payment Links statiques
Un payment link statique est une URL que vous créez une fois et partagez plusieurs fois. L’URL de base est la suivante :integer
défaut:"1"
Nombre d’articles à acheter.
string
requis
Les payment links utilisent
redirect_url. L’API Checkout Sessions utilise return_url dans le même but.URL vers laquelle rediriger après le paiement. Dodo Payments ajoute les détails du paiement sous forme de paramètres de requête, par exemple https://example.com/?payment_id=pay_ts2ySpzg07phGeBZqePbH&status=succeeded&email=customer%40example.com. Si le produit émet des clés de licence, un paramètre license_key est également ajouté, avec plusieurs clés séparées par des virgules.string
Spécifie la devise du paiement. Par défaut, il s’agit de la devise du pays de facturation.
boolean
défaut:"true"
Affiche ou masque le sélecteur de devise.
boolean
défaut:"true"
Affiche ou masque la section des remises. Définissez cette valeur sur
false pour empêcher les clients de saisir des codes promo.number
Fixe le montant facturé, dans les unités monétaires principales, par exemple
12.5 pour $12.50. Fonctionne uniquement avec les produits Pay What You Want et est ignoré s’il est inférieur au prix minimum du produit.string
Champs de métadonnées personnalisés, par exemple
metadata_orderId=123.Préremplir les informations client
Ajoutez les champs client en tant que paramètres de requête pour simplifier le checkout :string
Nom complet du client (ignoré si firstName ou lastName est fourni).
string
Prénom du client.
string
Nom du client.
string
Adresse e-mail du client.
string
Pays du client (code ISO 3166-1 alpha-2).
string
Adresse.
string
Ville.
string
État ou province.
string
Code postal ou ZIP.
Désactiver les champs du formulaire
Pour empêcher les clients de modifier les informations préremplies, désactivez un champ en fournissant sa valeur et en définissant l’indicateurdisable... correspondant sur true :
Exemple de payment link statique
Payment Links dynamiques (obsolètes)
Pour les intégrations existantes qui utilisent des payment links dynamiques, transmettezpayment_link: true à Create One-Time Payment ou Create Subscription pour créer un lien. Les exemples ci-dessous créent un payment link pour un paiement ponctuel. Pour les abonnements, consultez le Subscription Integration Guide.
- Node.js SDK
- Python SDK
- Go SDK
Webhooks
Les webhooks indiquent à votre serveur lorsqu’un paiement réussit ou échoue, afin que vous puissiez traiter la commande.Créer un endpoint webhook
Accédez à Developer → Webhooks dans le dashboard et ajoutez l’URL de votre endpoint. Copiez le secret de signature de l’endpoint dans la variable d’environnementDODO_PAYMENTS_WEBHOOK_KEY.
Voici un exemple utilisant Next.js :
app/api/webhooks/dodo/route.ts
Événements à écouter
Dans un flux de paiement ponctuel, écoutez au minimum les événements suivants :
Si vous vendez des produits avec des clés de licence, gérez également
license_key.created. Pour obtenir la liste complète des événements, notamment les événements d’abonnement, d’ayant droit, de crédit, de récupération et de relance, consultez le Webhook Event Guide.
Pour consulter un exemple complet avec Next.js et TypeScript, consultez le dépôt de démonstration et son déploiement en ligne.
Devise et adresse de facturation
Pour facturer dans une devise spécifique, transmettezbilling_currency et billing_address.country lors de la création de la session Checkout. Si vous les omettez, Adaptive Currency sélectionne la devise et le pays à partir de l’adresse IP du client, qui peuvent ne pas correspondre à la devise dans laquelle vous souhaitez facturer.
Les montants Pay What You Want sont exprimés dans la devise de base du produit, qui doit être USD, GBP ou EUR. Pour percevoir un montant fixe dans une autre devise, utilisez Adaptive Currency, qui convertit votre prix de base aux taux de change en vigueur, ou Localized Pricing, qui définit un prix fixe par devise. Localized Pricing ne fonctionne pas avec Pay What You Want.
Achat répété en un clic
Pour facturer un client existant avec un moyen de paiement enregistré, transmettez sonpayment_method_id avec confirm: true. payment_method_id est accepté uniquement lorsque confirm vaut true, et vous devez également transmettre le customer_id du client existant. Comme confirm vaut true, vous devez également transmettre un billing_address complet, ou uniquement country et zipcode lorsque minimal_address vaut true. La session débite directement le moyen de paiement enregistré et ne renvoie donc aucun checkout_url. Utilisez les webhooks pour savoir si le paiement a réussi.