Adaptateur Express - Dodo Payments Documentation

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

Install the package

Exécutez la commande suivante à la racine de votre projet :

npm install @dodopayments/express

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

Checkout Handler
Customer Portal Handler
Webhook Handler

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_codes": ["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"
}'

Utilisez ce gestionnaire pour permettre aux clients de gérer leurs abonnements et leurs informations via le portail client Dodo Payments.

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

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

curl --request GET \
--url 'https://example.com/api/customer-portal?customer_id=cus_9VuW4K7O3GHwasENg31m&send_email=true' \
--header 'User-Agent: insomnia/11.2.0' \
--cookie mode=test

Utilisez ce gestionnaire pour recevoir et traiter en toute sécurité les événements webhook de Dodo Payments dans votre application Express.

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

app.post('/api/webhook',Webhooks({
    webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
    onPayload: async (payload) => {
        // handle the payload
    },
    // ... other event handlers for granular control
}))

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.

Static Checkout (GET)

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.

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/..."
}

Dynamic Checkout (POST)

Envoyez les paramètres dans un corps JSON via une requête POST.
Prend en charge les paiements ponctuels et récurrents.
Pour la liste complète des champs pris en charge dans le corps POST, reportez-vous à :
- Request body for a One Time Payment Product
- Request body for a Subscription Product

Format de Réponse

Le paiement dynamique renvoie une réponse JSON avec l’URL de paiement :

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

Checkout Sessions (POST)

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.).

Checkout Handler

Customer Portal

Webhooks

​Installation

​Exemples de Gestionnaires de Routes

​Gestionnaire de Route de Paiement

​Paramètres de requête

​Format de Réponse

​Format de Réponse

​Format de Réponse

​Gestionnaire de Route du Portail Client

​Paramètres de requête

​Gestionnaire de Route de Webhook

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

​Invite pour LLM

Installation

Exemples de Gestionnaires de Routes

Gestionnaire de Route de Paiement

Paramètres de requête

Format de Réponse

Format de Réponse

Format de Réponse

Gestionnaire de Route du Portail Client

Paramètres de requête

Gestionnaire de Route de Webhook

Gestionnaires d’événements webhook pris en charge

Invite pour LLM