Rust

Rust SDKを使用すると、async RustアプリケーションからDodo Payments REST APIに型安全にアクセスできます。Tokioとreqwest上に構築され、型付きのrequestおよびresponse structを使用し、ページ分割された結果をストリーミングし、失敗したrequestを再試行します。

インストール

Cargoを使ってSDKをプロジェクトに追加します：

cargo add dodopayments

または、手動で追加します：

[dependencies]
dodopayments = "1.119.0"
tokio = { version = "1", features = ["full"] }
serde_json = "1"
futures = "0.3" # required for streaming paginated results

SDKにはRust 1.75以降が必要です。

クイックスタート

Client::from_env()はDODO_PAYMENTS_API_KEY環境変数からAPI keyを読み取ります。clientを作成してから、checkout sessionを作成します。

use dodopayments::Client;

#[tokio::main]
async fn main() -> dodopayments::Result<()> {
    let client = Client::from_env()?;

    let result = client
        .checkout_sessions()
        .create()
        .body(dodopayments::models::CheckoutSessionsCreateParams {
            product_cart: Some(vec![dodopayments::models::ProductItemReq {
                product_id: "pdt_123".to_string(),
                quantity: 1,
                addons: None,
                amount: None,
                credit_entitlements: None,
            }]),
            ..Default::default()
        })
        .await?;

    println!("{result:?}");
    Ok(())
}

DODO_PAYMENTS_API_KEYが設定されていない場合、Client::from_env()はError::Configを返します。別のenvironmentを選択しない限り、clientはlive modeに接続します。詳しくはEnvironmentsを参照してください。test modeのAPI keyはtest modeでのみ使用できます。

API keyは環境変数またはsecrets managerで管理してください。ソースコードに直接記述しないでください。

主な機能

Async First

Tokioとreqwest上に構築され、すべてのrequestでasync/awaitを使用します。

Strong Typing

compile-time check用の型付きrequestおよびresponse struct。

Auto-Pagination

すべてのページのitemをstreamすることも、1ページずつ移動することもできます。

Configurable

各clientのenvironment、base URL、timeout、retry countを設定できます。

Configuration

Environment Variables

Client::from_env()はDODO_PAYMENTS_API_KEYからAPI keyを読み取ります。DODO_PAYMENTS_BASE_URLを設定しない限り、live modeのURLを使用します。

export DODO_PAYMENTS_API_KEY="your_api_key"
export DODO_PAYMENTS_BASE_URL="https://test.dodopayments.com" # optional

Rust SDKはDODO_PAYMENTS_WEBHOOK_KEYを読み取らず、webhook signatureを検証するmethodもありません。検証するにはWebhooksを参照してください。 clientを明示的に設定することもできます。Client::newはResultを返すため、dodopayments::Resultを返すfunction内で?を使ってunwrapします。

use dodopayments::{Client, ClientConfig};

#[tokio::main]
async fn main() -> dodopayments::Result<()> {
    let client = Client::new(
        ClientConfig::new("https://live.dodopayments.com").with_api_key("My API Key"),
    )?;
    println!("{}", client.base_url());
    Ok(())
}

Environments

SDKには2つのenvironmentがあります。

Name	Base URL
`live_mode`	`https://live.dodopayments.com`
`test_mode`	`https://test.dodopayments.com`

デフォルトのbase URLはhttps://live.dodopayments.comです。別のenvironmentを選択するには、ハードコードされたURLの代わりにEnvironment enumを使用します。

use dodopayments::{Client, ClientConfig, Environment};

let client = Client::new(
    ClientConfig::from_environment(Environment::TestMode).with_api_key("My API Key"),
)?;

from_env()でDODO_PAYMENTS_API_KEYからAPI keyを引き続き読み取りながら、別のenvironmentを対象にするには、configでenvironmentを上書きします。

use dodopayments::{Client, ClientConfig, Environment};

let client = Client::new(ClientConfig::from_env()?.with_environment(Environment::TestMode))?;

Timeouts

デフォルトのrequest timeoutは30秒です。clientで上書きするにはwith_timeoutを使用します。

use std::time::Duration;
use dodopayments::{Client, ClientConfig};

let client = Client::new(
    ClientConfig::new("https://live.dodopayments.com")
        .with_api_key("My API Key")
        .with_timeout(Duration::from_secs(60)),
)?;

clientはconnection errorと、status 408、409、429、または500以上のresponseを再試行します。デフォルトでは指数バックオフを使用して2回再試行し、APIからRetry-After headerが送信された場合はその値に従って待機します。retry countを変更するにはClientConfigでwith_max_retriesを呼び出します。たとえば.with_max_retries(0)にすると再試行を無効にできます。

一般的な操作

このセクションの例では、Quick Startのclientを使用します。

Checkout Sessionの作成

return URLを指定してcheckout sessionを作成します。

let session = client
    .checkout_sessions()
    .create()
    .body(dodopayments::models::CheckoutSessionsCreateParams {
        product_cart: Some(vec![dodopayments::models::ProductItemReq {
            product_id: "pdt_123".to_string(),
            quantity: 1,
            addons: None,
            amount: None,
            credit_entitlements: None,
        }]),
        return_url: Some("https://yourdomain.com/return".to_string()),
        ..Default::default()
    })
    .await?;

println!("{session:?}");

customerをsession.checkout_urlにredirectします。各checkout URLは1回のみ使用でき、24時間後に期限切れになります。すべてのsession optionについてはCheckout Sessionsを参照してください。

Customerの管理

email addressとnameを指定してcustomerを作成し、IDで取得します。

// Create a customer
let customer = client
    .customers()
    .create()
    .body(dodopayments::models::CustomersCreateParams {
        email: Some("customer@example.com".to_string()),
        name: Some("John Doe".to_string()),
        ..Default::default()
    })
    .await?;

// Retrieve a customer
let customer = client
    .customers()
    .retrieve()
    .customer_id("cus_123")
    .await?;

println!("{customer:?}");

Subscriptionの処理

既存のcustomerのsubscriptionを作成します。

POST /subscriptions（SDKのsubscriptions().create() method）はdeprecatedです。既存のintegrationでは引き続き動作しますが、新しいintegrationではCheckout Sessionを通じてsubscriptionを作成してください。

let subscription = client
    .subscriptions()
    .create()
    .body(dodopayments::models::SubscriptionsCreateParams {
        billing: Some(Box::new(dodopayments::models::BillingAddress {
            country: Box::new(dodopayments::models::CountryCode::Us),
            city: Some("San Francisco".to_string()),
            state: Some("CA".to_string()),
            street: Some("1 Market St".to_string()),
            zipcode: Some("94105".to_string()),
        })),
        customer: Some(Box::new(
            dodopayments::models::CustomerRequest::AttachExistingCustomer(Box::new(
                dodopayments::models::AttachExistingCustomer {
                    customer_id: "cus_123".to_string(),
                },
            )),
        )),
        product_id: Some("pdt_456".to_string()),
        quantity: Some(1),
        ..Default::default()
    })
    .await?;

println!("{subscription:?}");

billingに必要なのはcountryだけです。これはCountryCode::UsなどのCountryCode enum variantです。customerはCustomerRequest enumです。既存のcustomerにはAttachExistingCustomerを渡し、customerを作成するにはNewCustomerを渡します。on-demand subscriptionに課金するには、SubscriptionsChargeParams bodyでclient.subscriptions().charge().subscription_id(...)を呼び出します。product_priceなどのamount fieldは最小通貨単位で指定します（たとえば2500は$25.00です）。

Usage-Based Billing

Usage Eventの取り込み

customerのusage eventを送信します。

let response = client
    .usage_events()
    .ingest()
    .body(dodopayments::models::UsageEventsIngestParams {
        events: Some(vec![dodopayments::models::EventInput {
            customer_id: "cus_abc123".to_string(),
            event_id: "api_call_12345".to_string(),
            event_name: "api_request".to_string(),
            metadata: None,
            timestamp: None,
        }]),
        ..Default::default()
    })
    .await?;

println!("{response:?}");

event_idはidempotency keyです。そのため、各eventに一意の値を指定してください。timestampがNoneの場合、eventには現在時刻が使用されます。

Usage Eventの一覧表示

customerとevent nameでfilterしたeventを一覧表示します。filterはJSON query objectに指定します。

let events = client
    .usage_events()
    .list()
    .query(serde_json::json!({
        "customer_id": "cus_abc123",
        "event_name": "api_request",
    }))
    .await?;

for event in &events.items {
    println!("{event:?}");
}

Pagination

List endpointは、items fieldに現在のページのresultを格納した型付きpageを返します。すべてのページのitemをstreamするには、into_streamを呼び出します。

use futures::StreamExt;

let mut items = Box::pin(
    client
        .payments()
        .list()
        .query(serde_json::json!({}))
        .await?
        .into_stream(),
);

while let Some(item) = items.next().await {
    let item = item?;
    println!("{item:?}");
}

1ページずつ移動するにはget_next_pageを呼び出します。最後のページの後はNoneを返します。

let mut page = client
    .payments()
    .list()
    .query(serde_json::json!({}))
    .await?;

loop {
    for item in &page.items {
        println!("{item:?}");
    }
    match page.get_next_page().await? {
        Some(next) => page = next,
        None => break,
    }
}

Error Handling

すべてのmethodはdodopayments::Result<T>を返します。失敗はdodopayments::Error enumのvariantです。ApiはAPIからのerror status、Httpはtransport error、Jsonはserialization error、Configはconfiguration error、MissingPathParamまたはMissingBodyは不完全なrequestを表します。これにmatchして、API errorとtransport errorを個別に処理します。

let result = client
    .checkout_sessions()
    .create()
    .body(dodopayments::models::CheckoutSessionsCreateParams {
        product_cart: Some(vec![dodopayments::models::ProductItemReq {
            product_id: "pdt_123".to_string(),
            quantity: 1,
            addons: None,
            amount: None,
            credit_entitlements: None,
        }]),
        ..Default::default()
    })
    .await;

match result {
    Ok(value) => println!("{value:?}"),
    Err(dodopayments::Error::Api { status, message }) => {
        eprintln!("API returned {status}: {message}");
    }
    Err(err) => eprintln!("request failed: {err}"),
}

未ドキュメントのEndpoint

型付きmethodがないendpointを呼び出すには、低レベルのrequest builderを使用します。authenticationとbase URLが適用されます。reqwest::Methodを指定するには、dependenciesにreqwest 0.12を追加します。

let response = client
    .request(reqwest::Method::GET, "/some/path")
    .send()
    .await?;

Resources

GitHub Repository

ソースコード、release、すべてのmethod list。

Crates.io

公開済みcrateとそのversion。

API Reference

すべてのendpoint、parameter、response。

Discord Community

質問したり、他のdeveloperと交流したりできます。

Support

Rust SDKについてサポートが必要な場合：

Discord：community serverに参加して、リアルタイムでサポートを受けてください。
Email：support@dodopayments.comまでお問い合わせください。
GitHub：repositoryでissueを作成してください。

Contributing

contributionするには、contributing guidelinesをお読みください。

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

インストール

クイックスタート

主な機能

Async First

Strong Typing

Auto-Pagination

Configurable

Configuration

Environment Variables

Environments

Timeouts

一般的な操作

Checkout Sessionの作成

Customerの管理

Subscriptionの処理

Usage-Based Billing

Usage Eventの取り込み

Usage Eventの一覧表示

Error Handling

未ドキュメントのEndpoint

Resources

GitHub Repository

Crates.io

API Reference

Discord Community

Support

Contributing

​インストール

​クイックスタート

​主な機能

Async First

Strong Typing

Auto-Pagination

Configurable

​Configuration

​Environment Variables

​Environments

​Timeouts

​一般的な操作

​Checkout Sessionの作成

​Customerの管理

​Subscriptionの処理

​Usage-Based Billing

​Usage Eventの取り込み

​Usage Eventの一覧表示

​Pagination

​Error Handling

​未ドキュメントのEndpoint

​Resources

GitHub Repository

Crates.io

API Reference

Discord Community

​Support

​Contributing

インストール

クイックスタート

主な機能

Configuration

Environment Variables

Environments

Timeouts

一般的な操作

Checkout Sessionの作成

Customerの管理

Subscriptionの処理

Usage-Based Billing

Usage Eventの取り込み

Usage Eventの一覧表示

Pagination

Error Handling

未ドキュメントのEndpoint

Resources

Support

Contributing