Aperçu des Adaptateurs de Framework

Les adaptateurs de framework ajoutent le checkout Dodo Payments, le Customer Portal et des gestionnaires de webhook à votre application en utilisant les types de requête et de réponse de votre framework. Chaque adaptateur est un package npm dans le scope @dodopayments. Les packages utilisent @dodopayments/core pour la validation du checkout, les requêtes vers l’API Dodo Payments, la validation des payloads de webhook et les callbacks typés pour les événements.

Chaque adaptateur accepte votre clé API et votre environnement dans sa configuration de handler. Conservez ces valeurs dans des variables d’environnement et transmettez-les lors de la création du handler.

Pour qu’un agent de programmation ajoute un adaptateur pour vous, installez le Agent Plugin.

Adaptateurs de framework disponibles

Choisissez l’adaptateur correspondant à votre framework :

Next.js

Route handlers pour le checkout, le Customer Portal et les webhooks dans l’App Router.

Nuxt

Server route handlers pour Nuxt 3, un framework Vue full-stack.

Express

Request handlers pour les routes Express 5 dans les applications Node.js.

Fastify

Route handlers pour Fastify 5, un framework Node.js doté d’une architecture de plugins.

Hono

Route handlers pour Hono 4, un framework web pour Cloudflare Workers, d’autres edge runtimes et Node.js.

Astro

Server endpoint handlers pour Astro 4 et 5, un framework web axé sur le contenu.

SvelteKit

Server route handlers pour SvelteKit 2, un framework Svelte full-stack.

Remix

Loader et action handlers pour Remix 2, un framework React full-stack.

TanStack Start

Server route handlers pour TanStack Start, un framework React full-stack type-safe.

Better Auth

Un plugin pour le framework d’authentification Better Auth qui ajoute des endpoints de checkout, de portail, d’utilisation et de webhook, et peut créer un client lors de l’inscription.

Convex

Un composant pour le backend Convex avec des actions de checkout et de Customer Portal, ainsi qu’une HTTP action de webhook.

Bun

Des handlers Bun.serve() natifs pour le checkout, le Customer Portal et les webhooks.

Fonctionnalités principales

Les adaptateurs de route handlers partagent les fonctionnalités suivantes :

Fonctionnalité	Description
Checkout Handler	Flux de checkout statique, dynamique et de checkout session
Customer Portal	Un handler qui ouvre le Customer Portal, où les clients gèrent leurs abonnements et leurs informations de facturation
Webhook Handler	Vérification de signature et callbacks typés pour chaque type d’événement
Configuration de l’environnement	Identifiants API et environnement transmis via des options de handler typées
Type Safety	Types TypeScript pour les options de handler et les payloads de webhook

Le plugin Better Auth et le composant Convex offrent les mêmes fonctionnalités via leurs propres API. Consultez leurs pages pour connaître les différences.

Démarrage rapide

Configurez un adaptateur de route handler en trois étapes.

Install the Adaptor

Installez le package correspondant à votre framework :

npm install @dodopayments/nextjs

npm install @dodopayments/nuxt

npm install @dodopayments/express

npm install @dodopayments/hono

npm install @dodopayments/astro

npm install @dodopayments/sveltekit

Configure Environment Variables

Ajoutez vos identifiants Dodo Payments à votre environnement. Créez la clé API sous Developer → API Keys et le secret de webhook sous Developer → Webhooks dans le dashboard. Une clé API de mode test fonctionne uniquement avec test_mode.

DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_RETURN_URL=https://yourdomain.com/checkout/success
DODO_PAYMENTS_ENVIRONMENT="test_mode" # or "live_mode"

Si vous ne transmettez pas d’environnement, l’adaptateur utilise live_mode.

Ne validez jamais votre fichier .env ni vos secrets dans le contrôle de version.

Create Route Handlers

Créez une route de checkout. Les routes du Customer Portal et des webhooks suivent le même modèle :

Next.js
Express
Hono

// app/checkout/route.ts
import { Checkout } from "@dodopayments/nextjs";

export const GET = Checkout({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT as "test_mode" | "live_mode",
});

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

const app = 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 as "test_mode" | "live_mode",
}));

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

const app = new Hono();

app.get('/checkout', Checkout({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT as "test_mode" | "live_mode",
}));

Votre route de checkout renvoie désormais une URL de checkout. La page de chaque adaptateur couvre le Customer Portal et les handlers de webhook, et répertorie toutes les options.

Types de flux de checkout

Les adaptateurs de route handlers prennent en charge trois types de flux de checkout. Le plugin Better Auth prend en charge les checkout sessions et un checkout dynamique obsolète. Le composant Convex prend uniquement en charge les checkout sessions.

Static Checkout (GET)

Le checkout statique renvoie un payment link pour un produit, que vous pouvez partager ou vers lequel rediriger l’utilisateur. Transmettez l’ID du produit comme query parameter :

/api/checkout?productId=pdt_xxx&quantity=1

Le handler vérifie que le produit existe et renvoie le lien sous la forme checkout_url. Les query parameters facultatifs préremplissent les informations du client et contrôlent le formulaire de checkout.

Dynamic Checkout (POST)

Le checkout dynamique crée un payment link à partir d’un body JSON contenant des informations personnalisées. billing et customer sont obligatoires :

{
  "product_id": "pdt_xxx",
  "quantity": 1,
  "billing": {
    "city": "San Francisco",
    "country": "US",
    "state": "CA",
    "street": "123 Main St",
    "zipcode": "94102"
  },
  "customer": {
    "email": "customer@example.com",
    "name": "John Doe"
  }
}

Il prend en charge les paiements ponctuels et les abonnements. Il appelle l’endpoint obsolète POST /payments ou POST /subscriptions, selon le type de produit ; utilisez donc les checkout sessions pour les nouvelles intégrations.

Checkout Sessions (POST)

Les checkout sessions constituent le flux recommandé. Elles offrent le plus grand nombre d’options et acceptent un panier contenant plusieurs produits :

{
  "product_cart": [
    { "product_id": "pdt_xxx", "quantity": 1 },
    { "product_id": "pdt_yyy", "quantity": 2 }
  ],
  "customer": {
    "email": "customer@example.com"
  }
}

Pour connaître tous les champs pris en charge, consultez le Checkout Sessions Guide.

Gestion des événements de webhook

Chaque adaptateur de route handler exporte un handler Webhooks. Il accepte votre secret de webhook ainsi que des callbacks typés facultatifs pour chaque type d’événement. onPayload s’exécute pour chaque événement :

Webhooks({
  webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY!,
  onPayload: async (payload) => {
    // Handle any webhook event
  },
  onPaymentSucceeded: async (payload) => {
    // Handle successful payments
  },
  onSubscriptionActive: async (payload) => {
    // Handle new subscriptions
  },
  // ...more than 40 optional event callbacks in total
});

Les callbacks couvrent les événements de paiement, de remboursement, de litige, d’abonnement, de clé de licence, de checkout abandonné, de relance, de crédit, d’octroi de droits et de versement. Le plugin Better Auth accepte les mêmes callbacks dans webhooks(), et le composant Convex les accepte dans createDodoWebhookHandler.

Chaque webhook handler vérifie les headers webhook-id, webhook-signature et webhook-timestamp avec la bibliothèque Standard Webhooks, puis valide le payload avec des schémas Zod. Les requêtes invalides sont rejetées avec un error status avant l’exécution de vos callbacks.

Choisir le bon adaptateur

Framework	Idéal pour	Runtime
Next.js	Applications React full-stack avec App Router	Node.js, Edge
Nuxt	Applications Vue.js full-stack	Node.js
Express	REST APIs et applications Node.js traditionnelles	Node.js
Fastify	APIs haute performance	Node.js
Hono	Déploiements edge, Cloudflare Workers	Edge, Node.js
Astro	Sites de contenu avec server endpoints	Node.js, Edge
SvelteKit	Applications Svelte full-stack	Node.js
Remix	React full-stack avec routage imbriqué	Node.js
TanStack Start	React full-stack type-safe	Node.js
Better Auth	Applications utilisant déjà Better Auth	Divers
Convex	Applications utilisant Convex pour le backend	Convex Runtime
Bun	Applications serveur Bun natives	Bun

Obtenir de l’aide

Pour obtenir de l’aide avec un adaptateur de framework :

Discord : Posez votre question sur le serveur communautaire.
E-mail : Contactez support@dodopayments.com.
GitHub : Ouvrez une issue dans le dépôt dodo-adapters, qui contient tous les adaptateurs.
Documentation : Consultez la référence de l’API.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Adaptateurs de framework disponibles

Next.js

Nuxt

Express

Fastify

Hono

Astro

SvelteKit

Remix

TanStack Start

Better Auth

Convex

Bun

Fonctionnalités principales

Démarrage rapide

Types de flux de checkout

Gestion des événements de webhook

Choisir le bon adaptateur

Obtenir de l’aide

​Adaptateurs de framework disponibles

Next.js

Nuxt

Express

Fastify

Hono

Astro

SvelteKit

Remix

TanStack Start

Better Auth

Convex

Bun

​Fonctionnalités principales

​Démarrage rapide

​Types de flux de checkout

​Gestion des événements de webhook

​Choisir le bon adaptateur

​Obtenir de l’aide

Adaptateurs de framework disponibles

Fonctionnalités principales

Démarrage rapide

Types de flux de checkout

Gestion des événements de webhook

Choisir le bon adaptateur

Obtenir de l’aide