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

# 框架适配器概述

> 将 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。

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

如果希望 coding agent 为你添加 adaptor，请安装 [Agent Plugin](/developer-resources/build-with-ai-coding-agents)。

## 可用的 Framework Adaptors

选择与你的 framework 匹配的 adaptor：

> **[Next.js](/developer-resources/nextjs-adaptor)**
>
> 用于 App Router 中 checkout、customer portal 和 webhooks 的 route handlers。

> **[Nuxt](/developer-resources/nuxt-adaptor)**
>
> 用于 Nuxt 3（一种全栈 Vue framework）的 server route handlers。

> **[Express](/developer-resources/express-adaptor)**
>
> 用于 Node.js 应用中 Express 5 routes 的 request handlers。

> **[Fastify](/developer-resources/fastify-adaptor)**
>
> 用于 Fastify 5（一种采用 plugin architecture 的 Node.js framework）的 route handlers。

> **[Hono](/developer-resources/hono-adaptor)**
>
> 用于 Hono 4 的 route handlers。Hono 是面向 Cloudflare Workers、其他 edge runtimes 和 Node.js 的 web framework。

> **[Astro](/developer-resources/astro-adaptor)**
>
> 用于 Astro 4 和 5（一种专注于 content 的 web framework）的 server endpoint handlers。

> **[SvelteKit](/developer-resources/sveltekit-adaptor)**
>
> 用于 SvelteKit 2（一种全栈 Svelte framework）的 server route handlers。

> **[Remix](/developer-resources/remix-adaptor)**
>
> 用于 Remix 2（一种全栈 React framework）的 loader 和 action handlers。

> **[TanStack Start](/developer-resources/tanstack-adaptor)**
>
> 用于 TanStack Start（一种 type-safe 全栈 React framework）的 server route handlers。

> **[Better Auth](/developer-resources/better-auth-adaptor)**
>
> Better Auth authentication framework 的 plugin，可添加 checkout、portal、usage 和 webhook endpoints，并可在注册时创建 customer。

> **[Convex](/developer-resources/convex-component)**
>
> 用于 Convex backend 的 component，提供 checkout 和 customer portal actions 以及 webhook HTTP action。

> **[Bun](/developer-resources/bun-adaptor)**
>
> 用于 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**

```bash theme={null}
npm install @dodopayments/nextjs
```

**Nuxt**

```bash theme={null}
npm install @dodopayments/nuxt
```

**Express**

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

**Hono**

```bash theme={null}
npm install @dodopayments/hono
```

**Astro**

```bash theme={null}
npm install @dodopayments/astro
```

**SvelteKit**

```bash theme={null}
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`。

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

> [!WARNING]
>
> 切勿将 `.env` 文件或 secrets 提交到 version control。

**3. Create Route Handlers**

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

**Next.js**

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

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

```typescript expandable theme={null}
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",
}));
```

> [!TIP]
>
> 你的 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 传入：
>
> ```text theme={null}
> /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` 为必填项：
>
> ```json theme={null}
> {
>   "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"
>   }
> }
> ```
>
> 它同时支持一次性付款和订阅。根据 product type，它会调用已弃用的 `POST /payments` 或 `POST /subscriptions` endpoint，因此新集成应使用 checkout sessions。

> **Checkout Sessions (POST)**
>
> Checkout sessions 是推荐的流程。它们提供最多的 options，并接受包含多个 products 的 cart：
>
> ```json theme={null}
> {
>   "product_cart": [
>     { "product_id": "pdt_xxx", "quantity": 1 },
>     { "product_id": "pdt_yyy", "quantity": 2 }
>   ],
>   "customer": {
>     "email": "customer@example.com"
>   }
> }
> ```
>
> 有关所有受支持的 fields，请参阅 [Checkout Sessions Guide](/developer-resources/checkout-session)。

## Webhook Event Handling

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

```typescript expandable theme={null}
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` 中接受它们。

> [!NOTE]
>
> 每个 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**：在[社区服务器](https://discord.gg/bYqAp4ayYh)中提问。
* **Email**：联系 [support@dodopayments.com](mailto:support@dodopayments.com)。
* **GitHub**：在[dodo-adapters 仓库](https://github.com/dodopayments/dodo-adapters)中提交 issue，该仓库包含所有适配器。
* **Documentation**：请参阅 [API 参考](/api-reference/introduction)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.