Skip to main content

Checkout Sessions

为一次性付款和订阅创建安全的托管 checkout。

Payment Links

分享 URL,无需编写代码即可收款。

Webhooks

监听付款事件并履行订单。

API Reference

完整的 endpoint 文档和在线测试。

前提条件

开始之前,你需要:
  • 一个 Dodo Payments 账户。
  • 至少一个产品。在控制面板的 Products 下创建产品。价格非零的订阅产品必须满足客户付款所用币种的订阅最低金额:USD 为 $1.00。除 USD、EUR 和 GBP 之外的币种也必须至少价值 $1.00。也支持 $0 订阅。
  • 一个 API key。在 Developer → API Keys 下创建,并将其存储在 DODO_PAYMENTS_API_KEY 环境变量中。在构建期间,请在测试模式下创建 key:本页面上的示例使用测试模式,测试模式 key 只能用于测试模式。请参阅身份验证。
  • 适用于你所用语言的 SDK。Node.js SDK 要求 Node.js 20 或更高版本,Python SDK 要求 Python 3.9 或更高版本,Go SDK 要求 Go 1.22 或更高版本。cURL 示例无需 SDK。
webhook 示例也使用 standardwebhooks 包。使用 npm install standardwebhooks 安装它。

选择集成路径

Overlay 和 inline checkout 只能在网页中运行。在原生移动应用中,请在服务器上创建 checkout session,然后使用移动端 checkout SDK 打开其 checkout_url。 如果你希望 coding agent 为你构建此集成,请安装 Agent Plugin。

Checkout Sessions

创建安全的托管式结账体验。你可以在服务器上创建 session,然后将客户重定向到返回的 checkout_url。
每个 checkout_url 只能使用一次,并会在 24 小时后过期;如果传入 confirm: true,则会在 15 分钟后过期。使用 confirm: true 时,还必须提供所有必填字段。请为每个客户和每次付款尝试创建新的 session。

创建 Checkout Session

重定向到 Checkout

创建 session 后,将客户重定向到 checkout_url:
如需高级自定义,请参阅完整的 Checkout Sessions 指南和 API Reference。

处理错误

请求失败时,API 会返回 HTTP status code 和 JSON body,其中包含 code 和 message。请根据 code 而不是 message 分支处理错误。有关每个 code、其原因以及解决方法,请参阅错误代码。失败的付款会单独报告:付款的 status 为 failed,其 error_code 会提供原因,并且你会收到一个 payment.failed webhook。如需决定是否重试,请参阅处理付款失败。 payment link 是一个打开产品结账页面的 URL,因此无需编写代码即可收款。查询参数可以预填客户信息并控制结账表单。客户打开链接时,checkout 会将参数存储在 session 中,并将 URL 缩短为 session 参数,因此刷新页面后这些参数仍会保留。 static payment link 是你创建一次后可以多次分享的 URL。基础 URL 为:
添加查询参数来自定义 checkout:
integer
默认值:"1"
要购买的商品数量。
string
必填
Payment links 使用 redirect_url。Checkout Sessions API 使用 return_url 实现相同目的。付款后要重定向到的 URL。Dodo Payments 会将付款详情作为查询参数附加,例如 https://example.com/?payment_id=pay_ts2ySpzg07phGeBZqePbH&status=succeeded&email=customer%40example.com。如果产品会发放 license key,还会附加一个 license_key 参数,多个 key 之间以逗号分隔。
string
指定付款币种。默认为账单国家/地区的币种。
boolean
默认值:"true"
显示或隐藏币种选择器。
boolean
默认值:"true"
显示或隐藏折扣部分。设置为 false 可阻止客户输入优惠券代码。
number
固定收费金额,单位为主要币种单位,例如 12.5 表示 $12.50。仅适用于 Pay What You Want 产品;如果金额低于产品最低价格,则会被忽略。
paymentAmount 使用主要币种单位(12.5 表示 $12.50)。Checkout Sessions API 字段 product_cart[].amount 使用最小币种单位(1250 表示 $12.50)。请参阅动态定价。
string
自定义元数据字段,例如 metadata_orderId=123。

预填客户信息

将客户字段作为查询参数添加,以简化 checkout:
string
客户的全名(如果提供了 firstName 或 lastName,则会被忽略)。
string
客户的名。
string
客户的姓。
string
客户的电子邮件地址。
string
客户所在国家/地区(ISO 3166-1 alpha-2 code)。
string
街道地址。
string
城市。
string
州或省。
string
邮政编码或 ZIP code。

禁用表单字段

若要防止客户更改预填信息,请提供字段值,并将对应的 disable... flag 设置为 true,从而禁用该字段:
禁用字段可以防止意外更改,并确保数据一致性。

Dynamic Payment Links(已弃用)

POST /payments 和 POST /subscriptions endpoints 已弃用。对于新的集成,请改用 Checkout Sessions。
对于使用 dynamic payment links 的现有集成,请将 payment_link: true 传递给创建一次性付款或创建订阅以创建链接。以下示例会创建一次性付款链接。有关订阅,请参阅订阅集成指南。

Webhooks

Webhooks 会在付款成功或失败时通知你的服务器,以便你完成订单履行。

创建 Webhook Endpoint

在控制面板中前往 Developer → Webhooks,然后添加你的 endpoint URL。将 endpoint 的 signing secret 复制到 DODO_PAYMENTS_WEBHOOK_KEY 环境变量中。 以下是使用 Next.js 的示例:
app/api/webhooks/dodo/route.ts
我们的 webhook 实现遵循 Standard Webhooks 规范。

要监听的事件

在一次性付款流程中,至少监听以下事件:
始终根据 webhook 中的 payment.succeeded 完成订单履行,而不要根据浏览器重定向执行。客户关闭标签页可能导致重定向丢失,而 webhook 会持续重试,直到收到确认。
如果你销售带有 license key 的产品,还应处理 license_key.created。有关完整的事件列表,包括订阅、entitlement、credit、recovery 和 dunning 事件,请参阅 Webhook Event Guide。 如需完整的 Next.js 和 TypeScript 示例,请参阅 demo repository 及其在线部署。

币种和账单地址

如需使用特定币种收费,请在创建 checkout session 时传入 billing_currency 和 billing_address.country。如果省略这两个参数,Adaptive Currency 会根据客户的 IP 地址选择币种和国家/地区,该币种可能不是你希望收取的币种。 Pay What You Want 金额使用产品的基础币种,该币种必须是 USD、GBP 或 EUR。如需使用其他币种收取固定金额,请使用 Adaptive Currency,它会按照实时汇率转换基础价格;或者使用本地化定价,为每种币种设置固定价格。Localized Pricing 不适用于 Pay What You Want。

一键重复购买

如需使用已保存的 payment method 向回头客收费,请将其 payment_method_id 与 confirm: true 一起传入。仅当 confirm 为 true 时,才接受 payment_method_id;同时还必须传入现有客户的 customer_id。由于 confirm 为 true,因此还必须传入完整的 billing_address;如果 minimal_address 为 true,则只需传入 country 和 zipcode。该 session 会直接从已保存的 payment method 扣款,因此不会返回 checkout_url。使用 webhooks 了解付款是否成功。

相关页面

Checkout Sessions

包含高级自定义选项的完整指南。

Overlay Checkout

将 checkout 作为模态覆盖层嵌入页面。

Inline Checkout

将 checkout 直接嵌入页面布局。

Subscription Integration

设置周期性计费。

Webhook Event Guide

所有 webhook 事件的完整列表。

API Reference

Checkout Sessions API 文档。
最后修改于 2026年9月26日