前提条件
要集成 Dodo Payments API,您需要:- 一个 Dodo Payments 商户账户
- 从仪表板获取的 API 凭证(API 密钥和 webhook 密钥)
仪表板设置
- 访问 Dodo Payments 仪表板
- 创建产品(一次性付款或订阅)。订阅产品的定价必须至少为 $1(或您所选货币的等值金额);不支持低于此最低金额的定价。
-
生成您的 API 密钥:
- 前往开发者 > API
- 详细指南
- 将 API 密钥复制到名为 DODO_PAYMENTS_API_KEY 的环境变量中
-
配置 webhooks:
- 前往开发者 > Webhooks
- 创建用于支付通知的 webhook URL
- 将 webhook 密钥复制到环境变量中
集成
支付链接
选择适合您使用场景的集成路径:- Checkout Sessions(推荐):适用于大多数集成。在您的服务器上创建 session,然后将客户重定向到安全的托管结账页面。
- Overlay Checkout:当您需要在页面内以模态叠加层形式打开结账页面时使用。
- Inline Checkout:将结账页面直接嵌入页面布局,以实现完全集成且带有品牌样式的结账体验。
- Static Payment Links:无需代码、可立即分享的 URL,适用于快速收款。
- Dynamic Payment Links:以编程方式创建的链接。不过,我们推荐使用 Checkout Sessions,因为它提供更大的灵活性。
- Mobile Checkout SDKs:适用于原生 Android、iOS、React Native 和 Flutter 应用。按照上述方式在服务器上创建 session,然后将
checkout_url交给 SDK。
Overlay Checkout 和 Inline Checkout 仅适用于浏览器——它们会将结账页面嵌入网页中。如果您正在构建原生移动应用,请在服务器上创建 checkout session,然后改用 Mobile Checkout SDKs 打开它。
1. Checkout Sessions
使用 Checkout Sessions 为一次性付款或订阅创建安全的托管结账体验。在您的服务器上创建 session,然后将客户重定向到返回的checkout_url。
Checkout sessions 默认有效期为 24 小时。如果传入
confirm=true,session 的有效期为 15 分钟,并且必须提供所有必填字段。1
Create a checkout session
选择您偏好的 SDK,或调用 REST API。
- Node.js SDK
- Python SDK
- REST API
2
Redirect customer to checkout
创建 session 后,将客户重定向到
checkout_url 以启动托管流程。2. Overlay Checkout
如需无缝的页面内结账体验,请了解我们的 Overlay Checkout 集成。客户无需离开您的网站即可完成付款。3. Inline Checkout
如需将结账页面直接嵌入页面,以实现完全集成的结账体验,请使用我们的 Inline Checkout 集成。您可以据此构建自定义订单摘要,并完全控制结账布局,同时由 Dodo Payments 安全地处理收款。4. Static Payment Links
Static payment links 允许您通过分享简单的 URL 快速收款。您可以通过传递 query parameters 预填客户信息、控制表单字段并添加自定义 metadata,从而自定义结账体验。1
Construct your payment link
从基础 URL 开始,并附加您的产品 ID:
2
Add core parameters
包含必要的 query parameters:
-
integer默认值:"1"要购买的商品数量。
-
string必填付款完成后用于重定向的 URL。
重定向 URL 将以 query parameters 的形式包含付款详情,例如:
如果产品启用了 license keys,还会附加
https://example.com/?payment_id=pay_ts2ySpzg07phGeBZqePbH&status=succeeded&email=customer%40example.com如果产品启用了 license keys,还会附加
license_key 参数(多个 key 以逗号分隔):https://example.com/?payment_id=pay_xxx&status=succeeded&license_key=LK-001&email=customer%40example.com3
4
Control form fields (optional)
您可以禁用特定字段,使其对客户只读。当您已经拥有客户信息(例如已登录用户的信息)时,这非常有用。
disable… flag 设置为 true:- Disable Flags Table
设置
showDiscounts=false 将禁用并隐藏结账表单中的折扣部分。如果您不希望客户在结账时输入 coupon 或 promo code,请使用此设置。5
6
Share the link
将已完成的支付链接发送给客户。客户访问链接时,所有查询参数都会被收集并与会话 ID 一起存储。随后,URL 会被简化为仅包含 session 参数(例如
?session=sess_1a2b3c4d)。存储的信息会在页面刷新后继续保留,并可在整个结账过程中访问。现在,客户的结账体验会根据你的参数进行简化和个性化。
4. 动态支付链接
通过 API 调用或我们的 SDK 创建,并包含客户详细信息。示例如下: 创建动态支付链接有两个 API:- 一次性支付链接 API API reference
- 订阅支付链接 API API reference
请确保传递
payment_link = true 以获取支付链接 - Node.js SDK
- Python SDK
- Go SDK
- Api Reference
创建支付链接后,将客户重定向到支付完成页面。
实现 Webhooks
设置 API 端点以接收支付通知。以下是使用 Next.js 的示例:要监听的事件
启用payload.type,并处理一次性支付流程中相关的事件。至少应监听以下事件:
如果你销售带有许可证密钥的数字产品,还应处理
license_key.created。有关完整的事件列表(包括订阅、权益、额度、恢复和催收事件),请参阅 Webhook Event Guide。
你可以在 GitHub 上参考这个使用 Next.js 和 TypeScript 实现演示的项目。
你可以在此处查看在线实现。
Checkout 与货币须知
Checkout sessions 会在 24 小时后过期(当
confirm: true 时为 15 分钟),并且每个 checkout_url 都是一次性使用 — 请为每位客户和每次支付尝试生成新的 session,不要重复使用链接。**一键重复购买。**对于已保存支付方式的回头客,将
payment_method_id 与 confirm: true 一起传递,即可立即扣款,完全跳过支付方式选择。相关 API reference
Create Checkout Session
用于创建一次性支付和订阅的安全托管 checkout sessions 的 API reference
Create Payment Link
用于以编程方式创建动态支付链接的 API reference