Dodo Payments

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

设置默认网关

当 Dodo Payments 是你的主要结账渠道时，在 后台 → 运行时设置 把默认网关设为 muse_dodo。

网关选择

你仍可在单次结账请求中覆盖网关。存储的默认值用于定价与 launch 流程。

获取 Dodo API 密钥

在 Dodo Payments 控制台的 Developer → API 中获取 API 密钥。把 API 密钥和环境（test_mode 或 live_mode）填入 后台 → 运行时设置。

密钥安全

网关凭证加密落库。切勿暴露到前端或版本库。

获取 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

将 Webhook 签名密钥填入 后台 → 运行时设置。保存后请在 Dodo 侧确认同一份 secret 仍然匹配。

密钥安全

Webhook secret 加密落库。与 Dodo 不一致会导致全部 webhook 被拒绝。

创建产品并获取产品 ID

结账产品 ID 存在 后台 → 运行时设置（billing.productMap）。公开定价页使用稳定套餐 ID（pro_monthly、pro_yearly、lifetime）。

在 Dodo Payments 控制台创建对应产品后，把产品 ID 填入后台产品映射。

本地开发测试

下载 Ngrok

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

运行

ngrok http 3000

回调域名

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

切换到测试模式

确保后台运行时设置里的 Dodo 环境为 test_mode，并在 Dodo Payments 控制台使用测试模式完成支付验证。

测试模式

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

工作原理

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

集成文件

src/modules/muse-billing/lib/gateways/dodo/gateway.ts

src/modules/muse-billing/lib/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 选择）等参数。

服务端从后台 billing.productMap 设置中解析 Dodo 产品 ID。

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

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

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