async-stripe

Stripe API responses often return related objects as IDs by default. To retrieve the full object, you must pass the field name in the expand parameter during the request. The library handles these fields using the Expandable<T> type.

Accessing Data

• Always get the ID: You can always call .id() on an Expandable<T> field to get the ID string, whether the field was expanded or not.
• Access the full object: If the field was expanded, use .as_object() to get a reference to the full object or .into_object() to take ownership.

Available Methods on Expandable<T>

• .id(): Returns the ID (works regardless of expansion status).
• .is_object(): Returns true if the field contains the full object.
• .as_object(): Returns a reference to the object if available.
• .into_object(): Takes ownership of the object if available.
• .into_id(): Takes ownership of the ID.

use stripe::{Client, Charge};

let client = Client::new(secret_key);

// 1. Always safe to get ID
let charge = Charge::retrieve(&client, &charge_id, &[]).await?;
let customer_id = charge.customer.id();

// 2. Requesting expansion
let charge = Charge::retrieve(&client, &charge_id, &["customer"]).await?;

// 3. Accessing expanded object
if let Some(customer) = charge.customer.as_object() {
    println!("Customer email: {:?}", customer.email);
} else {
    println!("Customer was not expanded");
}

To keep compile times low and binary sizes small, async-stripe is split into specialized crates. You must include the core client and then add the specific crates for the Stripe API areas you intend to use.

• async-stripe: The core client. Always required.
• stripe-core: Core resources like Customers, Charges, Payment Intents, and Refunds.
• stripe-payment: Payment Methods, Payment Links, and Sources.
• stripe-billing: Invoices, Subscriptions, Plans, and Quotes.
• stripe-connect: Accounts, Account Links, and Transfers.
• stripe-fraud: Radar and Reviews.
• stripe-checkout: Checkout Sessions.
• stripe-webhook: Securely receive and deserialize webhook events.
• stripe-product: Products, Prices, Coupons, and Tax Rates.
• stripe-issuing: Card creation and management.
• stripe-terminal: In-person payments.
• stripe-treasury: Financial accounts and money movement.
• stripe-misc: Tax, Identity, Reporting, Sigma, etc.

To use multiple resources from one crate, enable them via features, e.g., stripe-core = { version = "...", features = ["customer", "charge"] }.

To ensure reliable and secure webhook processing, follow these patterns:

1. Return 200 OK quickly

Stripe expects a response within a few seconds. If your processing logic is heavy, spawn a background task (e.g., using tokio::spawn) and return StatusCode::OK immediately.

2. Handle Idempotency

Stripe may send the same event multiple times. Use the event.id to track processed events in your database to avoid duplicate processing.

3. Security

• Use HTTPS in production.
• Store your webhook signing secret in environment variables.
• Always verify signatures using construct_event() in production.

// Pattern: Return 200 quickly by spawning a task
async fn handle_webhook(StripeEvent(event): StripeEvent) -> StatusCode {
    tokio::spawn(async move {
        process_event(event).await;
    });

    StatusCode::OK
}

// Pattern: Handle idempotency using event.id
async fn handle_webhook(StripeEvent(event): StripeEvent) {
    if already_processed(&event.id).await {
        return; // Skip duplicate
    }

    process_event(event).await;
    mark_as_processed(&event.id).await;
}

The RequestStrategy API allows you to handle network failures and prevent duplicate charges using idempotency keys and retries. The library automatically respects the Stripe-Should-Retry response header or falls back to retrying transient status codes like 409, 424, 429, and 5xx.

Available strategies:

• Once: No retries. Use this if you are managing retries manually.
• Idempotent(key): Executes the request once using a specific, user-provided IdempotencyKey. Use this for critical flows where you need control over the key.
• Retry(n): Retries the request up to n total times using a random UUID as the idempotency key. Best for general retry logic without backoff.
• ExponentialBackoff(n): Retries the request up to n total times using exponential backoff. Recommended for production to handle transient failures gracefully.

// Example of strategy options
let strategy = RequestStrategy::ExponentialBackoff(3);