Passer au contenu principal

Documentation Index

Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt

Use this file to discover all available pages before exploring further.

Checkout Handler

Intégrez le paiement Dodo Payments dans votre application Express.

Customer Portal

Permettez aux clients de gérer leurs abonnements et leurs informations.

Webhooks

Recevez et traitez les événements webhook de Dodo Payments.

​
Installation

1

Install the package

Exécutez la commande suivante à la racine de votre projet :
npm install @dodopayments/express
2

Set up environment variables

Créez un .env à la racine de votre projet :
DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_ENVIRONMENT="test_mode" or "live_mode"
DODO_PAYMENTS_RETURN_URL=your-return-url
Ne validez jamais votre .env ni vos secrets dans un système de contrôle de version.

​
Exemples de Gestionnaires de Routes

Utilisez ce gestionnaire pour intégrer le paiement Dodo Payments dans votre application Express. Il prend en charge les flux de paiement statiques (GET), dynamiques (POST) et de session (POST).
import { checkoutHandler } from '@dodopayments/express';

app.get('/api/checkout', checkoutHandler({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
    type: "static"
}))

app.post('/api/checkout', checkoutHandler({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
    type: "dynamic"
}))

app.post('/api/checkout', checkoutHandler({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
    type: "session"
}))

curl --request GET \
--url 'https://example.com/api/checkout?productId=pdt_fqJhl7pxKWiLhwQR042rh' \
--header 'User-Agent: insomnia/11.2.0' \
--cookie mode=test

curl --request POST \
--url https://example.com/api/checkout \
--header 'Content-Type: application/json' \
--header 'User-Agent: insomnia/11.2.0' \
--cookie mode=test \
--data '{
"billing": {
  "city": "Texas",
  "country": "US",
  "state": "Texas",
  "street": "56, hhh",
  "zipcode": "560000"
},
"customer": {
  "email": "test@example.com",
  	"name": "test"
},
"metadata": {},
"payment_link": true,
  "product_id": "pdt_QMDuvLkbVzCRWRQjLNcs",
  "quantity": 1,
  "billing_currency": "USD",
  "discount_code": "IKHZ23M9GQ",
  "return_url": "https://example.com",
  "trial_period_days": 10
}'

curl --request POST \
--url https://example.com/api/checkout \
--header 'Content-Type: application/json' \
--header 'User-Agent: insomnia/11.2.0' \
--cookie mode=test \
--data '{
"product_cart": [
  {
    "product_id": "pdt_QMDuvLkbVzCRWRQjLNcs",
    "quantity": 1
  }
],
"customer": {
  "email": "test@example.com",
  "name": "test"
},
"return_url": "https://example.com/success"
}'

​
Gestionnaire de Route de Paiement

Dodo Payments prend en charge trois types de flux de paiement pour intégrer des paiements à votre site Web ; cet adaptateur prend en charge tous les types de flux de paiement.
  • Liens de Paiement Statique : URL partageables instantanément pour une collecte de paiement rapide et sans code.
  • Liens de Paiement Dynamique : Générer des liens de paiement de manière programmatique avec des détails personnalisés en utilisant l’API ou les SDK.
  • Sessions de Paiement : Créez des expériences de paiement sécurisées et personnalisables avec des paniers de produits préconfigurés et des détails clients.

​
Paramètres de requête

​
productId
string
requis
Identifiant du produit (par exemple, ?productId=pdt_nZuwz45WAs64n3l07zpQR).
​
quantity
integer
Quantité du produit.
​
fullName
string
Nom complet du client.
​
firstName
string
Prénom du client.
​
lastName
string
Nom de famille du client.
​
email
string
Adresse e-mail du client.
​
country
string
Pays du client.
​
addressLine
string
Adresse du client.
​
city
string
Ville du client.
​
state
string
État/ province du client.
​
zipCode
string
Code postal du client.
​
disableFullName
boolean
Désactiver le champ nom complet.
​
disableFirstName
boolean
Désactiver le champ prénom.
​
disableLastName
boolean
Désactiver le champ nom de famille.
​
disableEmail
boolean
Désactiver le champ e-mail.
​
disableCountry
boolean
Désactiver le champ pays.
​
disableAddressLine
boolean
Désactiver le champ adresse.
​
disableCity
boolean
Désactiver le champ ville.
​
disableState
boolean
Désactiver le champ état.
​
disableZipCode
boolean
Désactiver le champ code postal.
​
paymentCurrency
string
Spécifiez la devise de paiement (par exemple, USD).
​
showCurrencySelector
boolean
Afficher le sélecteur de devise.
​
paymentAmount
integer
Spécifiez le montant du paiement (par exemple, 1000 pour 10,00 $).
​
showDiscounts
boolean
Afficher les champs de remise.
​
metadata_*
string
Tout paramètre de requête commençant par metadata_ sera transmis en tant que métadonnée.
Si productId est manquant, le gestionnaire renvoie une réponse 400. Les paramètres de requête non valides entraînent également une réponse 400.

​
Format de Réponse

Le paiement statique renvoie une réponse JSON avec l’URL de paiement :
{
  "checkout_url": "https://checkout.dodopayments.com/..."
}

​
Format de Réponse

Le paiement dynamique renvoie une réponse JSON avec l’URL de paiement :
{
  "checkout_url": "https://checkout.dodopayments.com/..."
}
Les sessions de paiement offrent une expérience de paiement hébergée plus sécurisée qui gère le flux de paiement complet pour les achats ponctuels et les abonnements avec un contrôle total de la personnalisation.Référez-vous au Guide d’Intégration des Sessions de Paiement pour plus de détails et une liste complète des champs pris en charge.

​
Format de Réponse

Les sessions de paiement renvoient une réponse JSON avec l’URL de paiement :
{
  "checkout_url": "https://checkout.dodopayments.com/session/..."
}

​
Gestionnaire de Route du Portail Client

Le Gestionnaire de Route du Portail Client vous permet d’intégrer de manière transparente le portail client Dodo Payments dans votre application Express.

​
Paramètres de requête

​
customer_id
string
requis
L’ID client pour la session du portail (par exemple, ?customer_id=cus_123).
​
send_email
boolean
Si défini sur true, envoie un e-mail au client contenant le lien du portail.
Renvoie 400 si customer_id est manquant.

​
Gestionnaire de Route de Webhook

  • Méthode : Seules les requêtes POST sont prises en charge. D’autres méthodes renvoient 405.
  • Vérification de Signature : Vérifie la signature du webhook en utilisant webhookKey. Renvoie 401 si la vérification échoue.
  • Validation de Charge Utile : Validée avec Zod. Renvoie 400 pour les charges utiles invalides.
  • Gestion des Erreurs :
    • 401 : Signature invalide
    • 400 : Charge utile invalide
    • 500 : Erreur interne lors de la vérification
  • Routage des Événements : Appelle le gestionnaire d’événements approprié en fonction du type de charge utile.

​
Gestionnaires d’événements webhook pris en charge

onPayload?: (payload: WebhookPayload) => Promise<void>;
onPaymentSucceeded?: (payload: WebhookPayload) => Promise<void>;
onPaymentFailed?: (payload: WebhookPayload) => Promise<void>;
onPaymentProcessing?: (payload: WebhookPayload) => Promise<void>;
onPaymentCancelled?: (payload: WebhookPayload) => Promise<void>;
onRefundSucceeded?: (payload: WebhookPayload) => Promise<void>;
onRefundFailed?: (payload: WebhookPayload) => Promise<void>;
onDisputeOpened?: (payload: WebhookPayload) => Promise<void>;
onDisputeExpired?: (payload: WebhookPayload) => Promise<void>;
onDisputeAccepted?: (payload: WebhookPayload) => Promise<void>;
onDisputeCancelled?: (payload: WebhookPayload) => Promise<void>;
onDisputeChallenged?: (payload: WebhookPayload) => Promise<void>;
onDisputeWon?: (payload: WebhookPayload) => Promise<void>;
onDisputeLost?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionActive?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionOnHold?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionRenewed?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionPlanChanged?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionCancelled?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionFailed?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionExpired?: (payload: WebhookPayload) => Promise<void>;
onSubscriptionUpdated?: (payload: WebhookPayload) => Promise<void>;
onLicenseKeyCreated?: (payload: WebhookPayload) => Promise<void>;
onAbandonedCheckoutDetected?: (payload: WebhookPayload) => Promise<void>;
onAbandonedCheckoutRecovered?: (payload: WebhookPayload) => Promise<void>;
onDunningStarted?: (payload: WebhookPayload) => Promise<void>;
onDunningRecovered?: (payload: WebhookPayload) => Promise<void>;
onCreditAdded?: (payload: WebhookPayload) => Promise<void>;
onCreditDeducted?: (payload: WebhookPayload) => Promise<void>;
onCreditExpired?: (payload: WebhookPayload) => Promise<void>;
onCreditRolledOver?: (payload: WebhookPayload) => Promise<void>;
onCreditRolloverForfeited?: (payload: WebhookPayload) => Promise<void>;
onCreditOverageCharged?: (payload: WebhookPayload) => Promise<void>;
onCreditManualAdjustment?: (payload: WebhookPayload) => Promise<void>;
onCreditBalanceLow?: (payload: WebhookPayload) => Promise<void>;

​
Invite pour LLM

Vous êtes un assistant développeur expert en Express.js. Votre tâche est de guider un utilisateur à travers l'intégration de l'adaptateur @dodopayments/express dans son projet Express.js existant.

L'adaptateur @dodopayments/express fournit des gestionnaires de routes pour les fonctionnalités de Paiement, Portail Client et Webhook de Dodo Payments, conçues pour s'intégrer directement dans une application Express.

Tout d'abord, installez le package nécessaire. Utilisez le gestionnaire de packages approprié pour le projet de l'utilisateur (npm, yarn ou bun) :

npm install @dodopayments/express

---

Voici comment vous devriez structurer votre réponse :

1. Demandez à l'utilisateur quelles fonctionnalités il souhaite intégrer.

"Quelles parties de l'adaptateur @dodopayments/express aimeriez-vous intégrer dans votre projet ? Vous pouvez choisir une ou plusieurs des options suivantes :

- Gestionnaire de Route de Paiement (pour gérer les paiements de produits)
- Gestionnaire de Route du Portail Client (pour gérer les abonnements/détails des clients)
- Gestionnaire de Route de Webhook (pour recevoir les événements webhook de Dodo Payments)
- Tout (intégrer les trois)"

---

2. En fonction de la sélection de l'utilisateur, fournissez des étapes d'intégration détaillées pour chaque fonctionnalité choisie.

---

**Si le Gestionnaire de Route de Paiement est sélectionné :**

**Objectif** : Ce gestionnaire gère différents types de flux de paiement. Tous les types de paiement (statique, dynamique et sessions) renvoient des réponses JSON avec des URL de paiement pour un traitement programmatique.

**Intégration** :
Créez des routes dans votre application Express pour les paiements statiques (GET), dynamiques (POST) et les sessions de paiement (POST).

import { checkoutHandler } from '@dodopayments/express';

app.get('/api/checkout', checkoutHandler({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  type: "static"
}));

app.post('/api/checkout', checkoutHandler({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  type: "dynamic"
}));

// Pour les sessions de paiement
app.post('/api/checkout', checkoutHandler({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  type: "session"
}));

Options de Configuration :

    bearerToken : Votre clé API Dodo Payments (recommandé d'être stocké dans la variable d'environnement DODO_PAYMENTS_API_KEY).

    returnUrl (optionnel) : URL pour rediriger l'utilisateur après un paiement réussi.

    environment : "test_mode" ou "live_mode"

    type : "static" (GET), "dynamic" (POST), ou "session" (POST)

GET (paiement statique) attend des paramètres de requête :

    productId (requis)

    quantity, champs client (fullName, email, etc.), et métadonnées (metadata_*) sont optionnels.

    Renvoie : {"checkout_url": "https://checkout.dodopayments.com/..."}

POST (paiement dynamique) attend un corps JSON avec les détails de paiement (unique ou abonnement). Référez-vous à la documentation pour le schéma complet du POST :

    Paiements uniques : https://docs.dodopayments.com/api-reference/payments/post-payments

    Abonnements : https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions

    Renvoie : {"checkout_url": "https://checkout.dodopayments.com/..."}

POST (sessions de paiement) - (Recommandé) Une expérience de paiement plus personnalisable. Renvoie JSON avec checkout_url : Les paramètres sont envoyés sous forme de corps JSON. Prend en charge les paiements uniques et récurrents. Renvoie : {"checkout_url": "https://checkout.dodopayments.com/session/..."}. Pour une liste complète des champs pris en charge, référez-vous à :

  Guide d'Intégration des Sessions de Paiement : https://docs.dodopayments.com/developer-resources/checkout-session

Si le Gestionnaire de Route du Portail Client est sélectionné :

Objectif : Cette route permet aux clients de gérer leurs abonnements via le portail Dodo Payments.

Intégration :

import { CustomerPortal } from "@dodopayments/express";

app.get('/api/customer-portal', CustomerPortal({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
}));

Paramètres de Requête :

    customer_id (requis) : par exemple, ?customer_id=cus_123

    send_email (optionnel) : si vrai, le client reçoit par e-mail le lien du portail

Renvoie 400 si customer_id est manquant.

Si le Gestionnaire de Route de Webhook est sélectionné :

Objectif : Traite les événements webhook entrants de Dodo Payments pour déclencher des événements dans votre application.

Intégration :

import { Webhooks } from "@dodopayments/express";

app.post('/api/webhook', Webhooks({
  webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
  onPayload: async (payload) => {
    // Traitez la charge utile générique
  },
  // Vous pouvez également fournir des gestionnaires spécifiques pour chaque type d'événement ci-dessous
}));

Fonctionnalités :

    Seule la méthode POST est autorisée — les autres renvoient 405

    La vérification de signature est effectuée en utilisant webhookKey. Renvoie 401 si invalide.

    Validation de charge utile basée sur Zod. Renvoie 400 si le schéma est invalide.

    Tous les gestionnaires sont des fonctions asynchrones.

Gestionnaires d'Événements Webhook Supportés :

Vous pouvez passer n'importe lequel des gestionnaires suivants :

    onPayload

    onPaymentSucceeded

    onPaymentFailed

    onPaymentProcessing

    onPaymentCancelled

    onRefundSucceeded

    onRefundFailed

    onDisputeOpened, onDisputeExpired, onDisputeAccepted, onDisputeCancelled, onDisputeChallenged, onDisputeWon, onDisputeLost

    onSubscriptionActive, onSubscriptionOnHold, onSubscriptionRenewed, onSubscriptionPlanChanged, onSubscriptionCancelled, onSubscriptionFailed, onSubscriptionExpired, onSubscriptionUpdated

    onLicenseKeyCreated

    onAbandonedCheckoutDetected, onAbandonedCheckoutRecovered

    onDunningStarted, onDunningRecovered

    onCreditAdded, onCreditDeducted, onCreditExpired, onCreditRolledOver, onCreditRolloverForfeited, onCreditOverageCharged, onCreditManualAdjustment, onCreditBalanceLow

Configuration des variables d'environnement :

Assurez-vous de définir ces variables d'environnement dans votre projet :

DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_ENVIRONMENT="test_mode" or "live_mode"
DODO_PAYMENTS_RETURN_URL=your-return-url

Utilisez-les dans votre code comme suit :

process.env.DODO_PAYMENTS_API_KEY
process.env.DODO_PAYMENTS_WEBHOOK_SECRET

Remarque sur la sécurité : Ne committez pas les secrets dans le contrôle de version. Utilisez des fichiers .env localement et des gestionnaires de secrets dans les environnements de déploiement (e.g., AWS, Vercel, Heroku, etc.).
Last modified on May 4, 2026