Skip to main content
Rust SDK 为 async Rust 应用提供了对 Dodo Payments REST API 的类型化访问。它基于 Tokio 和 reqwest 构建,使用类型化的 request 和 response structs,支持流式处理分页结果,并会重试失败的 requests。

安装

使用 Cargo 将 SDK 添加到您的项目中:
或者手动将其添加到您的 Cargo.toml 中:
SDK 要求 Rust 1.75 或更高版本。

快速开始

Client::from_env() 会从 DODO_PAYMENTS_API_KEY 环境变量中读取 API key。创建 client,然后创建 checkout session:
如果未设置 DODO_PAYMENTS_API_KEY,Client::from_env() 会返回 Error::Config。除非选择其他 environment,否则 client 会连接到 live mode,如Environments所示。test mode API key 只能在 test mode 中使用。
请将 API keys 保存在环境变量或 secrets manager 中。切勿将其硬编码到源代码中。

核心功能

Async First

基于 Tokio 和 reqwest 构建,为每个 request 提供 async/await。

Strong Typing

类型化的 request 和 response structs,可在 compile time 进行检查。

Auto-Pagination

流式处理所有页面中的每个 item,或一次移动一页。

Configurable

为每个 client 设置 environment、base URL、timeout 和 retry count。

配置

环境变量

Client::from_env() 会从 DODO_PAYMENTS_API_KEY 中读取 API key。除非设置 DODO_PAYMENTS_BASE_URL,否则它会使用 live mode URL:
Rust SDK 不会读取 DODO_PAYMENTS_WEBHOOK_KEY,也没有用于验证 webhook signatures 的 method。要验证它们,请参阅 Webhooks。 你也可以显式配置 client。Client::new 会返回一个 Result,因此请在返回 dodopayments::Result 的 function 中使用 ? 对其进行 unwrap:

Environments

SDK 有两种 environment: 默认 base URL 为 https://live.dodopayments.com。要选择其他 environment,请使用 Environment enum,而不是硬编码 URL:
如果要继续从 DODO_PAYMENTS_API_KEY 中读取 API key,并通过 from_env() 指定另一个 environment,请在 config 上覆盖 environment:

超时

默认 request timeout 为 30 秒。使用 with_timeout 为 client 覆盖该设置:
client 会重试 connection errors,以及 status 为 408、409、429 或 500 及以上的 responses。默认重试两次,并使用 exponential backoff;当 API 发送 Retry-After header 时,client 会等待该 header 指定的时间。要更改 retry count,请在 ClientConfig 上调用 with_max_retries,例如使用 .with_max_retries(0) 来关闭重试。

常见操作

本节中的示例使用 Quick Start 中的 client。

创建 Checkout Session

使用 return URL 创建 checkout session:
将 customer 重定向到 session.checkout_url。每个 checkout URL 只能使用一次,并会在 24 小时后过期。有关每个 session option 的信息,请参阅 Checkout Sessions。

管理 Customers

使用 email address 和 name 创建 customer,然后通过 ID 获取它:

处理 Subscriptions

为现有 customer 创建 subscription。
POST /subscriptions(SDK 的 subscriptions().create() method)已被 弃用。它仍适用于现有 integrations,但新的 integrations 应通过 Checkout Session 创建 subscriptions。
billing 只需要 country,即 CountryCode::Us 等 CountryCode enum variant。customer 是一个 CustomerRequest enum:对于现有 customer,传入 AttachExistingCustomer;或者传入 NewCustomer 来创建 customer。要为 on-demand subscription 收费,请使用 client.subscriptions().charge().subscription_id(...),并传入 SubscriptionsChargeParams body。金额字段(例如 product_price)使用货币的最小单位表示(例如,2500 表示 $25.00)。

基于用量的计费

写入 Usage Events

为 customer 发送 usage events:
event_id 是 idempotency key,因此请为每个 event 提供唯一值。如果 timestamp 为 None,则 event 会使用当前时间。

列出 Usage Events

列出按 customer 和 event name 过滤的 events。过滤条件位于 JSON query object 中:

分页

List endpoints 会返回一个类型化 page,其 items field 保存当前页面的 results。要流式处理所有页面中的每个 item,请调用 into_stream:
要一次移动一页,请调用 get_next_page。最后一页之后,它会返回 None:

错误处理

每个 method 都会返回一个 dodopayments::Result<T>。失败结果是 dodopayments::Error enum 的 variants:Api 表示 API 返回的 error status,Http 表示 transport errors,Json 表示 serialization errors,Config 表示 configuration errors,MissingPathParam 或 MissingBody 表示 requests 不完整。对其进行 match,以便分别处理 API errors 和 transport errors:

未文档化的 Endpoints

要调用没有类型化 method 的 endpoint,请使用底层的 request builder。它会应用 authentication 和 base URL。要命名 reqwest::Method,请将 reqwest 0.12 添加到 dependencies 中:

资源

GitHub Repository

源代码、releases 和完整的 method 列表。

Crates.io

已发布的 crate 及其 versions。

API Reference

每个 endpoint、parameter 和 response。

Discord Community

提出问题,并与其他 developers 交流。

支持

如需 Rust SDK 方面的帮助:

参与贡献

如需参与贡献,请阅读贡献指南。
最后修改于 2026年9月26日