安装
使用 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 中使用。
核心功能
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:
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 覆盖该设置:
Retry-After header 时,client 会等待该 header 指定的时间。要更改 retry count,请在 ClientConfig 上调用 with_max_retries,例如使用 .with_max_retries(0) 来关闭重试。
常见操作
本节中的示例使用 Quick Start 中的client。
创建 Checkout Session
使用 return URL 创建 checkout session:session.checkout_url。每个 checkout URL 只能使用一次,并会在 24 小时后过期。有关每个 session option 的信息,请参阅 Checkout Sessions。
管理 Customers
使用 email address 和 name 创建 customer,然后通过 ID 获取它:处理 Subscriptions
为现有 customer 创建 subscription。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 方面的帮助:- Discord:加入社区服务器获取实时帮助。
- Email:联系 support@dodopayments.com。
- GitHub:在repository中提交 issue。