框架适配器概述 - Dodo Payments Documentation

Dodo Payments 提供官方框架适配器，简化支付集成。每个适配器都旨在与您的框架约定无缝协作，提供结账、客户门户和 webhook 处理功能。

框架适配器让您在不到 10 行代码内集成 Dodo Payments。它们自动处理身份验证、请求解析和响应格式化。

可用框架适配器

选择与您的框架匹配的适配器：

Next.js

App Router 支持，提供结账、门户和 Webhook 的路由处理程序

Nuxt

基于 Vue 的全栈框架，集成服务器路由

Express

基于中间件的处理程序，适用于流行的 Node.js 框架

Fastify

拥有插件架构的高性能 Node.js 框架

Hono

面向边缘、Cloudflare Workers 等的超快速 Web 框架

Astro

以内容为中心的框架，支持服务器端点

SvelteKit

集成服务器钩子的全栈 Svelte 框架

Remix

具有 loader 和 action 处理程序的全栈 React 框架

TanStack Start

具有服务器函数的类型安全全栈 React 框架

Better Auth

用于无缝认证与支付的认证框架插件

Convex

用于实时支付同步的后端即服务组件

Bun

原生 Bun.serve() 处理程序，涵盖结账、门户和 Webhook

核心功能

所有框架适配器都提供以下内置功能：

功能	说明
结账处理程序	支持静态、动态和基于会话的结账流程
客户门户	用于订阅和计费管理的预构建处理程序
Webhook 处理程序	具有类型化事件处理程序的安全签名验证
环境配置	通过环境变量进行简单设置
类型安全	支持完整 TypeScript，并提供类型化有效负载

快速开始

通过三个步骤即可开始使用任意框架适配器：

Install the Adaptor

使用你的包管理器安装针对框架的适配器：

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

将 Dodo Payments 凭据添加到你的环境中：

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"

切勿将 .env 文件或密钥提交到版本控制。

Create Route Handlers

设置结账、客户门户和 Webhook 路由：

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

import { checkoutHandler } from '@dodopayments/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,
}));

import { Checkout } from "@dodopayments/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,
}));

你现在已准备好处理支付！访问各适配器页面获取详细指南和所有可用选项。

结账流程类型

所有适配器均支持三种结账流程类型：

Static Checkout (GET)

使用静态结账处理简单、可共享的支付链接。将产品 ID 作为查询参数传递：

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

支持通过查询参数进行可选的客户预填和定制。

Dynamic Checkout (POST)

使用动态结账可编程创建具有自定义信息的支付：

{
  "product_id": "pdt_xxx",
  "customer": {
    "email": "customer@example.com",
    "name": "John Doe"
  },
  "quantity": 1
}

支持一次性支付和订阅。

Checkout Sessions (POST)

使用结账会话，获得具备购物车支持的最灵活结账体验：

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

在结账会话指南中了解更多。

Webhook 事件处理

所有适配器均提供具有细粒度事件回调的类型安全 Webhook 处理：

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
  },
  // ... 20+ event types supported
});

所有 Webhook 处理程序自动验证签名并使用 Zod 模式校验有效载荷。无效请求将以适当的错误码拒绝。

选择合适的适配器

框架	适合	运行时
Next.js	App Router 的全栈 React 应用	Node.js，Edge
Nuxt	全栈 Vue.js 应用	Node.js
Express	REST API 和传统 Node.js 应用	Node.js
Fastify	高性能 API	Node.js
Hono	边缘部署、Cloudflare Workers	Edge，Node.js
Astro	带服务器端点的内容站点	Node.js，Edge
SvelteKit	全栈 Svelte 应用	Node.js
Remix	具有嵌套路由的全栈 React	Node.js
TanStack Start	类型安全的全栈 React	Node.js
Better Auth	已在使用 Better Auth 的应用	多种
Convex	使用 Convex 作为后端的应用	Convex 运行时
Bun	原生 Bun 服务器应用	Bun

获取帮助

需要框架适配器方面的帮助？

Discord：加入我们的社区服务器以获得实时帮助
Email：通过 support@dodopayments.com 联系我们
GitHub：在相应的适配器仓库中提交 issue
Documentation：访问我们的API 参考
Discord: 加入我们的社区服务器获取实时帮助
Email: 联系我们 support@dodopayments.com
GitHub: 在相应的适配器库中打开问题
Documentation: 访问我们的 API 参考
Discord: Join our community server for real-time help
Email: Contact us at support@dodopayments.com
GitHub: Open an issue on the respective adaptor repository
Documentation: Visit our API reference

​可用框架适配器

Next.js

Nuxt

Express

Fastify

Hono

Astro

SvelteKit

Remix

TanStack Start

Better Auth

Convex

Bun

​核心功能

​快速开始

​结账流程类型

​Webhook 事件处理

​选择合适的适配器

​获取帮助

可用框架适配器

核心功能

快速开始

结账流程类型

Webhook 事件处理

选择合适的适配器

获取帮助