Skip to main content

Prerequisites

To integrate the Dodo Payments API, you’ll need:
  • A Dodo Payments merchant account
  • API Credentials (API key and webhook secret key) from dashboard

Dashboard Setup

  1. Navigate to the Dodo Payments Dashboard
  2. Créez un produit (paiement unique ou abonnement). Les produits par abonnement doivent être tarifés à au moins $1 (ou l’équivalent dans la devise choisie) ; les montants inférieurs à ce minimum ne sont pas pris en charge.
  3. Generate your API key:
    • Go to Developer > API
    • Detailed Guide
    • Copy the API key the in env named DODO_PAYMENTS_API_KEY
  4. Configure webhooks:
    • Go to Developer > Webhooks
    • Create a webhook URL for payment notifications
    • Copy the webhook secret key in env

Integration

Choisissez le parcours d’intégration adapté à votre cas d’utilisation :
  • Checkout Sessions (recommandé) : idéal pour la plupart des intégrations. Créez une session sur votre serveur, puis redirigez les clients vers une page de paiement sécurisée et hébergée.
  • Overlay Checkout : à utiliser lorsque vous avez besoin d’une expérience dans la page qui ouvre le paiement sous forme de fenêtre modale superposée à votre site.
  • Inline Checkout : intégrez directement le paiement dans la mise en page de votre page pour une expérience entièrement intégrée et personnalisée.
  • Static Payment Links : des URL sans code, immédiatement partageables, pour collecter rapidement des paiements.
  • Dynamic Payment Links : des liens créés par programmation. Toutefois, Checkout Sessions est recommandé et offre davantage de flexibilité.
  • Mobile Checkout SDKs : pour les applications natives Android, iOS, React Native et Flutter. Créez la session sur votre serveur comme indiqué ci-dessus, puis transmettez checkout_url au SDK.
Overlay Checkout et Inline Checkout sont réservés aux navigateurs : ils intègrent le paiement dans une page web. Si vous développez une application mobile native, créez la session de paiement sur votre serveur et ouvrez-la avec les Mobile Checkout SDKs à la place.

1. Checkout Sessions

Utilisez Checkout Sessions pour créer une expérience de paiement sécurisée, hébergée, pour les paiements uniques ou les abonnements. Vous créez une session sur votre serveur, puis redirigez le client vers checkout_url renvoyé.
Les Checkout Sessions sont valides pendant 24 heures par défaut. Si vous transmettez confirm=true, les sessions sont valides pendant 15 minutes et tous les champs obligatoires doivent être fournis.
1

Create a checkout session

Choisissez votre SDK préféré ou appelez l’API REST.
2

Redirect customer to checkout

Après la création de la session, redirigez vers checkout_url pour démarrer le parcours hébergé.
Privilégiez Checkout Sessions pour commencer à accepter des paiements de la manière la plus rapide et la plus fiable. Pour une personnalisation avancée, consultez le guide Checkout Sessions complet et la référence de l’API.

2. Overlay Checkout

Pour une expérience de paiement fluide dans la page, découvrez notre intégration Overlay Checkout, qui permet aux clients de finaliser leurs paiements sans quitter votre site.

3. Inline Checkout

Pour des expériences de paiement entièrement intégrées directement dans votre page, utilisez notre intégration Inline Checkout. Elle vous permet de créer des récapitulatifs de commande personnalisés et de contrôler entièrement la mise en page du paiement, tandis que Dodo Payments gère la collecte des paiements en toute sécurité. Les Static Payment Links vous permettent d’accepter rapidement des paiements en partageant une URL simple. Vous pouvez personnaliser l’expérience de paiement en transmettant des paramètres de requête pour préremplir les informations client, contrôler les champs du formulaire et ajouter des métadonnées personnalisées.
1

Construct your payment link

Commencez par l’URL de base et ajoutez votre identifiant de produit :
2

Add core parameters

Incluez les paramètres de requête essentiels :
  • integer
    défaut:"1"
    Nombre d’articles à acheter.
  • string
    requis
    URL de redirection après la finalisation du paiement.
L’URL de redirection inclura 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 les clés de licence sont activées pour le produit, un paramètre license_key est également ajouté (séparé par des virgules pour plusieurs clés) :
https://example.com/?payment_id=pay_xxx&status=succeeded&license_key=LK-001&email=customer%40example.com
3

Pre-fill customer information (optional)

Ajoutez les champs client ou de facturation comme paramètres de requête pour simplifier le paiement.
  • 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.
  • string
    Adresse postale.
  • string
    Ville.
  • string
    État ou province.
  • string
    Code postal/ZIP.
  • boolean
    true ou false
4

Control form fields (optional)

Vous pouvez désactiver certains champs afin de les rendre accessibles en lecture seule pour le client. Cette option est utile lorsque vous disposez déjà des informations du client (par exemple, pour les utilisateurs connectés).
Pour désactiver un champ, fournissez sa valeur et définissez l’indicateur disable… correspondant sur true :
La désactivation des champs contribue à empêcher les modifications accidentelles et garantit la cohérence des données.
La définition de showDiscounts=false désactive et masque la section des remises dans le formulaire de paiement. Utilisez cette option si vous souhaitez empêcher les clients de saisir des codes de réduction ou promotionnels lors du paiement.
5

Add advanced controls (optional)

  • 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.
  • integer
    Montant en centimes (uniquement pour la tarification Pay What You Want).
  • string
    Champs de métadonnées personnalisés (par exemple, metadata_orderId=123).
6

Share the link

Envoyez le lien de paiement finalisé à votre client. Lorsqu’il le consulte, tous les paramètres de requête sont collectés et enregistrés avec un identifiant de session. L’URL est ensuite simplifiée pour ne contenir que le paramètre de session (par exemple, ?session=sess_1a2b3c4d). Les informations enregistrées persistent après les actualisations de la page et sont accessibles pendant tout le processus de paiement.
L’expérience de paiement du client est désormais simplifiée et personnalisée en fonction de vos paramètres.
Privilégiez Checkout Sessions pour la plupart des cas d’utilisation : cette solution offre davantage de flexibilité et de contrôle.
Créé via un appel d’API ou notre SDK avec les informations du client. Voici un exemple : Il existe deux API pour créer des liens de paiement dynamiques : Le guide ci-dessous explique comment créer un lien de paiement unique. Pour obtenir des instructions détaillées sur l’intégration des abonnements, consultez ce guide d’intégration des abonnements.
Assurez-vous de transmettre payment_link = true pour obtenir le lien de paiement
Après la création du lien de paiement, redirigez vos clients pour qu’ils finalisent leur paiement.

Implémentation des Webhooks

Configurez un endpoint d’API pour recevoir les notifications de paiement. Voici un exemple utilisant Next.js :
Notre implémentation des Webhooks suit la spécification Standard Webhooks. Pour les définitions des types de Webhooks, consultez notre guide des événements Webhook.

Événements à écouter

Activez payload.type et gérez les événements pertinents pour un parcours de paiement unique. Au minimum, écoutez les événements suivants :
Exécutez toujours la commande sur payment.succeeded depuis le Webhook, et non lors de la redirection du navigateur : la redirection peut être manquée si le client ferme l’onglet, tandis que le Webhook est réessayé jusqu’à ce qu’il soit confirmé.
Si vous vendez des produits numériques avec des clés de licence, gérez également license_key.created. Pour consulter la liste complète des événements — notamment les événements liés aux abonnements, aux droits, aux crédits, à la récupération et au recouvrement — consultez le guide des événements Webhook. Vous pouvez consulter ce projet, qui contient une implémentation de démonstration, sur GitHub, avec Next.js et TypeScript. Vous pouvez consulter l’implémentation en ligne ici.

Points essentiels à connaître sur Checkout et les devises

Les montants dynamiques (Pay-What-You-Want) sont exprimés dans la devise de base du produit, et non dans une devise locale arbitraire. La devise de base est limitée à USD, INR, GBP et EUR. Pour collecter un montant fixe dans une autre devise (par exemple, PHP), vous ne pouvez pas le transmettre directement : utilisez Adaptive Pricing (qui convertit votre montant de base selon le taux de change en vigueur) ou Localized Pricing (prix fixe par devise, mais incompatible avec Pay-What-You-Want).
Définissez explicitement la devise. Transmettez billing_currency et billing_address.country dans la Checkout Session. Si ces paramètres sont omis, la devise et le pays sont détectés à partir de l’adresse IP du client (Adaptive Currency) et peuvent ne pas correspondre à ce que vous souhaitez facturer.
Les Checkout Sessions expirent au bout de 24 heures (15 minutes lorsque confirm: true est utilisé), et chaque checkout_url est à usage unique : générez une nouvelle session pour chaque client et chaque tentative de paiement au lieu de réutiliser un lien.
Achat répété en un clic. Pour un client récurrent disposant d’un moyen de paiement enregistré, transmettez payment_method_id avec confirm: true pour le débiter instantanément, sans passer par la sélection du moyen de paiement.

Référence de l’API associée

Create Checkout Session

Référence de l’API pour créer des Checkout Sessions sécurisées et hébergées pour les paiements uniques et les abonnements

Create Payment Link

Référence de l’API pour créer des liens de paiement dynamiques par programmation
Dernière modification le 31 juillet 2026