async-stripe

A convenient, performant, and strongly-typed Rust library for the Stripe
HTTP API.

This library provides asynchronous bindings for the entire Stripe API
surface. It's generated directly from Stripe's official OpenAPI
specification and is updated weekly via CI to ensure it's always
up-to-date with the latest API changes.

✨ Key Features

• Complete & Current API Coverage: Generated from the official
  Stripe OpenAPI spec for maximum coverage and correctness. Our CI runs
  weekly to pull in the latest API definitions.

• Asynchronous & Performant: Built with async Rust for high
  performance. Uses miniserde for blazing-fast deserialization,
  keeping your binary sizes small and compile times fast.

• Modular by Design: The API is split into multiple crates
  (stripe-core, stripe-billing, etc.), so you only compile what you
  need, further reducing bloat.

• Ergonomic API: A fluent, builder-style API for constructing
  requests that is easy to use and discover.

• Flexible HTTP Clients: Supports tokio and async-std runtimes
  with native-tls and rustls backends.

⏰ 1.0 Alpha Notice: We are still expecting a few breaking changes before RC. We recommend using the Migration Guide when upgrading from 0.x versions.

🚀 Quick Start

Here's a quick example of how to create a new Stripe Customer.

1. Add dependencies to your Cargo.toml:

You'll need the main async-stripe crate for the client and a resource
crate for the APIs you want to use (e.g., stripe-core for customers).

[dependencies]
async-stripe = "1.0.0-alpha.2"
stripe-core = { version = "1.0.0-alpha.2", features = ["customer"] }
tokio = { version = "1", features = ["full"] }

2. Create a Customer:

The new API uses a builder pattern that flows naturally from request
creation to sending.

use stripe::Client;
use stripe_core::customer::CreateCustomer;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Initialize the client
    let secret_key = std::env::var("STRIPE_SECRET_KEY").expect("Missing STRIPE_SECRET_KEY in env");
    let client = Client::new(secret_key);

    // 2. Create a customer using the builder pattern
    let customer = CreateCustomer::new()
        .name("Alexander Lyon")
        .email("test@async-stripe.com")
        .description("A fake customer that is used to illustrate the examples in async-stripe.")
        .metadata([(String::from("async-stripe"), String::from("true"))])
        .send(&client)
        .await?;

    println!("Successfully created customer: {} ({})", customer.name.unwrap_or_default(), customer.id);

    Ok(())
}

How It Works

Code Generation

async-stripe achieves its vast API coverage and stays current by
generating Rust code directly from the official Stripe OpenAPI
specification. A CI job runs
weekly to fetch the latest spec, regenerate the code, and open a pull
request. This ensures that new Stripe features and updates are available
in the library almost immediately.

Performance: serde and miniserde

The Stripe API has a massive surface area, and the code generation
process creates a very large number of types. Using serde for both
serialization and deserialization in previous versions resulted in
excessive codegen size and long compile times. To solve this,
async-stripe now uses a hybrid approach:

• serde is used for serializing request parameters you send to
  Stripe. Its flexibility and rich feature set make it ideal for
  building complex requests.

• miniserde is used for deserializing API responses from
  Stripe. It's a minimal, high-performance JSON library that
  significantly reduces compile times and final binary size compared to
  a full serde dependency.

If you need to use serde::Deserialize on the Stripe response types
within your own application, you can enable the deserialize feature on
any of the stripe-* crates.

Modular Crate Structure

The Stripe API is extensive. To avoid long compile times and large
dependencies, async-stripe is split into several crates. You only need
to include the ones corresponding to the API sections you use.

API Area	Crate Name	Description
Client	async-stripe	The core client for making requests. Always required.
Core Resources	stripe-core	Customers, Charges, Payment Intents, Refunds, etc.
Payments	stripe-payment	Payment Methods, Payment Links, Sources.
Billing & Subscriptions	stripe-billing	Invoices, Subscriptions, Plans, Quotes.
Stripe Connect	stripe-connect	Accounts, Account Links, Transfers.
Fraud Detection	stripe-fraud	Radar, Reviews.
Checkout	stripe-checkout	Checkout Sessions.
Webhooks	stripe-webhook	Securely receive and deserialize webhook events.
Products & Pricing	stripe-product	Products, Prices, Coupons, Tax Rates.
Issuing	stripe-issuing	Card creation and management for Stripe Issuing.
Terminal	stripe-terminal	In-person payments with Stripe Terminal.
Treasury	stripe-treasury	Financial accounts and money movement.
Miscellaneous	stripe-misc	Tax, Identity, Reporting, Sigma, etc.

For a complete, up-to-date mapping of every API object to its crate
and feature flag, see the
crate_info.md
file in the repository. We are actively working on improving API
surface exploration. For now, you can explore the generated/
directory in the repository to see all available API crates and their
respective modules.

Usage Guide

1. Choose Your HTTP Client

The core async-stripe crate provides the client. You must enable a
feature flag to select your desired async runtime and TLS backend.

Feature Flag	Async Runtime	HTTP Client	TLS Backend
default-tls (Default)	tokio	hyper	native-tls
rustls-tls-webpki-roots	tokio	hyper	rustls (from webpki-roots)
rustls-tls-native	tokio	hyper	rustls (from native cert store)
async-std-surf	async-std	surf	native-tls
blocking	Sync (uses tokio internally)	hyper	Depends on active TLS feature

2. Add Resource Crates and Features

For each Stripe resource you want to interact with, add its crate and
enable the corresponding feature flag. For example, to use Customer
and Charge objects:

# Cargo.toml
[dependencies]
# ...
stripe-core = { version = "...", features = ["customer", "charge"] }

3. Pagination

Listing resources is now more ergonomic. You can call .paginate()
directly on a List* request struct to get a stream of results.

use stripe_core::customer::ListCustomer;
use futures_util::TryStreamExt;

# async fn run(client: &stripe::Client) -> Result<(), stripe::StripeError> {
let mut stream = ListCustomer::new().paginate().stream(client);
while let Some(customer) = stream.try_next().await? {
    println!("Got customer: {}", customer.id);
}
# Ok(())
# }

4. Handling Webhooks

Webhook handling is now isolated in the stripe-webhook crate and the
API is much simpler. You can now match directly on the event object
type.

use stripe_webhook::{Event, EventObject, Webhook};

fn handle_webhook(payload: &str, sig: &str, secret: &str) {
    let event = Webhook::construct_event(payload, sig, secret).unwrap();
    match event.data.object {
        EventObject::CheckoutSessionCompleted(session) => {
            println!("Received checkout session completed webhook with id: {:?}", session.id);
        }
        EventObject::AccountUpdated(account) => {
            println!("Received account updated webhook for account: {:?}", account.id);
        }
        _ => println!("Unknown event encountered in webhook: {:?}", event.type_),
    }
}

Project Status

This library is actively maintained. The code is regenerated weekly to
ensure it never falls behind the official Stripe API.

We are working on setting up fully automated releases to crates.io to
coincide with the weekly updates. This will ensure you can depend on the
latest Stripe features as soon as they are available.

Contributing

Contributions are welcome! Please see
CONTRIBUTING.md
for details on how to get started, run tests, and contribute to the code
generation process.

License

This project is licensed under either of:

• Apache License, Version 2.0
  (LICENSE-APACHE
  or http://www.apache.org/licenses/LICENSE-2.0)

• MIT license
  (LICENSE-MIT or
  http://opensource.org/licenses/MIT)

This project began as a fork of
stripe-rs, and we are
incredibly grateful for their foundational work.