framework-adapters

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Framework 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
@dodopayments/*
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.
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
Checkout
/
CustomerPortal
/
Webhooks
, but two differ, and the return shapes differ as well. Check this table before writing imports:
AdapterCheckout exportPortal exportHandler shape
nextjs
,
hono
,
astro
,
bun
,
remix
,
tanstack
Checkout
CustomerPortal
returns a request handler
express
checkoutHandler
(lowercase)
CustomerPortal
returns
(req, res)
fastify
Checkout
CustomerPortal
returns
{ getHandler, postHandler }
sveltekit
Checkout
CustomerPortal
returns
{ GET, POST }
/
{ GET }
nuxt
checkoutHandler
(auto-imported)
customerPortalHandler
no import statement
convex
DodoPayments
component
—
createDodoWebhookHandler
The adapters handle raw body preservation for webhook verification, environment variable mapping, and framework-specific request/response shapes. Checkout payload design belongs to the
checkout-integration
skill; webhook business logic belongs to
webhook-integration
; portal behavior belongs to
customer-management
.
Dodo发布了
@dodopayments/*
系列包,通过框架特定的路由处理器封装了核心SDK。你无需自行编写HTTP处理器,只需导入适配器的处理器并直接挂载到路由中即可。
每个适配器都提供三类处理器:
  • Checkout: 静态(仅GET)、动态(带购物车的POST)或会话(带预构建会话的POST)。
  • CustomerPortal: 生成有时效的门户会话链接。
  • Webhooks: 验证webhook签名并派发带类型的事件。
不同适配器的导出名称并不统一。 大多数导出
Checkout
/
CustomerPortal
/
Webhooks
,但有两个例外,且返回结构也有所不同。编写导入语句前请参考下表:
适配器Checkout导出Portal导出处理器结构
nextjs
、
hono
、
astro
、
bun
、
remix
、
tanstack
Checkout
CustomerPortal
返回一个请求处理器
express
checkoutHandler
(小写)
CustomerPortal
返回
(req, res)
fastify
Checkout
CustomerPortal
返回
{ getHandler, postHandler }
sveltekit
Checkout
CustomerPortal
返回
{ GET, POST }
/
{ GET }
nuxt
checkoutHandler
(自动导入)
customerPortalHandler
无需导入语句
convex
DodoPayments
组件
—
createDodoWebhookHandler
这些适配器会处理webhook验证所需的原始请求体保留、环境变量映射,以及框架特定的请求/响应结构。Checkout的payload设计属于
checkout-integration
技能的范畴;webhook业务逻辑属于
webhook-integration
技能;门户相关功能属于
customer-management
技能。

Framework selection and installation

框架选择与安装

FrameworkPackageInstall
Next.js
@dodopayments/nextjs
npm install @dodopayments/nextjs
Express
@dodopayments/express
npm install @dodopayments/express
Fastify
@dodopayments/fastify
npm install @dodopayments/fastify
Hono
@dodopayments/hono
npm install @dodopayments/hono
Astro
@dodopayments/astro
npm install @dodopayments/astro
Remix
@dodopayments/remix
npm install @dodopayments/remix
SvelteKit
@dodopayments/sveltekit
npm install @dodopayments/sveltekit
Nuxt
@dodopayments/nuxt
npm install @dodopayments/nuxt
TanStack Start
@dodopayments/tanstack
npm install @dodopayments/tanstack
Bun
@dodopayments/bun
bun add @dodopayments/bun
Convex
@dodopayments/convex
npm install @dodopayments/convex
框架包名安装命令
Next.js
@dodopayments/nextjs
npm install @dodopayments/nextjs
Express
@dodopayments/express
npm install @dodopayments/express
Fastify
@dodopayments/fastify
npm install @dodopayments/fastify
Hono
@dodopayments/hono
npm install @dodopayments/hono
Astro
@dodopayments/astro
npm install @dodopayments/astro
Remix
@dodopayments/remix
npm install @dodopayments/remix
SvelteKit
@dodopayments/sveltekit
npm install @dodopayments/sveltekit
Nuxt
@dodopayments/nuxt
npm install @dodopayments/nuxt
TanStack Start
@dodopayments/tanstack
npm install @dodopayments/tanstack
Bun
@dodopayments/bun
bun add @dodopayments/bun
Convex
@dodopayments/convex
npm install @dodopayments/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/success
Nuxt 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/success
Convex uses dashboard environment variables (not local
.env
):
env
DODO_PAYMENTS_API_KEY=dodo_test_...
DODO_PAYMENTS_ENVIRONMENT=test_mode
DODO_PAYMENTS_WEBHOOK_SECRET=your-webhook-secret
Webhook key naming: Some adapters reference
DODO_PAYMENTS_WEBHOOK_KEY
, others use
DODO_PAYMENTS_WEBHOOK_SECRET
. Check your framework's adapter docs and dashboard configuration to use the correct variable name.
大多数适配器使用以下标准变量名:
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/success
Nuxt 使用私有运行时配置前缀:
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/success
Convex 使用仪表板环境变量(而非本地
.env
文件):
env
DODO_PAYMENTS_API_KEY=dodo_test_...
DODO_PAYMENTS_ENVIRONMENT=test_mode
DODO_PAYMENTS_WEBHOOK_SECRET=your-webhook-secret
Webhook密钥命名: 部分适配器使用
DODO_PAYMENTS_WEBHOOK_KEY
,另一些则使用
DODO_PAYMENTS_WEBHOOK_SECRET
。请查阅你所用框架的适配器文档和仪表板配置,以使用正确的变量名。

Narrowing
environment

收窄
environment
的类型

Adapter configs type
environment
as
Pick<ClientOptions, "environment">
, i.e. the literal union
"test_mode" | "live_mode"
.
process.env.X
is
string | undefined
, which does not assign to it — passing it directly is a type error in every adapter.
Define 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
test_mode
is deliberate: a missing or misspelled variable must never silently resolve to live mode. Every example below uses
dodoEnvironment
.
适配器配置中
environment
的类型为
Pick<ClientOptions, "environment">
,即字面量联合类型
"test_mode" | "live_mode"
。而
process.env.X
的类型是
string | undefined
,无法直接赋值给它——在所有适配器中直接传入都会导致类型错误。
只需定义一次此辅助函数,即可在所有构建适配器配置的地方导入使用:
typescript
// lib/dodo-env.ts
export const dodoEnvironment =
  process.env.DODO_PAYMENTS_ENVIRONMENT === "live_mode" ? "live_mode" : "test_mode";
默认回退到
test_mode
是有意设计的:缺失或拼写错误的变量绝不能静默解析为正式模式。下方所有示例都使用
dodoEnvironment
。

Next.js

Next.js

Package:
@dodopayments/nextjs

Route placement:
app/api/checkout/route.ts
,
app/api/customer-portal/route.ts
,
app/api/webhook/route.ts
包名:
@dodopayments/nextjs

路由位置:
app/api/checkout/route.ts
、
app/api/customer-portal/route.ts
、
app/api/webhook/route.ts

Checkout (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/express

Checkout

Checkout

The Express adapter names its checkout export
checkoutHandler
in lowercase, unlike every other adapter.
import { Checkout } from "@dodopayments/express"
does not resolve.
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导出名为小写的
checkoutHandler
。
import { 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/fastify
Fastify requires a string body parser to preserve the raw body for webhook verification.
包名:
@dodopayments/fastify
Fastify需要配置字符串体解析器,以保留原始请求体用于webhook验证。

Checkout

Checkout

Checkout(config)
returns an object with
getHandler
and
postHandler
, not a single callable. Build it once and mount each method, rather than calling the result.
typescript
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)
会返回一个包含
getHandler
和
postHandler
的对象,而非单个可调用函数。请先构建一次处理器,再分别挂载每个方法,而不是直接调用返回结果。
typescript
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/hono

Checkout

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:
@dodopayments/astro

Route placement:
src/pages/api/checkout.ts
,
src/pages/api/customer-portal.ts
,
src/pages/api/webhook.ts
Disable prerendering for checkout routes.
包名:
@dodopayments/astro

路由位置:
src/pages/api/checkout.ts
、
src/pages/api/customer-portal.ts
、
src/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/remix

Checkout

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:
@dodopayments/sveltekit

Route placement:
src/routes/api/checkout/+server.ts
,
src/routes/api/customer-portal/+server.ts
,
src/routes/api/webhook/+server.ts
包名:
@dodopayments/sveltekit

路由位置:
src/routes/api/checkout/+server.ts
、
src/routes/api/customer-portal/+server.ts
、
src/routes/api/webhook/+server.ts

Checkout

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/nuxt
Add the module to
nuxt.config.ts
and configure runtime variables:
typescript
// 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.ts
中并配置运行时变量:
typescript
// 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
addServerImportsDir
, so
checkoutHandler
,
customerPortalHandler
, and
Webhooks
are auto-imported inside
server/
. Do not import them from
@dodopayments/nuxt
— that entry point exports only the Nuxt module itself, and a named import from it will not resolve.
typescript
// 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模块通过
addServerImportsDir
注册其处理器,因此
checkoutHandler
、
customerPortalHandler
和
Webhooks
会在
server/
目录下自动导入。请勿从
@dodopayments/nuxt
导入它们——该入口点仅导出Nuxt模块本身,命名导入无法解析。
typescript
// 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/tanstack

Checkout

Checkout

Checkout(config)
returns a plain
(request: Request) => Promise<Response>
, so export it directly as the route's method handler. The adapter's own documented usage is
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 (
createServerFileRoute
was removed). Wrap these exports in whatever route helper your installed version provides; the adapter handlers themselves are unaffected.
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的服务端路由定义API在不同版本间有所变化(
createServerFileRoute
已被移除)。请将这些导出包裹在你安装版本所提供的任意路由辅助函数中;适配器处理器本身不受影响。

Bun

Bun

Package:
@dodopayments/bun
包名:
@dodopayments/bun

Checkout 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/convex
Convex uses a component-based architecture. Register the component in
convex.config.ts
:
typescript
// 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/convex
Convex采用基于组件的架构。请在
convex.config.ts
中注册该组件:
typescript
// 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

常见错误

  1. Duplicate POST handlers: Next.js and Astro docs show two
    export const POST
    declarations. Choose one checkout mode per route or add routing logic to dispatch between them.
  2. Wrong webhook variable name: Check whether your adapter uses
    DODO_PAYMENTS_WEBHOOK_KEY
    or
    DODO_PAYMENTS_WEBHOOK_SECRET
    . The docs are inconsistent; use the name your adapter actually references.
  3. 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
    express.raw()
    ; other frameworks handle this automatically. Webhook signature verification is covered in the
    webhook-integration
    skill.
  4. 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.
  5. Hardcoding secrets: Always read API keys and webhook secrets from environment variables, never from code or config files.
  6. Skipping environment setup: The adapters won't work without
    DODO_PAYMENTS_API_KEY
    and
    DODO_PAYMENTS_ENVIRONMENT
    . Set these before testing.
  7. Using
    @dodopayments/core
    directly:
    The core package is an internal dependency, not a documented public entry point. Use the framework adapter for your stack.
  1. 重复的POST处理器: Next.js和Astro的文档中展示了两个
    export const POST
    声明。每条路由请选择一种checkout模式,或添加路由逻辑在不同模式间进行分发。
  2. Webhook变量名错误: 请确认你的适配器使用的是
    DODO_PAYMENTS_WEBHOOK_KEY
    还是
    DODO_PAYMENTS_WEBHOOK_SECRET
    。文档存在不一致的情况,请使用适配器实际引用的变量名。
  3. 忘记保留原始请求体: Webhook处理器必须接收原始请求体,而非重新解析后的JSON对象。Fastify需要显式配置字符串体解析器;Express需要使用
    express.raw()
    ;其他框架会自动处理。Webhook签名验证的相关内容在
    webhook-integration
    技能中介绍。
  4. 混淆框架约定: 每个框架都有自己的请求/响应结构。不要将Next.js的处理器用于Express,反之亦然。请使用对应你所用框架的适配器。
  5. 硬编码密钥: 始终从环境变量中读取API密钥和webhook密钥,绝不要直接写在代码或配置文件中。
  6. 跳过环境配置: 没有
    DODO_PAYMENTS_API_KEY
    和
    DODO_PAYMENTS_ENVIRONMENT
    时适配器无法工作。请在测试前完成这些配置。
  7. 直接使用
    @dodopayments/core
    :
    核心包是内部依赖,并非公开的文档化入口点。请使用对应你技术栈的框架适配器。

Resources

参考资源