Rust

Rust SDK는 async Rust 애플리케이션에 Dodo Payments REST API에 대한 타입이 지정된 액세스를 제공합니다. Tokio와 reqwest를 기반으로 구축되었으며, 타입이 지정된 request 및 response struct를 사용하고, 페이지로 구분된 결과를 stream하며, 실패한 request를 retry합니다.

설치

SDK를 Cargo로 프로젝트에 추가하세요:

cargo add dodopayments

또는 수동으로 이를 Cargo.toml에 추가하세요:

[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를 반환합니다. Environments에 설명된 것처럼 다른 environment를 선택하지 않으면 client는 live mode에 연결됩니다. test mode API key는 test mode에서만 작동합니다.

API key는 environment variable 또는 secrets manager에 보관하세요. source code에 직접 hardcode하지 마세요.

핵심 기능

Async First

Tokio와 reqwest를 기반으로 구축되었으며, 모든 request에 async/await를 사용합니다.

Strong Typing

compile-time check를 위한 타입이 지정된 request 및 response struct입니다.

Auto-Pagination

모든 page의 항목을 stream하거나 한 번에 한 page씩 이동할 수 있습니다.

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에는 두 가지 environment가 있습니다:

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

기본 base URL은 https://live.dodopayments.com입니다. hard-coded URL 대신 Environment enum을 사용하여 다른 environment를 선택하세요:

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초입니다. with_timeout를 사용하여 client의 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를 retry합니다. 기본적으로 exponential backoff를 사용하여 두 번 retry하며, API가 Retry-After header를 전송하면 해당 값을 기다립니다. retry count를 변경하려면 ClientConfig에서 with_max_retries를 호출하세요. 예를 들어 .with_max_retries(0)는 retry를 비활성화합니다.

일반적인 작업

이 section의 예제에서는 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은 한 번만 작동하며 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).

사용량 기반 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는 타입이 지정된 page를 반환하며, items field에 현재 page의 결과가 저장됩니다. 모든 page의 항목을 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:?}");
}

한 번에 한 page씩 이동하려면 get_next_page를 호출하세요. 마지막 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를 나타냅니다. API error와 transport error를 별도로 처리하려면 이를 match하세요:

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를 호출하려면 low-level request builder를 사용하세요. 이 builder는 authentication과 base URL을 적용합니다. reqwest::Method의 이름을 지정하려면 dependency에 reqwest 0.12를 추가하세요:

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

리소스

GitHub Repository

source code, release 및 전체 method 목록입니다.

Crates.io

publish된 crate와 해당 version입니다.

API Reference

모든 endpoint, parameter 및 response입니다.

Discord Community

질문을 하고 다른 developer와 소통할 수 있습니다.

지원

Rust SDK에 대한 지원이 필요하면 다음을 이용하세요:

Discord: 실시간 지원을 받으려면 community server에 참여하세요.
Email: support@dodopayments.com으로 문의하세요.
GitHub: repository에 issue를 등록하세요.

기여

기여하려면 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 처리

사용량 기반 Billing

Usage Event 수집

Usage Event 나열

Error Handling

문서화되지 않은 Endpoint

리소스

GitHub Repository

Crates.io

API Reference

Discord Community

지원

기여

​설치

​빠른 시작

​핵심 기능

Async First

Strong Typing

Auto-Pagination

Configurable

​Configuration

​Environment Variables

​Environments

​Timeouts

​일반적인 작업

​Checkout Session 생성

​Customer 관리

​Subscription 처리

​사용량 기반 Billing

​Usage Event 수집

​Usage Event 나열

​Pagination

​Error Handling

​문서화되지 않은 Endpoint

​리소스

GitHub Repository

Crates.io

API Reference

Discord Community

​지원

​기여

설치

빠른 시작

핵심 기능

Configuration

Environment Variables

Environments

Timeouts

일반적인 작업

Checkout Session 생성

Customer 관리

Subscription 처리

사용량 기반 Billing

Usage Event 수집

Usage Event 나열

Pagination

Error Handling

문서화되지 않은 Endpoint

리소스

지원

기여