Dodo Payments 是商户记录(Merchant of Record),作为法律上的销售方,负责收取和缴纳销售税并处理拒付。开发者的代码负责创建结账会话、验证 webhook 并授予访问权限。
用途
本技能适用于任何 Dodo Payments 集成或账户任务。几乎每个集成都遵循三个步骤:在服务端用 client.checkoutSessions.create(...) 创建结账会话并将客户重定向到 checkout_url;处理 webhook,Dodo 会向端点 POST 签名 webhook,需用 client.webhooks.unwrap(...) 在原始请求体上验签;从已验证的 webhook 授予访问,一次性购买用 payment.succeeded,订阅用 subscription.active。return_url 重定向只是 UI 提示,绝不是付款证明。
主要能力
- 客户端设置与测试/实时模式:environment 选项为 'test_mode' 或 'live_mode'(SDK 默认),基础 URL 分别为 https://test.dodopayments.com 和 https://live.dodopayments.com,API 密钥前缀为 dodo_test_ 和 dodo_live_。支持 npm、pip、Go、PHP、Ruby、Java、Kotlin SDK。金额为最小货币单位的整数,如 USD 10.00 为 1000。SDK 对连接错误、408、409、429 和 5xx 重试两次;列表方法的 for await 会遍历所有页。
- 安全规则:必须在原始请求体上验证 webhook 签名,使用 client.webhooks.unwrap() 或 standardwebhooks 包,不得手写 HMAC 或验证重新序列化的 JSON;unsafeUnwrap() 仅用于 dodo wh trigger 发送的未签名负载。上线前使用测试模式,通过 references/testing-go-live.md 切换实时模式。绝不在客户端代码中放置 API 密钥,浏览器包、移动应用、桌面应用和 CLI 都不持有 Dodo API 密钥,Dodo 也没有可发布密钥,客户端只接收 URL。实时模式下任何写操作(退款、取消、套餐变更、扣费、删除、webhook 端点变更)前需确认资源 ID 和影响并等待用户同意。仅从已验证的 webhook 或服务端 API 读取授予访问,绝不从 return_url 查询参数、浏览器状态或移动 SDK 结果授予。
- 路由表涵盖:结账会话、React Native/Flutter/iOS/Android 移动结账、订阅(试用、升级降级、按比例计费、暂停、取消、按需扣费、催款)、webhook 端点与验证、幂等、重试、用量计费、积分、许可证密钥、产品、折扣、本地化定价、客户、退款争议、框架适配器(Next.js、Express、Hono、Fastify、Astro、Remix、SvelteKit、Nuxt、TanStack、Bun、Convex)、Better Auth、BillingSDK、测试上线、MCP 服务器。
使用方式
通过 MCP 服务器(https://mcp.dodopayments.com/mcp)可调用五个工具:search_docs 查找指南和文档页;read_docs_page 以 Markdown 读取完整文档页;search 查找 SDK 和 API 方法、参数和响应字段;execute 在用户账户上运行 TypeScript 调用 dodopayments SDK;feedback 报告文档错误或缺失。客户端通过 OAuth 登录,无需 API 密钥。写集成代码前先调用 search_docs,调用 execute 前先调用 search,实时模式写操作遵循安全规则 4。
适用场景
适用于需要集成 Dodo Payments 支付、订阅、用量计费、积分、许可证密钥、折扣、本地化定价、客户管理、退款争议处理的项目,以及使用 Next.js、Express 等框架或 Better Auth 的应用。
限制
资料未提供具体收费或价格信息。旧模式应替换:client.payments.create() 和 client.subscriptions.create() 已弃用,改用 client.checkoutSessions.create();discount_code 字符串已弃用,改用 discount_codes 数组;license_key.created webhook 为旧版,改用 entitlement_grant.created;client.licenseKeys.list()、retrieve()、update() 已弃用,通过 entitlement grants 读取密钥;框架适配器中 type: "dynamic" 结账调用已弃用端点,改用 type: "session"。