@dodopayments/bun 包为你的 Bun 服务器提供三个请求处理程序。Checkout 返回 checkout URL,CustomerPortal 将客户发送到 Customer Portal,而 Webhooks 验证 webhook 事件并将其路由到你的代码。每个处理程序都接收标准的 Request 并返回 Response,因此你可以从 Bun.serve() 的 fetch 处理程序中调用它。
Checkout Handler
使用静态、动态和 checkout session 流程创建 checkout URL。
Customer Portal
让客户管理其订阅和详细信息。
Webhooks
接收并处理 Dodo Payments webhook 事件。
安装
1
Install the Package
在项目根目录运行此命令:该包还需要
zod 3.25 或更高版本,并将其列为 peer dependency。2
Set Up Environment Variables
在项目根目录创建一个 Bun 会自动读取
.env 文件。在 Developer → API Keys 下创建 API key。在 Developer → Webhooks 下添加 webhook endpoint,并将其 Signing secret 复制到 DODO_PAYMENTS_WEBHOOK_KEY:.env 文件,因此示例会从 process.env 读取这些值。DODO_PAYMENTS_RETURN_URL 是 checkout 后客户返回的地址。如果不传入 environment,处理程序会使用 live_mode。test mode API key 只能与 test_mode 配合使用。路由处理程序示例
所有示例都使用 Bun 的原生服务器
Bun.serve(),并在其 fetch 处理程序中按路径和方法路由请求。- Checkout Handler
- Customer Portal Handler
- Webhook Handler
使用此处理程序将 Dodo Payments checkout 添加到你的 Bun 服务器。静态处理程序处理
GET 请求。session 和 dynamic 处理程序处理 POST 请求。动态 checkout 示例假设服务器会为 POST 请求返回 dynamicCheckoutHandler(request)。Checkout 路由处理程序
checkout 处理程序支持使用 Dodo Payments 收款的三种方式:- 静态 Payment Links: 可分享的 URL,无需代码即可收款。
- 动态 Payment Links: 使用自定义详细信息生成的 payment links。它们使用已弃用的 endpoints。
- Checkout Sessions: 为产品购物车、客户详细信息和自定义选项提供托管 checkout。这是推荐的流程。
Checkout 接收以下选项:
处理程序会为
GET 请求提供静态 checkout。对于 POST 请求,当 type 为 dynamic 时,它会创建 dynamic payment link,否则会创建 checkout session。
Static Checkout (GET)
Static Checkout (GET)
Dynamic Checkout (POST)
Dynamic Checkout (POST)
- 在 POST request 中将参数作为 JSON body 发送。
- 同时支持一次性付款和 recurring payments。处理程序会获取产品;如果产品是 recurring,则创建 subscription,否则创建一次性付款。
- body 需要
billing(包含street、city、state、country和zipcode)以及customer,另外还需要product_id或product_cart。Subscriptions 需要product_id。 - 有关所有支持的 body fields,请参阅:
响应格式
Dynamic checkout 返回包含 payment link(作为 checkout URL)的 JSON 响应:Checkout Sessions (POST)
Checkout Sessions (POST)
Checkout sessions 为一次性购买和 subscriptions 创建 hosted checkout,并提供完整的自定义控制。
product_cart 是唯一必填字段,并且至少需要一个产品。如果 body 不包含 return_url,处理程序会使用其配置中的 returnUrl。每个 checkout_url 只能使用一次,并会在 24 小时后过期;传入 confirm: true 时,则在 15 分钟后过期。使用 payment_method_id 创建的 session 不会返回 checkout_url,因此处理程序会返回 400。有关更多详细信息和所有支持的字段,请参阅 Checkout Sessions Integration Guide。响应格式
Checkout sessions 返回包含 checkout URL 的 JSON 响应:Customer Portal 路由处理程序
Customer Portal 路由处理程序会为你传入的客户创建 Customer Portal session,并将浏览器重定向到该 session。CustomerPortal 与 Checkout 接收相同的 bearerToken 和 environment 选项。
Query Parameters
如果缺少customer_id,处理程序会返回 400;如果无法创建 portal session,则返回 500。
Webhook 路由处理程序
webhook 路由处理程序会在运行你的代码之前,使用作为webhookKey 传入的 webhook secret 验证每个请求:
- Method: 仅支持 POST requests。其他 methods 返回 405。
- Signature Verification: 使用
webhookKey验证webhook-id、webhook-timestamp和webhook-signatureheaders,并遵循 Standard Webhooks specification。验证失败时返回 401。 - Payload Validation: 将 body 解析为 JSON,并使用 Zod 验证。JSON 无效或 payload 无效时返回 400。
- Error Handling:
- 401:无效签名
- 400:无效 payload
- 500:验证期间发生内部错误
- Event Routing: 对每个 event 调用
onPayload,然后调用该 event 类型对应的处理程序,并返回 200。
Bun.serve(),请求也会失败。