框架适配器概述

将 Dodo Payments checkout、Customer Portal 和 webhook handlers 添加到 Next.js、Nuxt、Express、Hono、SvelteKit、Convex、Better Auth 及其他框架中。

Framework adaptors 使用框架的 request 和 response 类型，为你的应用添加 Dodo Payments checkout、Customer Portal 和 webhook handlers。每个 adaptor 都是 @dodopayments scope 中的 npm package。这些 packages 使用 @dodopayments/core 进行 checkout validation、Dodo Payments API requests、webhook payload validation 和 typed event callbacks。

每个 adaptor 都会在其 handler configuration 中接收你的 API key 和 environment。请将这些值保存在 environment variables 中，并在创建 handler 时传入。

如果希望 coding agent 为你添加 adaptor，请安装 Agent Plugin。

​

可用的 Framework Adaptors

选择与你的 framework 匹配的 adaptor：

Next.js

用于 App Router 中 checkout、customer portal 和 webhooks 的 route handlers。

Nuxt

用于 Nuxt 3（一种全栈 Vue framework）的 server route handlers。

Express

用于 Node.js 应用中 Express 5 routes 的 request handlers。

Fastify

用于 Fastify 5（一种采用 plugin architecture 的 Node.js framework）的 route handlers。

Hono

用于 Hono 4 的 route handlers。Hono 是面向 Cloudflare Workers、其他 edge runtimes 和 Node.js 的 web framework。

Astro

用于 Astro 4 和 5（一种专注于 content 的 web framework）的 server endpoint handlers。

SvelteKit

用于 SvelteKit 2（一种全栈 Svelte framework）的 server route handlers。

Remix

用于 Remix 2（一种全栈 React framework）的 loader 和 action handlers。

TanStack Start

用于 TanStack Start（一种 type-safe 全栈 React framework）的 server route handlers。

Better Auth

Better Auth authentication framework 的 plugin，可添加 checkout、portal、usage 和 webhook endpoints，并可在注册时创建 customer。

Convex

用于 Convex backend 的 component，提供 checkout 和 customer portal actions 以及 webhook HTTP action。

Bun

用于 checkout、customer portal 和 webhooks 的原生 Bun.serve() handlers。

​

核心功能

这些 route handler adaptors 共享以下功能：

功能	描述
Checkout Handler	静态、动态和 checkout session 流程
Customer Portal	用于打开 Customer Portal 的 handler，客户可在其中管理订阅和账单详情
Webhook Handler	针对单个 event types 的 signature verification 和 typed callbacks
Environment Config	通过 typed handler options 传入 API credentials 和 environment
Type Safety	用于 handler options 和 webhook payloads 的 TypeScript types

Better Auth plugin 和 Convex component 通过各自的 APIs 提供相同功能。有关差异，请参阅它们各自的页面。

​

快速开始

分三步设置 route handler adaptor。

1. Install the Adaptor

   安装适用于你的 framework 的 package：

   Next.js

   npm install @dodopayments/nextjs
   

   Nuxt

   npm install @dodopayments/nuxt
   

   Express

   npm install @dodopayments/express
   

   Hono

   npm install @dodopayments/hono
   

   Astro

   npm install @dodopayments/astro
   

   SvelteKit

   npm install @dodopayments/sveltekit
   
2. Configure Environment Variables

   将 Dodo Payments credentials 添加到你的 environment 中。在 dashboard 的 Developer → API Keys 下创建 API key，并在 Developer → Webhooks 下创建 webhook secret。test mode API key 仅适用于 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"
   

   如果不传入 environment，adaptor 将使用 live_mode。

   切勿将 .env 文件或 secrets 提交到 version control。

3. Create Route Handlers

   创建 checkout route。customer portal 和 webhook routes 遵循相同模式：

   Next.js

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

   Express

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

   Hono

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

   你的 checkout route 现在会返回 checkout URL。每个 adaptor 的页面都会介绍 customer portal 和 webhook handlers，并列出所有 options。

​

Checkout Flow Types

Route handler adaptors 支持三种 checkout flow types。Better Auth plugin 支持 checkout sessions 和已弃用的 dynamic checkout。Convex component 仅支持 checkout sessions。

Static Checkout (GET)

Static checkout 为单个 product 返回 payment link，因此你可以分享该链接或将用户重定向到该链接。将 product ID 作为 query parameter 传入：

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

handler 会检查 product 是否存在，并将链接作为 checkout_url 返回。可选 query parameters 可预填 customer details 并控制 checkout form。

Dynamic Checkout (POST)

Dynamic checkout 根据包含自定义 details 的 JSON body 创建 payment link。billing 和 customer 为必填项：

{
  "product_id": "pdt_xxx",
  "quantity": 1,
  "billing": {
    "city": "San Francisco",
    "country": "US",
    "state": "CA",
    "street": "123 Main St",
    "zipcode": "94102"
  },
  "customer": {
    "email": "[e-mail]",
    "name": "John Doe"
  }
}

它同时支持一次性付款和订阅。根据 product type，它会调用已弃用的 POST /payments 或 POST /subscriptions endpoint，因此新集成应使用 checkout sessions。

Checkout Sessions (POST)

Checkout sessions 是推荐的流程。它们提供最多的 options，并接受包含多个 products 的 cart：

{
  "product_cart": [
    { "product_id": "pdt_xxx", "quantity": 1 },
    { "product_id": "pdt_yyy", "quantity": 2 }
  ],
  "customer": {
    "email": "[e-mail]"
  }
}

有关所有受支持的 fields，请参阅 Checkout Sessions Guide。

​

Webhook Event Handling

每个 route handler adaptor 都会导出一个 Webhooks handler。它接收你的 webhook secret，以及针对单个 event types 的可选 typed callbacks。onPayload 会针对每个 event 运行：

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

这些 callbacks 覆盖 payment、refund、dispute、subscription、license key、abandoned checkout、dunning、credit、entitlement grant 和 payout events。Better Auth plugin 在 webhooks() 中接受相同的 callbacks，Convex component 则在 createDodoWebhookHandler 中接受它们。

每个 webhook handler 都会使用 Standard Webhooks library 验证 webhook-id、webhook-signature 和 webhook-timestamp headers，然后使用 Zod schemas 验证 payload。无效 requests 会在 callbacks 运行前以 error status 被拒绝。

​

选择合适的 Adaptor

Framework	最适合的场景	Runtime
Next.js	使用 App Router 的全栈 React apps	Node.js、Edge
Nuxt	全栈 Vue.js applications	Node.js
Express	REST APIs 和传统 Node.js apps	Node.js
Fastify	高性能 APIs	Node.js
Hono	Edge deployments、Cloudflare Workers	Edge、Node.js
Astro	带 server endpoints 的 content sites	Node.js、Edge
SvelteKit	全栈 Svelte applications	Node.js
Remix	使用 nested routing 的全栈 React	Node.js
TanStack Start	Type-safe 全栈 React	Node.js
Better Auth	已使用 Better Auth 的 apps	Various
Convex	使用 Convex 作为 backend 的 apps	Convex Runtime
Bun	原生 Bun server applications	Bun

​

获取帮助

如果需要框架适配器方面的帮助：

• Discord：在社区服务器中提问。
• Email：联系 [e-mail]。
• GitHub：在dodo-adapters 仓库中提交 issue，该仓库包含所有适配器。
• Documentation：请参阅 API 参考。