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。
standardwebhooks 包。使用 npm install standardwebhooks 安装它。
选择集成路径
Overlay 和 inline checkout 只能在网页中运行。在原生移动应用中,请在服务器上创建 checkout session,然后使用移动端 checkout SDK 打开其
checkout_url。
如果你希望 coding agent 为你构建此集成,请安装 Agent Plugin。
Checkout Sessions
创建安全的托管式结账体验。你可以在服务器上创建 session,然后将客户重定向到返回的checkout_url。
创建 Checkout Session
- Node.js SDK
- Python SDK
- cURL
重定向到 Checkout
创建 session 后,将客户重定向到checkout_url:
处理错误
请求失败时,API 会返回 HTTP status code 和 JSON body,其中包含code 和 message。请根据 code 而不是 message 分支处理错误。有关每个 code、其原因以及解决方法,请参阅错误代码。失败的付款会单独报告:付款的 status 为 failed,其 error_code 会提供原因,并且你会收到一个 payment.failed webhook。如需决定是否重试,请参阅处理付款失败。
Payment Links
payment link 是一个打开产品结账页面的 URL,因此无需编写代码即可收款。查询参数可以预填客户信息并控制结账表单。客户打开链接时,checkout 会将参数存储在 session 中,并将 URL 缩短为session 参数,因此刷新页面后这些参数仍会保留。
Static Payment Links
static payment link 是你创建一次后可以多次分享的 URL。基础 URL 为: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 产品;如果金额低于产品最低价格,则会被忽略。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,从而禁用该字段:
Static Payment Link 示例
Dynamic Payment Links(已弃用)
对于使用 dynamic payment links 的现有集成,请将payment_link: true 传递给创建一次性付款或创建订阅以创建链接。以下示例会创建一次性付款链接。有关订阅,请参阅订阅集成指南。
- Node.js SDK
- Python SDK
- Go SDK
Webhooks
Webhooks 会在付款成功或失败时通知你的服务器,以便你完成订单履行。创建 Webhook Endpoint
在控制面板中前往 Developer → Webhooks,然后添加你的 endpoint URL。将 endpoint 的 signing secret 复制到DODO_PAYMENTS_WEBHOOK_KEY 环境变量中。
以下是使用 Next.js 的示例:
app/api/webhooks/dodo/route.ts
要监听的事件
在一次性付款流程中,至少监听以下事件:
如果你销售带有 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 文档。