Skip to main content

Checkout Sessions

Créez une page de paiement sécurisée et hébergée pour les paiements ponctuels et les abonnements.

Payment Links

Partagez une URL pour collecter des paiements sans code.

Webhooks

Écoutez les événements de paiement et traitez les commandes.

API Reference

Documentation complète des endpoints et tests en direct.

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.
L’exemple de webhook utilise également le package 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 le checkout_url renvoyé.
Chaque checkout_url ne fonctionne qu’une fois et expire après 24 heures, ou après 15 minutes lorsque vous transmettez confirm: true. Avec confirm: true, vous devez également fournir tous les champs obligatoires. Créez une nouvelle session pour chaque client et chaque tentative de paiement.

Créer une session Checkout

Rediriger vers le checkout

Après avoir créé une session, redirigez le client vers le checkout_url :
Pour une personnalisation avancée, consultez le guide complet Sessions Checkout et l’API Reference.

Gérer les erreurs

Lorsqu’une requête échoue, l’API renvoie un code d’état HTTP et un corps JSON contenant un code 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. 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ètre session, afin qu’un actualisation de la page les conserve. Un payment link statique est une URL que vous créez une fois et partagez plusieurs fois. L’URL de base est la suivante :
Ajoutez des paramètres de requête pour personnaliser le checkout :
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.
paymentAmount utilise les unités monétaires principales (12.5 correspond à $12.50). Le champ product_cart[].amount de l’API Checkout Sessions utilise la plus petite unité monétaire (1250 correspond à $12.50). Consultez Dynamic Pricing.
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’indicateur disable... correspondant sur true :
La désactivation des champs empêche les modifications accidentelles et garantit la cohérence des données.
Les endpoints POST /payments et POST /subscriptions sont obsolètes. Pour les nouvelles intégrations, utilisez plutôt Checkout Sessions.
Pour les intégrations existantes qui utilisent des payment links dynamiques, transmettez payment_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.

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’environnement DODO_PAYMENTS_WEBHOOK_KEY. Voici un exemple utilisant Next.js :
app/api/webhooks/dodo/route.ts
Notre implémentation des webhooks suit la spécification Standard Webhooks.

Événements à écouter

Dans un flux de paiement ponctuel, écoutez au minimum les événements suivants :
Traitez toujours la commande à partir de payment.succeeded reçu du webhook, et non depuis la redirection du navigateur. La redirection peut être manquée si le client ferme l’onglet, tandis que le webhook est réessayé jusqu’à réception d’un accusé.
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, transmettez billing_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 son payment_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.

Pages associées

Checkout Sessions

Guide complet avec des options de personnalisation avancées.

Overlay Checkout

Intégrez le checkout sous forme de fenêtre modale superposée à votre page.

Inline Checkout

Intégrez directement le checkout à la mise en page de votre page.

Subscription Integration

Configurez la facturation récurrente.

Webhook Event Guide

Liste complète de tous les événements webhook.

API Reference

Documentation de l’API Checkout Sessions.
Dernière modification le 8 octobre 2026