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

# Hono Adaptor

> Apprenez à intégrer Dodo Payments avec votre projet Hono App Router en utilisant notre Adaptor NextJS. 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 Hono.
  </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/hono
    ```
  </Step>

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

    ```env expandable theme={null}
    DODO_PAYMENTS_API_KEY=your-api-key
    DODO_PAYMENTS_RETURN_URL=https://yourapp.com/success
    DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
    DODO_PAYMENTS_ENVIRONMENT="test_mode" or "live_mode""
    ```

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

## Exemples de Gestionnaires de Route

<Info>
  Tous les exemples supposent que vous utilisez le routeur Hono App Router.
</Info>

<Tabs>
  <Tab title="Checkout Handler">
    <Info>
      Utilisez ce gestionnaire pour intégrer le paiement Dodo Payments dans votre application Hono. Il prend en charge les flux statiques (GET), dynamiques (POST) et de session (POST).
    </Info>

    <CodeGroup>
      ```typescript Hono Route Handler expandable theme={null}
        // route.ts
        import { Checkout } from '@dodopayments/hono';
        import Hono from 'hono'

        const app = new Hono()

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

        app.post(
        "/api/checkout",
        Checkout({
            bearerToken: process.env.DODO_PAYMENTS_API_KEY,
            environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
            returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
            type: 'dynamic'
        })
        );
        
        app.post(
        "/api/checkout",
        Checkout({
            bearerToken: process.env.DODO_PAYMENTS_API_KEY,
            environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
            returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
            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 Hono Route Handler expandable theme={null}
      // route.ts
      import { Checkout } from '@dodopayments/hono';
      import Hono from 'hono'

      const app = new Hono()
      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 les événements webhook de Dodo Payments de manière sécurisée dans votre application Hono.
    </Info>

    <CodeGroup>
      ```typescript Hono Route Handler expandable theme={null}
      // route.ts
      import Hono from 'hono'
      import { Webhooks } from '@dodopayments/hono'

      const app = new Hono()
      app.post(
      "/api/webhooks",
          Webhooks({
              webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
              onPayload: async (payload) => {
              // Handle Payload Here
              console.log(payload)
              }
          })
      );

      ```
    </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érez 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 pris en charge

    <ParamField query="productId" type="string" required>
      Identifiant du produit (par ex., <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/zip du client.
    </ParamField>

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

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

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

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

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

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

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

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

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

    <ParamField query="paymentCurrency" type="string">
      Spécifiez la devise de paiement (par ex., <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 ex., <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 comme métadonnée.
    </ParamField>

    <Warning>
      Si <code>productId</code> est manquant, le gestionnaire renvoie une réponse 400. Les paramètres de requête invalides 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 le corps JSON d’une requête POST.
    * Prend en charge les paiements uniques et récurrents.
    * Pour la liste complète des champs pris en charge dans le corps de la requête POST, consultez :
      * [Corps de requête pour un produit à paiement unique](https://docs.dodopayments.com/api-reference/payments/post-payments)
      * [Corps de requête pour un produit d’abonnement](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 uniques 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 de Dodo Payments dans votre application Hono.

### Paramètres de requête

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

<ParamField query="send_email" type="boolean">
  S’il est défini sur <code>true</code>, envoie un e-mail au client avec le lien vers le 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>;
  onLicenseKeyCreated?: (payload: WebhookPayload) => Promise<void>;
  ```
</CodeGroup>

***

## Invite pour LLM

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

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

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/hono

---

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/hono 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 redirige les utilisateurs vers la page de paiement de Dodo Payments.

**Intégration** :
Créez deux routes dans votre application Hono — une pour le paiement statique (GET) et une pour le paiement dynamique (POST).

import { Checkout } from '@dodopayments/hono';
import Hono from 'hono'

const app = new Hono()

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

app.post(
  "/api/checkout",
  Checkout({
    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
    returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
    type: 'session' // ou 'dynamic' pour un lien dynamique
  })
);

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

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

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 { Checkout } from '@dodopayments/hono';
import Hono from 'hono'

const app = new Hono()
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 Hono from 'hono'
import { Webhooks } from '@dodopayments/hono'

const app = new Hono()
app.post(
  "/api/webhooks",
  Webhooks({
    webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
    onPayload: async (payload) => {
      // Traitez la Charge Utile Ici
      console.log(payload)
    }
  })
);

Fonctionnalités :

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

    La vérification de signature est effectuée à l'aide de 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, onSubscriptionPaused, onSubscriptionPlanChanged, onSubscriptionCancelled, onSubscriptionFailed, onSubscriptionExpired

    onLicenseKeyCreated

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_RETURN_URL=https://yourapp.com/success
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_ENVIRONMENT="test_mode" ou "live_mode"

Utilisez-les dans votre code comme :

process.env.DODO_PAYMENTS_API_KEY
process.env.DODO_PAYMENTS_WEBHOOK_KEY

Note de Sécurité : Ne PAS commettre de secrets dans le contrôle de version. Utilisez des fichiers .env localement et des gestionnaires de secrets dans les environnements de déploiement (par exemple, AWS, Vercel, Heroku, etc.).

Utilisez-les dans votre code comme suit :

process.env.DODO_PAYMENTS_API_KEY
process.env.DODO_PAYMENTS_WEBHOOK_KEY

Note de sécurité : NE PAS commettre de secrets dans le contrôle de version. Utilisez des fichiers .env localement et des gestionnaires de secrets dans les environnements de déploiement (par exemple, AWS, Vercel, Heroku, etc.).
```