Panoramica degli Adattatori del Framework

Gli adattatori per framework aggiungono il checkout di Dodo Payments, il Customer Portal e i gestori dei webhook alla tua app utilizzando i tipi di richiesta e risposta del tuo framework. Ogni adattatore è un pacchetto npm nello scope @dodopayments. I pacchetti utilizzano @dodopayments/core per la convalida del checkout, le richieste all’API di Dodo Payments, la convalida del payload dei webhook e i callback tipizzati degli eventi.

Ogni adattatore accetta la tua chiave API e l’ambiente nella configurazione del gestore. Conserva questi valori nelle variabili d’ambiente e passali quando crei il gestore.

Per fare in modo che un agente di coding aggiunga un adattatore per te, installa il Plugin dell’agente.

Adattatori per framework disponibili

Scegli l’adattatore corrispondente al tuo framework:

Next.js

Gestori delle route per checkout, Customer Portal e webhook nell’App Router.

Nuxt

Gestori delle route server per Nuxt 3, un framework Vue full-stack.

Express

Gestori delle richieste per le route Express 5 nelle app Node.js.

Fastify

Gestori delle route per Fastify 5, un framework Node.js con un’architettura a plugin.

Hono

Gestori delle route per Hono 4, un framework web per Cloudflare Workers, altri runtime edge e Node.js.

Astro

Gestori degli endpoint server per Astro 4 e 5, un framework web incentrato sui contenuti.

SvelteKit

Gestori delle route server per SvelteKit 2, un framework Svelte full-stack.

Remix

Gestori di loader e action per Remix 2, un framework React full-stack.

TanStack Start

Gestori delle route server per TanStack Start, un framework React full-stack type-safe.

Better Auth

Un plugin per il framework di autenticazione Better Auth che aggiunge endpoint per checkout, portale, utilizzo e webhook e può creare un cliente al momento della registrazione.

Convex

Un componente per il backend Convex con action per checkout e Customer Portal e una HTTP action per i webhook.

Bun

Gestori Bun.serve() nativi per checkout, Customer Portal e webhook.

Funzionalità principali

Gli adattatori dei gestori delle route condividono queste funzionalità:

Funzionalità	Descrizione
Gestore del checkout	Flussi di checkout statici, dinamici e con sessione di checkout
Customer Portal	Un gestore che apre il Customer Portal, dove i clienti gestiscono abbonamenti e dati di fatturazione
Gestore dei webhook	Verifica della firma e callback tipizzati per i singoli tipi di evento
Configurazione dell’ambiente	Credenziali API e ambiente passati tramite opzioni tipizzate del gestore
Sicurezza dei tipi	Tipi TypeScript per le opzioni del gestore e i payload dei webhook

Il plugin Better Auth e il componente Convex offrono le stesse funzionalità tramite le rispettive API. Consulta le relative pagine per conoscere le differenze.

Avvio rapido

Configura un adattatore per il gestore delle route in tre passaggi.

Install the Adaptor

Installa il pacchetto per il tuo 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

Aggiungi le credenziali Dodo Payments al tuo ambiente. Crea la chiave API in Developer → API Keys e il segreto del webhook in Developer → Webhooks nella dashboard. Una chiave API in modalità di test funziona solo con 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"

Se non passi un ambiente, l’adattatore utilizza live_mode.

Non eseguire mai il commit del file .env o dei segreti nel controllo versione.

Create Route Handlers

Crea una route per il checkout. Le route per Customer Portal e webhook seguono lo stesso schema:

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",
}));

La tua route di checkout ora restituisce un URL di checkout. La pagina di ogni adattatore illustra i gestori per Customer Portal e webhook ed elenca tutte le opzioni.

Tipi di flusso del checkout

Gli adattatori dei gestori delle route supportano tre tipi di flusso del checkout. Il plugin Better Auth supporta le sessioni di checkout e un checkout dinamico deprecato. Il componente Convex supporta solo le sessioni di checkout.

Static Checkout (GET)

Il checkout statico restituisce un link di pagamento per un prodotto, così puoi condividerlo o reindirizzarlo. Passa l’ID del prodotto come parametro di query:

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

Il gestore verifica che il prodotto esista e restituisce il link come checkout_url. I parametri di query facoltativi precompilano i dati del cliente e controllano il modulo di checkout.

Dynamic Checkout (POST)

Il checkout dinamico crea un link di pagamento da un body JSON con dettagli personalizzati. billing e customer sono obbligatori:

{
  "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"
  }
}

Supporta sia i pagamenti una tantum sia gli abbonamenti. Chiama l’endpoint POST /payments o POST /subscriptions deprecato, a seconda del tipo di prodotto; per le nuove integrazioni, quindi, utilizza le sessioni di checkout.

Checkout Sessions (POST)

Le sessioni di checkout sono il flusso consigliato. Offrono il maggior numero di opzioni e accettano un carrello con diversi prodotti:

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

Per tutti i campi supportati, consulta la Guida alle sessioni di checkout.

Gestione degli eventi webhook

Ogni adattatore dei gestori delle route esporta un gestore Webhooks. Accetta il segreto del webhook e callback tipizzati facoltativi per i singoli tipi di evento. onPayload viene eseguito per ogni evento:

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
});

I callback coprono eventi relativi a pagamenti, rimborsi, contestazioni, abbonamenti, chiavi di licenza, checkout abbandonati, solleciti di pagamento, crediti, concessioni di entitlements ed erogazioni. Il plugin Better Auth accetta gli stessi callback in webhooks() e il componente Convex li accetta in createDodoWebhookHandler.

Ogni gestore dei webhook verifica gli header webhook-id, webhook-signature e webhook-timestamp con la libreria Standard Webhooks, quindi convalida il payload con gli schema Zod. Le richieste non valide vengono rifiutate con uno status di errore prima dell’esecuzione dei callback.

Scegliere l’adattatore giusto

Framework	Ideale per	Runtime
Next.js	App React full-stack con App Router	Node.js, Edge
Nuxt	Applicazioni Vue.js full-stack	Node.js
Express	API REST e app Node.js tradizionali	Node.js
Fastify	API ad alte prestazioni	Node.js
Hono	Deployment edge, Cloudflare Workers	Edge, Node.js
Astro	Siti incentrati sui contenuti con endpoint server	Node.js, Edge
SvelteKit	Applicazioni Svelte full-stack	Node.js
Remix	React full-stack con routing annidato	Node.js
TanStack Start	React full-stack type-safe	Node.js
Better Auth	App che utilizzano già Better Auth	Vari
Convex	App che utilizzano Convex per il backend	Convex Runtime
Bun	Applicazioni server Bun native	Bun

Ottenere assistenza

Per ricevere assistenza con un adattatore del framework:

Discord: Fai una domanda nel server della community.
Email: Contatta support@dodopayments.com.
GitHub: Apri una issue nel repository dodo-adapters, che contiene tutti gli adattatori.
Documentazione: Consulta il riferimento API.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Adattatori per framework disponibili

Next.js

Nuxt

Express

Fastify

Hono

Astro

SvelteKit

Remix

TanStack Start

Better Auth

Convex

Bun

Funzionalità principali

Avvio rapido

Tipi di flusso del checkout

Gestione degli eventi webhook

Scegliere l’adattatore giusto

Ottenere assistenza

​Adattatori per framework disponibili

Next.js

Nuxt

Express

Fastify

Hono

Astro

SvelteKit

Remix

TanStack Start

Better Auth

Convex

Bun

​Funzionalità principali

​Avvio rapido

​Tipi di flusso del checkout

​Gestione degli eventi webhook

​Scegliere l’adattatore giusto

​Ottenere assistenza

Adattatori per framework disponibili

Funzionalità principali

Avvio rapido

Tipi di flusso del checkout

Gestione degli eventi webhook

Scegliere l’adattatore giusto

Ottenere assistenza