Skip to main content

前提条件

要集成 Dodo Payments API,您需要:
  • 一个 Dodo Payments 商户账户
  • 从仪表板获取的 API 凭证(API 密钥和 webhook 密钥)

仪表板设置

  1. 访问 Dodo Payments 仪表板
  2. 创建产品(一次性付款或订阅)。订阅产品的定价必须至少为 $1(或您所选货币的等值金额);不支持低于此最低金额的定价。
  3. 生成您的 API 密钥:
    • 前往开发者 > API
    • 详细指南
    • 将 API 密钥复制到名为 DODO_PAYMENTS_API_KEY 的环境变量中
  4. 配置 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。
2

Redirect customer to checkout

创建 session 后,将客户重定向到 checkout_url 以启动托管流程。
优先使用 Checkout Sessions,这是开始收款最快、最可靠的方式。如需高级自定义,请参阅完整的 Checkout Sessions 指南API Reference

2. Overlay Checkout

如需无缝的页面内结账体验,请了解我们的 Overlay Checkout 集成。客户无需离开您的网站即可完成付款。

3. Inline Checkout

如需将结账页面直接嵌入页面,以实现完全集成的结账体验,请使用我们的 Inline Checkout 集成。您可以据此构建自定义订单摘要,并完全控制结账布局,同时由 Dodo Payments 安全地处理收款。 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 的形式包含付款详情,例如:
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.com
3

Pre-fill customer information (optional)

将客户或账单字段作为 query parameters 添加,以简化结账流程。
  • string
    客户的全名(如果提供了 firstName 或 lastName,则忽略此字段)。
  • string
    客户的名字。
  • string
    客户的姓氏。
  • string
    客户的电子邮件地址。
  • string
    客户所在国家/地区。
  • string
    街道地址。
  • string
    城市。
  • string
    州或省。
  • string
    邮政编码/ZIP code。
  • boolean
    true 或 false
4

Control form fields (optional)

您可以禁用特定字段,使其对客户只读。当您已经拥有客户信息(例如已登录用户的信息)时,这非常有用。
要禁用字段,请提供其值,并将相应的 disable… flag 设置为 true
禁用字段有助于防止意外更改并确保数据一致性。
设置 showDiscounts=false 将禁用并隐藏结账表单中的折扣部分。如果您不希望客户在结账时输入 coupon 或 promo code,请使用此设置。
5

Add advanced controls (optional)

  • string
    指定支付货币。默认为账单国家/地区的货币。
  • boolean
    默认值:"true"
    显示或隐藏货币选择器。
  • number
    固定收取的金额,以主要货币单位表示(例如,12.5 表示 $12.50)。仅适用于 Pay What You Want 产品。如果该值低于产品最低价格,则会被忽略。
  • string
    自定义元数据字段(例如 metadata_orderId=123)。
支付链接中的 paymentAmount 与 Checkout Sessions API 中的 amount 字段并非相同单位。链接参数使用主要货币单位(12.5 = 12.50),而APIproductcart[].amount使用最小面额(1250=12.50),而 API 的 `product_cart[].amount` 使用最小面额(`1250` = 12.50)。有关 API 字段,请参阅 Dynamic Pricing
6

Share the link

将已完成的支付链接发送给客户。客户访问链接时,所有查询参数都会被收集并与会话 ID 一起存储。随后,URL 会被简化为仅包含 session 参数(例如 ?session=sess_1a2b3c4d)。存储的信息会在页面刷新后继续保留,并可在整个结账过程中访问。
现在,客户的结账体验会根据你的参数进行简化和个性化。

4. 动态支付链接

对于大多数使用场景,建议使用 Checkout Sessions,因为它提供了更大的灵活性和控制力。
通过 API 调用或我们的 SDK 创建,并包含客户详细信息。示例如下: 创建动态支付链接有两个 API:
两个链接创建端点均已弃用POST /paymentsPOST /subscriptions 仍可用于现有集成,但新集成应改用 Checkout SessionsPOST /checkouts)。
下面的指南介绍如何创建一次性支付链接。 有关集成订阅的详细说明,请参阅订阅集成指南
请确保传递 payment_link = true 以获取支付链接
创建支付链接后,将客户重定向到支付完成页面。

实现 Webhooks

设置 API 端点以接收支付通知。以下是使用 Next.js 的示例:
我们的 webhook 实现遵循 Standard Webhooks 规范。有关 webhook 类型定义,请参阅我们的 Webhook Event Guide

要监听的事件

启用 payload.type,并处理一次性支付流程中相关的事件。至少应监听以下事件:
始终根据 webhook 中的 payment.succeeded 完成履约,而不是根据浏览器重定向完成 — 如果客户关闭标签页,重定向可能会被跳过;而 webhook 会一直重试,直到收到确认。
如果你销售带有许可证密钥的数字产品,还应处理 license_key.created。有关完整的事件列表(包括订阅、权益、额度、恢复和催收事件),请参阅 Webhook Event Guide 你可以在 GitHub 上参考这个使用 Next.js 和 TypeScript 实现演示的项目。 你可以在此处查看在线实现。

Checkout 与货币须知

动态(Pay-What-You-Want)金额使用产品的基础货币 — 而不是任意本地货币 — 且基础货币仅限于 USD、INR、GBP 和 EUR。如果要以其他货币(例如 PHP)收取固定金额,不能直接传递该金额:请使用 Adaptive Pricing(按实时 FX 将基础金额进行转换)或 Localized Pricing(按每种货币设置固定价格,但与 Pay-What-You-Want 不兼容)。
**明确设置货币。**在 checkout session 中传递 billing_currencybilling_address.country。如果省略,系统会根据客户的 IP 检测货币和国家/地区(Adaptive Currency),结果可能与你计划收取的货币不一致。
Checkout sessions 会在 24 小时后过期(当 confirm: true 时为 15 分钟),并且每个 checkout_url 都是一次性使用 — 请为每位客户和每次支付尝试生成新的 session,不要重复使用链接。
**一键重复购买。**对于已保存支付方式的回头客,将 payment_method_idconfirm: true 一起传递,即可立即扣款,完全跳过支付方式选择。

相关 API reference

Create Checkout Session

用于创建一次性支付和订阅的安全托管 checkout sessions 的 API reference

Create Payment Link

用于以编程方式创建动态支付链接的 API reference
最后修改于 2026年8月6日