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

# Adaptateur Express

> Apprenez à intégrer Dodo Payments avec votre projet Express App Router en utilisant notre Adaptateur Express. Couvre le processus de paiement, le portail client, les webhooks et la configuration d'environnement sécurisé.

<CardGroup cols={2}>
  <Card title="Checkout Handler" icon="cart-shopping" href="#checkout-route-handler">
    Intégrez le paiement Dodo Payments dans votre application Express.
  </Card>

  <Card title="Customer Portal" icon="user" href="#customer-portal-route-handler">
    Permettez aux clients de gérer leurs abonnements et leurs informations.
  </Card>

  <Card title="Webhooks" icon="bell" href="#webhook-route-handler">
    Recevez et traitez les événements webhook de Dodo Payments.
  </Card>
</CardGroup>

## Installation

<Steps>
  <Step title="Install the package">
    Exécutez la commande suivante à la racine de votre projet :

    ```bash theme={null}
    npm install @dodopayments/express
    ```
  </Step>

  <Step title="Set up environment variables">
    Créez un <code>.env</code> à la racine de votre projet :

    ```env expandable theme={null}
    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
    ```

    <Warning>
      Ne validez jamais votre <code>.env</code> ni vos secrets dans un système de contrôle de version.
    </Warning>
  </Step>
</Steps>

## Exemples de Gestionnaires de Routes

<Tabs>
  <Tab title="Checkout Handler">
    <Info>
      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).
    </Info>

    <CodeGroup>
      ```typescript Express Route Handler expandable theme={null}
      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"
      }))
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Static Checkout Curl example expandable theme={null}
      curl --request GET \
      --url 'https://example.com/api/checkout?productId=pdt_fqJhl7pxKWiLhwQR042rh' \
      --header 'User-Agent: insomnia/11.2.0' \
      --cookie mode=test
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Dynamic Checkout Curl example expandable theme={null}
      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
      }'
      ```
    </CodeGroup>

    <CodeGroup>
      ```curl Checkout Session Curl example expandable theme={null}
      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"
      }'
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Customer Portal Handler">
    <Info>
      Utilisez ce gestionnaire pour permettre aux clients de gérer leurs abonnements et leurs informations via le portail client Dodo Payments.
    </Info>

    <CodeGroup>
      ```typescript Express Route Handler expandable theme={null}
      import { CustomerPortal } from "@dodopayments/express";

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

    <CodeGroup>
      ```curl Customer Portal Curl example expandable theme={null}
      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
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Webhook Handler">
    <Info>
      Utilisez ce gestionnaire pour recevoir et traiter en toute sécurité les événements webhook de Dodo Payments dans votre application Express.
    </Info>

    <CodeGroup>
      ```typescript Express Route Handler expandable theme={null}
      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
      }))
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Gestionnaire de Route de Paiement

<Info>
  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.
</Info>

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

<AccordionGroup>
  <Accordion title="Static Checkout (GET)">
    ### Paramètres de requête

    <ParamField query="productId" type="string" required>
      Identifiant du produit (par exemple, <code>?productId=pdt\_nZuwz45WAs64n3l07zpQR</code>).
    </ParamField>

    <ParamField query="quantity" type="integer">
      Quantité du produit.
    </ParamField>

    <ParamField query="fullName" type="string">
      Nom complet du client.
    </ParamField>

    <ParamField query="firstName" type="string">
      Prénom du client.
    </ParamField>

    <ParamField query="lastName" type="string">
      Nom de famille du client.
    </ParamField>

    <ParamField query="email" type="string">
      Adresse e-mail du client.
    </ParamField>

    <ParamField query="country" type="string">
      Pays du client.
    </ParamField>

    <ParamField query="addressLine" type="string">
      Adresse du client.
    </ParamField>

    <ParamField query="city" type="string">
      Ville du client.
    </ParamField>

    <ParamField query="state" type="string">
      État/ province du client.
    </ParamField>

    <ParamField query="zipCode" type="string">
      Code postal du client.
    </ParamField>

    <ParamField query="disableFullName" type="boolean">
      Désactiver le champ nom complet.
    </ParamField>

    <ParamField query="disableFirstName" type="boolean">
      Désactiver le champ prénom.
    </ParamField>

    <ParamField query="disableLastName" type="boolean">
      Désactiver le champ nom de famille.
    </ParamField>

    <ParamField query="disableEmail" type="boolean">
      Désactiver le champ e-mail.
    </ParamField>

    <ParamField query="disableCountry" type="boolean">
      Désactiver le champ pays.
    </ParamField>

    <ParamField query="disableAddressLine" type="boolean">
      Désactiver le champ adresse.
    </ParamField>

    <ParamField query="disableCity" type="boolean">
      Désactiver le champ ville.
    </ParamField>

    <ParamField query="disableState" type="boolean">
      Désactiver le champ état.
    </ParamField>

    <ParamField query="disableZipCode" type="boolean">
      Désactiver le champ code postal.
    </ParamField>

    <ParamField query="paymentCurrency" type="string">
      Spécifiez la devise de paiement (par exemple, <code>USD</code>).
    </ParamField>

    <ParamField query="showCurrencySelector" type="boolean">
      Afficher le sélecteur de devise.
    </ParamField>

    <ParamField query="paymentAmount" type="integer">
      Spécifiez le montant du paiement (par exemple, <code>1000</code> pour 10,00 \$).
    </ParamField>

    <ParamField query="showDiscounts" type="boolean">
      Afficher les champs de remise.
    </ParamField>

    <ParamField query="metadata_*" type="string">
      Tout paramètre de requête commençant par <code>metadata\_</code> sera transmis en tant que métadonnée.
    </ParamField>

    <Warning>
      Si <code>productId</code> est manquant, le gestionnaire renvoie une réponse 400. Les paramètres de requête non valides entraînent également une réponse 400.
    </Warning>

    ### Format de Réponse

    Le paiement statique renvoie une réponse JSON avec l'URL de paiement :

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/..."
    }
    ```
  </Accordion>

  <Accordion title="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](https://docs.dodopayments.com/api-reference/payments/post-payments)
      * [Request body for a Subscription Product](https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions)

    ### Format de Réponse

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

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/..."
    }
    ```
  </Accordion>

  <Accordion title="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](https://docs.dodopayments.com/developer-resources/checkout-session) 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 :

    ```json theme={null}
    {
      "checkout_url": "https://checkout.dodopayments.com/session/..."
    }
    ```
  </Accordion>
</AccordionGroup>

## 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

<ParamField query="customer_id" type="string" required>
  L'ID client pour la session du portail (par exemple, <code>?customer\_id=cus\_123</code>).
</ParamField>

<ParamField query="send_email" type="boolean">
  Si défini sur <code>true</code>, envoie un e-mail au client contenant le lien du portail.
</ParamField>

<Warning>
  Renvoie 400 si <code>customer\_id</code> est manquant.
</Warning>

## 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 <code>webhookKey</code>. 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

<CodeGroup>
  ```typescript Typescript expandable theme={null}
  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>;
  ```
</CodeGroup>

***

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