Skip to main content
Rust SDK cung cấp cho các ứng dụng Rust async quyền truy cập có kiểu dữ liệu vào REST API của Dodo Payments. SDK được xây dựng trên Tokio và reqwest, sử dụng các struct request và response có kiểu, stream kết quả phân trang và thử lại các request không thành công.

Cài đặt

Thêm SDK vào dự án của bạn với Cargo:
Hoặc thêm nó vào Cargo.toml của bạn thủ công:
SDK yêu cầu Rust 1.75 trở lên.

Bắt đầu nhanh

Client::from_env() đọc API key của bạn từ biến môi trường DODO_PAYMENTS_API_KEY. Tạo một client, sau đó tạo một checkout session:
Nếu DODO_PAYMENTS_API_KEY chưa được thiết lập, Client::from_env() trả về một Error::Config. Client kết nối với live mode trừ khi bạn chọn environment khác, như được trình bày trong Environments. Test mode API key chỉ hoạt động trong test mode.
Lưu API key trong biến môi trường hoặc trình quản lý secrets. Không bao giờ hardcode chúng trong source code.

Tính năng cốt lõi

Async First

Được xây dựng trên Tokio và reqwest, với async/await cho mọi request.

Strong Typing

Các struct request và response có kiểu để kiểm tra tại thời điểm biên dịch.

Auto-Pagination

Stream mọi item qua các trang hoặc chuyển từng trang một.

Configurable

Thiết lập environment, base URL, timeout và số lần retry cho mỗi client.

Cấu hình

Biến môi trường

Client::from_env() đọc API key của bạn từ DODO_PAYMENTS_API_KEY. SDK sử dụng URL của live mode trừ khi bạn thiết lập DODO_PAYMENTS_BASE_URL:
Rust SDK không đọc DODO_PAYMENTS_WEBHOOK_KEY và không có method để xác minh chữ ký webhook. Để xác minh chúng, hãy làm theo Webhooks. Bạn cũng có thể cấu hình client một cách tường minh. Client::new trả về một Result, vì vậy hãy unwrap nó bằng ? bên trong một function trả về dodopayments::Result:

Environments

SDK có hai environment: Base URL mặc định là https://live.dodopayments.com. Để chọn environment khác, hãy sử dụng enum Environment thay vì URL hard-code:
Để tiếp tục đọc API key từ DODO_PAYMENTS_API_KEY bằng from_env() nhưng nhắm đến environment khác, hãy ghi đè environment trong config:

Timeouts

Timeout request mặc định là 30 giây. Ghi đè timeout cho một client bằng with_timeout:
Client thử lại các lỗi kết nối và response có status 408, 409, 429 hoặc 500 trở lên. Theo mặc định, client thử lại hai lần với exponential backoff và chờ header Retry-After khi API gửi header này. Để thay đổi số lần retry, hãy gọi with_max_retries trên ClientConfig, ví dụ .with_max_retries(0) để tắt retry.

Các thao tác phổ biến

Các ví dụ trong phần này sử dụng client từ Quick Start.

Tạo Checkout Session

Tạo một checkout session với return URL:
Chuyển hướng khách hàng đến session.checkout_url. Mỗi checkout URL chỉ hoạt động một lần và hết hạn sau 24 giờ. Để xem mọi tùy chọn session, hãy xem Checkout Sessions.

Quản lý khách hàng

Tạo một khách hàng với địa chỉ email và tên, sau đó truy xuất khách hàng bằng ID:

Xử lý Subscriptions

Tạo một subscription cho khách hàng hiện có.
POST /subscriptions (method subscriptions().create() của SDK) đã deprecated. Method này vẫn hoạt động cho các integration hiện có, nhưng các integration mới nên tạo subscription thông qua một Checkout Session.
billing chỉ yêu cầu country, một biến thể enum CountryCode chẳng hạn như CountryCode::Us. customer là một enum CustomerRequest: truyền AttachExistingCustomer cho khách hàng hiện có hoặc NewCustomer để tạo khách hàng mới. Để tính phí một on-demand subscription, hãy gọi client.subscriptions().charge().subscription_id(...) với body SubscriptionsChargeParams. Các field amount như product_price được tính theo đơn vị tiền tệ nhỏ nhất (ví dụ, 2500 là $25.00).

Tính phí theo mức sử dụng

Tiếp nhận Usage Events

Gửi usage events cho một khách hàng:
event_id là idempotency key, vì vậy hãy cung cấp cho mỗi event một giá trị duy nhất. Nếu timestamp là None, event sử dụng thời gian hiện tại.

Liệt kê Usage Events

Liệt kê các event được lọc theo khách hàng và tên event. Các bộ lọc nằm trong một JSON query object:

Phân trang

Các endpoint list trả về một page có kiểu, trong đó field items chứa trang kết quả hiện tại. Để stream mọi item qua tất cả các trang, hãy gọi into_stream:
Để chuyển từng trang một, hãy gọi get_next_page. Method này trả về None sau trang cuối cùng:

Xử lý lỗi

Mọi method đều trả về một dodopayments::Result<T>. Các lỗi là những variant của enum dodopayments::Error: Api cho lỗi status từ API, Http cho lỗi transport, Json cho lỗi serialization, Config cho lỗi configuration và MissingPathParam hoặc MissingBody cho request chưa hoàn chỉnh. Hãy match trên giá trị này để xử lý lỗi API riêng với lỗi transport:

Endpoint chưa được tài liệu hóa

Để gọi một endpoint không có method có kiểu, hãy sử dụng low-level builder request. Builder này áp dụng authentication và base URL. Để đặt tên reqwest::Method, hãy thêm reqwest 0.12 vào dependencies:

Tài nguyên

GitHub Repository

Source code, các bản phát hành và danh sách method đầy đủ.

Crates.io

Crate đã phát hành và các phiên bản của crate.

API Reference

Mọi endpoint, parameter và response.

Discord Community

Đặt câu hỏi và trao đổi với các developer khác.

Hỗ trợ

Để được hỗ trợ về Rust SDK:

Đóng góp

Để đóng góp, hãy đọc hướng dẫn đóng góp.
Lần sửa đổi cuối 26 tháng 9, 2026