Dodo Payments

MuseMVP 集成了 Dodo Payments 作为支付网关之一。通过统一的 Muse Billing 模块，它与 Creem、Stripe、Waffo 共用同一套合约与权益模型，支持订阅、一次性购买与客户门户。本文介绍如何配置 Dodo 网关并了解其工作原理。

设置默认网关

当 Dodo Payments 是主要结账渠道时，设置 BILLING_DEFAULT_GATEWAY=muse_dodo。

网关选择

你仍可在单次结账请求中覆盖网关。环境变量默认值用于定价与 launch 流程。

获取 Dodo API 密钥

在 Dodo Payments 控制台获取 API 密钥，并设置 DODO_PAYMENTS_API_KEY 和 DODO_PAYMENTS_ENVIRONMENT。

密钥安全

网关凭证只保存在服务端环境变量或部署平台密钥中。切勿暴露到前端或版本库。

获取 Dodo Webhook 密钥

在 Dodo Payments 控制台创建 Webhook，并将回调 URL 设为：

https://example.com/api/muse-billing/notify/muse_dodo

选择需要监听的事件类型（或全部）：

payment.succeeded
payment.failed
payment.processing
payment.cancelled
subscription.active
subscription.updated
subscription.on_hold
subscription.renewed
subscription.plan_changed
subscription.cancelled
subscription.failed
subscription.expired

把 Dodo webhook 签名密钥写入 DODO_PAYMENTS_WEBHOOK_SECRET。

密钥安全

Webhook secret 保存在服务端环境变量中。与 Dodo 不一致会导致全部 webhook 被拒绝。

创建产品并获取产品 ID

结账产品 ID 来自对应网关的 <GATEWAY>_PRODUCT_ID_<PLAN> 环境变量。公开定价页使用稳定套餐 ID。

在 Dodo Payments 控制台创建对应产品后，把产品 ID 填入 DODO_PRODUCT_ID_* 环境变量。

本地开发测试

下载 Ngrok

Ngrok（https://dashboard.ngrok.com/get-started/setup/windows）是一款反向代理工具，可将本地开发服务暴露到公网。

运行

ngrok http 3000

回调域名

将终端中显示的域名作为 Webhook 配置中的回调地址。

切换到测试模式

设置 DODO_PAYMENTS_ENVIRONMENT=test_mode，并在控制台使用测试模式。

测试模式

Dodo 测试模式不会产生真实扣款，适合在本地验证订阅与一次性购买流程。

工作原理

了解 Muse Billing 如何将 Dodo Payments 接入系统。

集成文件

packages/billing/src/gateways/dodo/gateway.ts

packages/billing/src/gateways/dodo/mappers.ts

src/backend/api/routes/muse-billing/router.ts

文件	作用
`dodo/gateway.ts`	Dodo 网关实现：创建 checkout session、解析 Webhook、客户门户。
`dodo/mappers.ts`	将 Dodo Webhook 事件与订阅状态映射为 Muse 合约快照。
`router.ts`	API 路由：暴露 `/api/muse-billing/*` 端点。

核心流程

支付与客户门户的调用链路：

前端调用 POST /api/muse-billing/launch，传入 productId、可选 gatewayId（默认由 orchestrator 选择）等参数。

服务端从 DODO_PRODUCT_ID_* 环境变量解析 Dodo 产品或价格 ID。

创建 Dodo checkout session，并返回 launchUrl 供前端跳转到托管结账页。

支付完成后，Dodo 发送 Webhook；服务端校验签名并将合约生命周期与访问窗口同步到数据库。

当用户需要进入平台门户时，调用 POST /api/muse-billing/customer-hub 获取跳转到 Dodo 客户门户的链接，用于管理订阅或下载收据。