framework-adapters
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseFramework Adapters
框架适配器
Use this skill when you need to integrate Dodo Payments into a web framework using the official adapter packages. Framework adapters handle route plumbing, environment configuration, and handler setup so you don't build checkout, portal, and webhook routes from scratch.
当你需要使用官方适配器包将Dodo Payments集成到Web框架中时,可使用此技能。框架适配器会处理路由搭建、环境配置和处理器设置,让你无需从零构建checkout、门户和webhook路由。
When to use this skill
何时使用此技能
- You're building a checkout flow in Next.js, Express, Fastify, Hono, Astro, Remix, SvelteKit, Nuxt, TanStack, Bun, or Convex.
- You need to set up a customer portal session endpoint.
- You're adding webhook handlers that verify signatures and dispatch events.
- You want framework-idiomatic route placement and environment variable handling.
- You need to choose between static, dynamic, or session checkout modes.
- 你正在使用Next.js、Express、Fastify、Hono、Astro、Remix、SvelteKit、Nuxt、TanStack、Bun或Convex构建checkout流程。
- 你需要搭建客户门户会话端点。
- 你要添加用于验证签名和派发事件的webhook处理器。
- 你希望采用符合框架惯例的路由放置方式和环境变量处理方案。
- 你需要在静态、动态或会话式checkout模式之间做选择。
What framework adapters do
框架适配器的作用
Dodo publishes packages that wrap the core SDK with framework-specific route handlers. Instead of writing your own HTTP handlers, you import the adapter's handlers and mount them directly in your routes.
@dodopayments/*Each adapter exposes three handler families:
- Checkout: static (GET only), dynamic (POST with cart), or session (POST with pre-built session).
- CustomerPortal: generates a time-bound portal session link.
- Webhooks: verifies webhook signatures and dispatches typed events.
Export names are not uniform across adapters. Most export / / , but two differ, and the return shapes differ as well. Check this table before writing imports:
CheckoutCustomerPortalWebhooks| Adapter | Checkout export | Portal export | Handler shape |
|---|---|---|---|
| | | returns a request handler |
| | | returns |
| | | returns |
| | | returns |
| | | no import statement |
| | — | |
The adapters handle raw body preservation for webhook verification, environment variable mapping, and framework-specific request/response shapes. Checkout payload design belongs to the skill; webhook business logic belongs to ; portal behavior belongs to .
checkout-integrationwebhook-integrationcustomer-managementDodo发布了系列包,通过框架特定的路由处理器封装了核心SDK。你无需自行编写HTTP处理器,只需导入适配器的处理器并直接挂载到路由中即可。
@dodopayments/*每个适配器都提供三类处理器:
- Checkout: 静态(仅GET)、动态(带购物车的POST)或会话(带预构建会话的POST)。
- CustomerPortal: 生成有时效的门户会话链接。
- Webhooks: 验证webhook签名并派发带类型的事件。
不同适配器的导出名称并不统一。 大多数导出 / / ,但有两个例外,且返回结构也有所不同。编写导入语句前请参考下表:
CheckoutCustomerPortalWebhooks| 适配器 | Checkout导出 | Portal导出 | 处理器结构 |
|---|---|---|---|
| | | 返回一个请求处理器 |
| | | 返回 |
| | | 返回 |
| | | 返回 |
| | | 无需导入语句 |
| | — | |
这些适配器会处理webhook验证所需的原始请求体保留、环境变量映射,以及框架特定的请求/响应结构。Checkout的payload设计属于技能的范畴;webhook业务逻辑属于技能;门户相关功能属于技能。
checkout-integrationwebhook-integrationcustomer-managementFramework selection and installation
框架选择与安装
| Framework | Package | Install |
|---|---|---|
| Next.js | | |
| Express | | |
| Fastify | | |
| Hono | | |
| Astro | | |
| Remix | | |
| SvelteKit | | |
| Nuxt | | |
| TanStack Start | | |
| Bun | | |
| Convex | | |
| 框架 | 包名 | 安装命令 |
|---|---|---|
| Next.js | | |
| Express | | |
| Fastify | | |
| Hono | | |
| Astro | | |
| Remix | | |
| SvelteKit | | |
| Nuxt | | |
| TanStack Start | | |
| Bun | | |
| Convex | | |
Environment variables
环境变量
Most adapters use these standard names:
env
DODO_PAYMENTS_API_KEY=dodo_test_...
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_ENVIRONMENT=test_mode
DODO_PAYMENTS_RETURN_URL=https://yourdomain.com/checkout/successNuxt uses private runtime config prefixes:
env
NUXT_PRIVATE_BEARER_TOKEN=dodo_test_...
NUXT_PRIVATE_WEBHOOK_KEY=your-webhook-secret
NUXT_PRIVATE_ENVIRONMENT=test_mode
NUXT_PRIVATE_RETURNURL=https://yourdomain.com/checkout/successConvex uses dashboard environment variables (not local ):
.envenv
DODO_PAYMENTS_API_KEY=dodo_test_...
DODO_PAYMENTS_ENVIRONMENT=test_mode
DODO_PAYMENTS_WEBHOOK_SECRET=your-webhook-secretWebhook key naming: Some adapters reference , others use . Check your framework's adapter docs and dashboard configuration to use the correct variable name.
DODO_PAYMENTS_WEBHOOK_KEYDODO_PAYMENTS_WEBHOOK_SECRET大多数适配器使用以下标准变量名:
env
DODO_PAYMENTS_API_KEY=dodo_test_...
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_ENVIRONMENT=test_mode
DODO_PAYMENTS_RETURN_URL=https://yourdomain.com/checkout/successNuxt 使用私有运行时配置前缀:
env
NUXT_PRIVATE_BEARER_TOKEN=dodo_test_...
NUXT_PRIVATE_WEBHOOK_KEY=your-webhook-secret
NUXT_PRIVATE_ENVIRONMENT=test_mode
NUXT_PRIVATE_RETURNURL=https://yourdomain.com/checkout/successConvex 使用仪表板环境变量(而非本地文件):
.envenv
DODO_PAYMENTS_API_KEY=dodo_test_...
DODO_PAYMENTS_ENVIRONMENT=test_mode
DODO_PAYMENTS_WEBHOOK_SECRET=your-webhook-secretWebhook密钥命名: 部分适配器使用,另一些则使用。请查阅你所用框架的适配器文档和仪表板配置,以使用正确的变量名。
DODO_PAYMENTS_WEBHOOK_KEYDODO_PAYMENTS_WEBHOOK_SECRETNarrowing environment
environment收窄environment
的类型
environmentAdapter configs type as , i.e. the literal union . is , which does not assign to it — passing it directly is a type error in every adapter.
environmentPick<ClientOptions, "environment">"test_mode" | "live_mode"process.env.Xstring | undefinedDefine this helper once and import it wherever you construct an adapter config:
typescript
// lib/dodo-env.ts
export const dodoEnvironment =
process.env.DODO_PAYMENTS_ENVIRONMENT === "live_mode" ? "live_mode" : "test_mode";Defaulting to is deliberate: a missing or misspelled variable must never silently resolve to live mode. Every example below uses .
test_modedodoEnvironment适配器配置中的类型为,即字面量联合类型。而的类型是,无法直接赋值给它——在所有适配器中直接传入都会导致类型错误。
environmentPick<ClientOptions, "environment">"test_mode" | "live_mode"process.env.Xstring | undefined只需定义一次此辅助函数,即可在所有构建适配器配置的地方导入使用:
typescript
// lib/dodo-env.ts
export const dodoEnvironment =
process.env.DODO_PAYMENTS_ENVIRONMENT === "live_mode" ? "live_mode" : "test_mode";默认回退到是有意设计的:缺失或拼写错误的变量绝不能静默解析为正式模式。下方所有示例都使用。
test_modedodoEnvironmentNext.js
Next.js
Package:
Route placement:, ,
@dodopayments/nextjsRoute placement:
app/api/checkout/route.tsapp/api/customer-portal/route.tsapp/api/webhook/route.ts包名:
路由位置:、、
@dodopayments/nextjs路由位置:
app/api/checkout/route.tsapp/api/customer-portal/route.tsapp/api/webhook/route.tsCheckout (choose one mode per route)
Checkout(每条路由选择一种模式)
typescript
// app/api/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: dodoEnvironment,
type: "static",
});
export const POST = Checkout({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
environment: dodoEnvironment,
type: "session",
});typescript
// app/api/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: dodoEnvironment,
type: "static",
});
export const POST = Checkout({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
environment: dodoEnvironment,
type: "session",
});Customer Portal
客户门户
typescript
// app/api/customer-portal/route.ts
import { CustomerPortal } from "@dodopayments/nextjs";
export const GET = CustomerPortal({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
environment: dodoEnvironment,
});typescript
// app/api/customer-portal/route.ts
import { CustomerPortal } from "@dodopayments/nextjs";
export const GET = CustomerPortal({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
environment: dodoEnvironment,
});Webhooks
Webhooks
typescript
// app/api/webhook/route.ts
import { Webhooks } from "@dodopayments/nextjs";
export const POST = Webhooks({
webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
onPayload: async (payload) => {
console.log("Webhook received:", payload.type);
},
});typescript
// app/api/webhook/route.ts
import { Webhooks } from "@dodopayments/nextjs";
export const POST = Webhooks({
webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
onPayload: async (payload) => {
console.log("Webhook received:", payload.type);
},
});Express
Express
Package:
@dodopayments/express包名:
@dodopayments/expressCheckout
Checkout
The Express adapter names its checkout export in lowercase, unlike every other adapter. does not resolve.
checkoutHandlerimport { Checkout } from "@dodopayments/express"typescript
import express from "express";
import { checkoutHandler } from "@dodopayments/express";
import { dodoEnvironment } from "./lib/dodo-env";
const app = express();
app.get("/api/checkout", checkoutHandler({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
environment: dodoEnvironment,
type: "static",
}));
app.post("/api/checkout", checkoutHandler({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
environment: dodoEnvironment,
type: "session",
}));与其他所有适配器不同,Express适配器的checkout导出名为小写的。无法解析。
checkoutHandlerimport { Checkout } from "@dodopayments/express"typescript
import express from "express";
import { checkoutHandler } from "@dodopayments/express";
import { dodoEnvironment } from "./lib/dodo-env";
const app = express();
app.get("/api/checkout", checkoutHandler({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
environment: dodoEnvironment,
type: "static",
}));
app.post("/api/checkout", checkoutHandler({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
environment: dodoEnvironment,
type: "session",
}));Customer Portal
客户门户
typescript
import { CustomerPortal } from "@dodopayments/express";
app.get("/api/customer-portal", CustomerPortal({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
environment: dodoEnvironment,
}));typescript
import { CustomerPortal } from "@dodopayments/express";
app.get("/api/customer-portal", CustomerPortal({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
environment: dodoEnvironment,
}));Webhooks
Webhooks
typescript
import { Webhooks } from "@dodopayments/express";
app.use(express.raw({ type: "application/json" }));
app.post("/api/webhook", Webhooks({
webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
onPayload: async (payload) => {
console.log("Webhook:", payload.type);
},
}));typescript
import { Webhooks } from "@dodopayments/express";
app.use(express.raw({ type: "application/json" }));
app.post("/api/webhook", Webhooks({
webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
onPayload: async (payload) => {
console.log("Webhook:", payload.type);
},
}));Fastify
Fastify
Package:
@dodopayments/fastifyFastify requires a string body parser to preserve the raw body for webhook verification.
包名:
@dodopayments/fastifyFastify需要配置字符串体解析器,以保留原始请求体用于webhook验证。
Checkout
Checkout
Checkout(config)getHandlerpostHandlertypescript
import Fastify from "fastify";
import { Checkout } from "@dodopayments/fastify";
import { dodoEnvironment } from "./lib/dodo-env";
const fastify = Fastify();
const staticCheckout = Checkout({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
environment: dodoEnvironment,
type: "static",
});
const sessionCheckout = Checkout({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
environment: dodoEnvironment,
type: "session",
});
fastify.get("/api/checkout", staticCheckout.getHandler);
fastify.post("/api/checkout", sessionCheckout.postHandler);Checkout(config)getHandlerpostHandlertypescript
import Fastify from "fastify";
import { Checkout } from "@dodopayments/fastify";
import { dodoEnvironment } from "./lib/dodo-env";
const fastify = Fastify();
const staticCheckout = Checkout({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
environment: dodoEnvironment,
type: "static",
});
const sessionCheckout = Checkout({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
environment: dodoEnvironment,
type: "session",
});
fastify.get("/api/checkout", staticCheckout.getHandler);
fastify.post("/api/checkout", sessionCheckout.postHandler);Webhooks
Webhooks
typescript
import { Webhooks } from "@dodopayments/fastify";
fastify.addContentTypeParser(
"application/json",
{ parseAs: "string" },
(req, body, done) => done(null, body)
);
fastify.post("/api/webhook", Webhooks({
webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
onPayload: async (payload) => {
console.log("Webhook:", payload.type);
},
}));typescript
import { Webhooks } from "@dodopayments/fastify";
fastify.addContentTypeParser(
"application/json",
{ parseAs: "string" },
(req, body, done) => done(null, body)
);
fastify.post("/api/webhook", Webhooks({
webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
onPayload: async (payload) => {
console.log("Webhook:", payload.type);
},
}));Hono
Hono
Package:
@dodopayments/hono包名:
@dodopayments/honoCheckout
Checkout
typescript
import { Hono } from "hono";
import { Checkout } from "@dodopayments/hono";
const app = new Hono();
app.get("/api/checkout", Checkout({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
environment: dodoEnvironment,
type: "static",
}));
app.post("/api/checkout", Checkout({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
environment: dodoEnvironment,
type: "session",
}));typescript
import { Hono } from "hono";
import { Checkout } from "@dodopayments/hono";
const app = new Hono();
app.get("/api/checkout", Checkout({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
environment: dodoEnvironment,
type: "static",
}));
app.post("/api/checkout", Checkout({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
environment: dodoEnvironment,
type: "session",
}));Customer Portal
客户门户
typescript
import { CustomerPortal } from "@dodopayments/hono";
app.get("/api/customer-portal", CustomerPortal({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
environment: dodoEnvironment,
}));typescript
import { CustomerPortal } from "@dodopayments/hono";
app.get("/api/customer-portal", CustomerPortal({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
environment: dodoEnvironment,
}));Webhooks
Webhooks
typescript
import { Webhooks } from "@dodopayments/hono";
app.post("/api/webhook", Webhooks({
webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
onPayload: async (payload) => {
console.log("Webhook:", payload.type);
},
}));typescript
import { Webhooks } from "@dodopayments/hono";
app.post("/api/webhook", Webhooks({
webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
onPayload: async (payload) => {
console.log("Webhook:", payload.type);
},
}));Astro
Astro
Package:
Route placement:, ,
@dodopayments/astroRoute placement:
src/pages/api/checkout.tssrc/pages/api/customer-portal.tssrc/pages/api/webhook.tsDisable prerendering for checkout routes.
包名:
路由位置:、、
@dodopayments/astro路由位置:
src/pages/api/checkout.tssrc/pages/api/customer-portal.tssrc/pages/api/webhook.ts请为checkout路由禁用预渲染。
Checkout
Checkout
typescript
// src/pages/api/checkout.ts
import { Checkout } from "@dodopayments/astro";
export const prerender = false;
// Astro reads env from import.meta.env, which is typed as string - so it needs
// the same narrowing as process.env. Define this alongside the other helper in
// lib/dodo-env.ts if you use both.
const dodoEnvironment =
import.meta.env.DODO_PAYMENTS_ENVIRONMENT === "live_mode" ? "live_mode" : "test_mode";
export const GET = Checkout({
bearerToken: import.meta.env.DODO_PAYMENTS_API_KEY,
returnUrl: import.meta.env.DODO_PAYMENTS_RETURN_URL,
environment: dodoEnvironment,
type: "static",
});
export const POST = Checkout({
bearerToken: import.meta.env.DODO_PAYMENTS_API_KEY,
returnUrl: import.meta.env.DODO_PAYMENTS_RETURN_URL,
environment: dodoEnvironment,
type: "session",
});typescript
// src/pages/api/checkout.ts
import { Checkout } from "@dodopayments/astro";
export const prerender = false;
// Astro从import.meta.env读取环境变量,其类型为string——因此需要和process.env做同样的类型收窄。
// 如果你同时使用两者,请将此辅助函数与其他辅助函数一同定义在lib/dodo-env.ts中。
const dodoEnvironment =
import.meta.env.DODO_PAYMENTS_ENVIRONMENT === "live_mode" ? "live_mode" : "test_mode";
export const GET = Checkout({
bearerToken: import.meta.env.DODO_PAYMENTS_API_KEY,
returnUrl: import.meta.env.DODO_PAYMENTS_RETURN_URL,
environment: dodoEnvironment,
type: "static",
});
export const POST = Checkout({
bearerToken: import.meta.env.DODO_PAYMENTS_API_KEY,
returnUrl: import.meta.env.DODO_PAYMENTS_RETURN_URL,
environment: dodoEnvironment,
type: "session",
});Webhooks
Webhooks
typescript
// src/pages/api/webhook.ts
import { Webhooks } from "@dodopayments/astro";
export const prerender = false;
export const POST = Webhooks({
webhookKey: import.meta.env.DODO_PAYMENTS_WEBHOOK_KEY,
onPayload: async (payload) => {
console.log("Webhook:", payload.type);
},
});typescript
// src/pages/api/webhook.ts
import { Webhooks } from "@dodopayments/astro";
export const prerender = false;
export const POST = Webhooks({
webhookKey: import.meta.env.DODO_PAYMENTS_WEBHOOK_KEY,
onPayload: async (payload) => {
console.log("Webhook:", payload.type);
},
});Remix
Remix
Package:
@dodopayments/remix包名:
@dodopayments/remixCheckout
Checkout
typescript
// app/routes/api.checkout.tsx
import { Checkout } from "@dodopayments/remix";
import type { LoaderFunctionArgs, ActionFunctionArgs } from "@remix-run/node";
const checkoutHandler = Checkout({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
environment: dodoEnvironment,
type: "session",
});
export const loader = ({ request }: LoaderFunctionArgs) => checkoutHandler(request);
export const action = ({ request }: ActionFunctionArgs) => checkoutHandler(request);typescript
// app/routes/api.checkout.tsx
import { Checkout } from "@dodopayments/remix";
import type { LoaderFunctionArgs, ActionFunctionArgs } from "@remix-run/node";
const checkoutHandler = Checkout({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
environment: dodoEnvironment,
type: "session",
});
export const loader = ({ request }: LoaderFunctionArgs) => checkoutHandler(request);
export const action = ({ request }: ActionFunctionArgs) => checkoutHandler(request);Customer Portal
客户门户
typescript
// app/routes/api.customer-portal.tsx
import { CustomerPortal } from "@dodopayments/remix";
import type { LoaderFunctionArgs } from "@remix-run/node";
const portalHandler = CustomerPortal({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
environment: dodoEnvironment,
});
export const loader = ({ request }: LoaderFunctionArgs) => portalHandler(request);typescript
// app/routes/api.customer-portal.tsx
import { CustomerPortal } from "@dodopayments/remix";
import type { LoaderFunctionArgs } from "@remix-run/node";
const portalHandler = CustomerPortal({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
environment: dodoEnvironment,
});
export const loader = ({ request }: LoaderFunctionArgs) => portalHandler(request);Webhooks
Webhooks
typescript
// app/routes/api.webhook.tsx
import { Webhooks } from "@dodopayments/remix";
import type { ActionFunctionArgs } from "@remix-run/node";
export const action = ({ request }: ActionFunctionArgs) =>
Webhooks({
webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
onPayload: async (payload) => {
console.log("Webhook:", payload.type);
},
})(request);typescript
// app/routes/api.webhook.tsx
import { Webhooks } from "@dodopayments/remix";
import type { ActionFunctionArgs } from "@remix-run/node";
export const action = ({ request }: ActionFunctionArgs) =>
Webhooks({
webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
onPayload: async (payload) => {
console.log("Webhook:", payload.type);
},
})(request);SvelteKit
SvelteKit
Package:
Route placement:, ,
@dodopayments/sveltekitRoute placement:
src/routes/api/checkout/+server.tssrc/routes/api/customer-portal/+server.tssrc/routes/api/webhook/+server.ts包名:
路由位置:、、
@dodopayments/sveltekit路由位置:
src/routes/api/checkout/+server.tssrc/routes/api/customer-portal/+server.tssrc/routes/api/webhook/+server.tsCheckout
Checkout
typescript
// src/routes/api/checkout/+server.ts
import { Checkout } from "@dodopayments/sveltekit";
import { DODO_PAYMENTS_API_KEY, DODO_PAYMENTS_RETURN_URL, DODO_PAYMENTS_ENVIRONMENT } from "$env/static/private";
const checkoutHandler = Checkout({
bearerToken: DODO_PAYMENTS_API_KEY,
returnUrl: DODO_PAYMENTS_RETURN_URL,
environment: DODO_PAYMENTS_ENVIRONMENT,
type: "session",
});
export const GET = checkoutHandler;
export const POST = checkoutHandler;typescript
// src/routes/api/checkout/+server.ts
import { Checkout } from "@dodopayments/sveltekit";
import { DODO_PAYMENTS_API_KEY, DODO_PAYMENTS_RETURN_URL, DODO_PAYMENTS_ENVIRONMENT } from "$env/static/private";
const checkoutHandler = Checkout({
bearerToken: DODO_PAYMENTS_API_KEY,
returnUrl: DODO_PAYMENTS_RETURN_URL,
environment: DODO_PAYMENTS_ENVIRONMENT,
type: "session",
});
export const GET = checkoutHandler;
export const POST = checkoutHandler;Webhooks
Webhooks
typescript
// src/routes/api/webhook/+server.ts
import { Webhooks } from "@dodopayments/sveltekit";
import { DODO_PAYMENTS_WEBHOOK_KEY } from "$env/static/private";
export const POST = Webhooks({
webhookKey: DODO_PAYMENTS_WEBHOOK_KEY,
onPayload: async (payload) => {
console.log("Webhook:", payload.type);
},
});typescript
// src/routes/api/webhook/+server.ts
import { Webhooks } from "@dodopayments/sveltekit";
import { DODO_PAYMENTS_WEBHOOK_KEY } from "$env/static/private";
export const POST = Webhooks({
webhookKey: DODO_PAYMENTS_WEBHOOK_KEY,
onPayload: async (payload) => {
console.log("Webhook:", payload.type);
},
});Nuxt
Nuxt
Package:
@dodopayments/nuxtAdd the module to and configure runtime variables:
nuxt.config.tstypescript
// nuxt.config.ts
export default defineNuxtConfig({
modules: ["@dodopayments/nuxt"],
runtimeConfig: {
private: {
bearerToken: process.env.NUXT_PRIVATE_BEARER_TOKEN,
webhookKey: process.env.NUXT_PRIVATE_WEBHOOK_KEY,
environment: process.env.NUXT_PRIVATE_ENVIRONMENT,
returnUrl: process.env.NUXT_PRIVATE_RETURNURL,
},
},
});包名:
@dodopayments/nuxt将模块添加到中并配置运行时变量:
nuxt.config.tstypescript
// nuxt.config.ts
export default defineNuxtConfig({
modules: ["@dodopayments/nuxt"],
runtimeConfig: {
private: {
bearerToken: process.env.NUXT_PRIVATE_BEARER_TOKEN,
webhookKey: process.env.NUXT_PRIVATE_WEBHOOK_KEY,
environment: process.env.NUXT_PRIVATE_ENVIRONMENT,
returnUrl: process.env.NUXT_PRIVATE_RETURNURL,
},
},
});Checkout
Checkout
The Nuxt module registers its handlers with , so , , and are auto-imported inside . Do not import them from — that entry point exports only the Nuxt module itself, and a named import from it will not resolve.
addServerImportsDircheckoutHandlercustomerPortalHandlerWebhooksserver/@dodopayments/nuxttypescript
// server/routes/api/checkout.ts
// checkoutHandler and useRuntimeConfig are auto-imported by the module.
const config = useRuntimeConfig();
export default checkoutHandler({
bearerToken: config.private.bearerToken,
returnUrl: config.private.returnUrl,
environment: config.private.environment,
type: "session",
});Nuxt模块通过注册其处理器,因此、和会在目录下自动导入。请勿从导入它们——该入口点仅导出Nuxt模块本身,命名导入无法解析。
addServerImportsDircheckoutHandlercustomerPortalHandlerWebhooksserver/@dodopayments/nuxttypescript
// server/routes/api/checkout.ts
// checkoutHandler和useRuntimeConfig由模块自动导入。
const config = useRuntimeConfig();
export default checkoutHandler({
bearerToken: config.private.bearerToken,
returnUrl: config.private.returnUrl,
environment: config.private.environment,
type: "session",
});Webhooks
Webhooks
typescript
// server/routes/api/webhook.ts
// Webhooks and useRuntimeConfig are auto-imported by the module.
const config = useRuntimeConfig();
export default Webhooks({
webhookKey: config.private.webhookKey,
onPayload: async (payload) => {
console.log("Webhook:", payload.type);
},
});typescript
// server/routes/api/webhook.ts
// Webhooks和useRuntimeConfig由模块自动导入。
const config = useRuntimeConfig();
export default Webhooks({
webhookKey: config.private.webhookKey,
onPayload: async (payload) => {
console.log("Webhook:", payload.type);
},
});TanStack Start
TanStack Start
Package:
@dodopayments/tanstack包名:
@dodopayments/tanstackCheckout
Checkout
Checkout(config)(request: Request) => Promise<Response>export const GET = Checkout(config)typescript
// src/routes/api/checkout.ts
import { Checkout } from "@dodopayments/tanstack";
import { dodoEnvironment } from "./lib/dodo-env";
export const GET = Checkout({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
environment: dodoEnvironment,
type: "static",
});
export const POST = Checkout({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
environment: dodoEnvironment,
type: "session",
});TanStack Start's server-route definition API has changed across releases ( was removed). Wrap these exports in whatever route helper your installed version provides; the adapter handlers themselves are unaffected.
createServerFileRouteCheckout(config)(request: Request) => Promise<Response>export const GET = Checkout(config)typescript
// src/routes/api/checkout.ts
import { Checkout } from "@dodopayments/tanstack";
import { dodoEnvironment } from "./lib/dodo-env";
export const GET = Checkout({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
environment: dodoEnvironment,
type: "static",
});
export const POST = Checkout({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
environment: dodoEnvironment,
type: "session",
});TanStack Start的服务端路由定义API在不同版本间有所变化(已被移除)。请将这些导出包裹在你安装版本所提供的任意路由辅助函数中;适配器处理器本身不受影响。
createServerFileRouteBun
Bun
Package:
@dodopayments/bun包名:
@dodopayments/bunCheckout and Portal
Checkout与门户
typescript
import { Checkout, CustomerPortal } from "@dodopayments/bun";
const checkoutHandler = Checkout({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
environment: dodoEnvironment,
type: "session",
});
const portalHandler = CustomerPortal({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
environment: dodoEnvironment,
});
Bun.serve({
port: 3000,
fetch(request) {
const url = new URL(request.url);
if (url.pathname === "/api/checkout") {
return checkoutHandler(request);
}
if (url.pathname === "/api/customer-portal" && request.method === "GET") {
return portalHandler(request);
}
return new Response("Not Found", { status: 404 });
},
});typescript
import { Checkout, CustomerPortal } from "@dodopayments/bun";
const checkoutHandler = Checkout({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
environment: dodoEnvironment,
type: "session",
});
const portalHandler = CustomerPortal({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
environment: dodoEnvironment,
});
Bun.serve({
port: 3000,
fetch(request) {
const url = new URL(request.url);
if (url.pathname === "/api/checkout") {
return checkoutHandler(request);
}
if (url.pathname === "/api/customer-portal" && request.method === "GET") {
return portalHandler(request);
}
return new Response("Not Found", { status: 404 });
},
});Convex
Convex
Package:
@dodopayments/convexConvex uses a component-based architecture. Register the component in :
convex.config.tstypescript
// convex/convex.config.ts
import { defineApp } from "convex/server";
import dodopayments from "@dodopayments/convex/convex.config";
const app = defineApp();
app.use(dodopayments);
export default app;Then use the component in your actions and HTTP routes:
typescript
// convex/checkout.ts
import { mutation } from "./_generated/server";
import { components } from "./_generated/server";
export const createCheckoutSession = mutation({
args: { customerId: v.string() },
handler: async (ctx, args) => {
const dodo = components.dodopayments;
return dodo.checkout.createSession(ctx, {
customerId: args.customerId,
// ... checkout params
});
},
});Convex only supports session checkout, not static or dynamic modes.
包名:
@dodopayments/convexConvex采用基于组件的架构。请在中注册该组件:
convex.config.tstypescript
// convex/convex.config.ts
import { defineApp } from "convex/server";
import dodopayments from "@dodopayments/convex/convex.config";
const app = defineApp();
app.use(dodopayments);
export default app;然后在你的action和HTTP路由中使用该组件:
typescript
// convex/checkout.ts
import { mutation } from "./_generated/server";
import { components } from "./_generated/server";
export const createCheckoutSession = mutation({
args: { customerId: v.string() },
handler: async (ctx, args) => {
const dodo = components.dodopayments;
return dodo.checkout.createSession(ctx, {
customerId: args.customerId,
// ... checkout params
});
},
});Convex仅支持会话式checkout,不支持静态或动态模式。
Common mistakes
常见错误
-
Duplicate POST handlers: Next.js and Astro docs show twodeclarations. Choose one checkout mode per route or add routing logic to dispatch between them.
export const POST -
Wrong webhook variable name: Check whether your adapter usesor
DODO_PAYMENTS_WEBHOOK_KEY. The docs are inconsistent; use the name your adapter actually references.DODO_PAYMENTS_WEBHOOK_SECRET -
Forgetting raw body preservation: Webhook handlers must receive the raw request body, not a re-parsed JSON object. Fastify requires an explicit string body parser; Express needs; other frameworks handle this automatically. Webhook signature verification is covered in the
express.raw()skill.webhook-integration -
Mixing framework conventions: Each framework has its own request/response shape. Don't try to use a Next.js handler in Express or vice versa. Use the adapter for your framework.
-
Hardcoding secrets: Always read API keys and webhook secrets from environment variables, never from code or config files.
-
Skipping environment setup: The adapters won't work withoutand
DODO_PAYMENTS_API_KEY. Set these before testing.DODO_PAYMENTS_ENVIRONMENT -
Usingdirectly: The core package is an internal dependency, not a documented public entry point. Use the framework adapter for your stack.
@dodopayments/core
- 重复的POST处理器: Next.js和Astro的文档中展示了两个声明。每条路由请选择一种checkout模式,或添加路由逻辑在不同模式间进行分发。
export const POST - Webhook变量名错误: 请确认你的适配器使用的是还是
DODO_PAYMENTS_WEBHOOK_KEY。文档存在不一致的情况,请使用适配器实际引用的变量名。DODO_PAYMENTS_WEBHOOK_SECRET - 忘记保留原始请求体: Webhook处理器必须接收原始请求体,而非重新解析后的JSON对象。Fastify需要显式配置字符串体解析器;Express需要使用;其他框架会自动处理。Webhook签名验证的相关内容在
express.raw()技能中介绍。webhook-integration - 混淆框架约定: 每个框架都有自己的请求/响应结构。不要将Next.js的处理器用于Express,反之亦然。请使用对应你所用框架的适配器。
- 硬编码密钥: 始终从环境变量中读取API密钥和webhook密钥,绝不要直接写在代码或配置文件中。
- 跳过环境配置: 没有和
DODO_PAYMENTS_API_KEY时适配器无法工作。请在测试前完成这些配置。DODO_PAYMENTS_ENVIRONMENT - 直接使用: 核心包是内部依赖,并非公开的文档化入口点。请使用对应你技术栈的框架适配器。
@dodopayments/core