Stripe Python Library: Official SDK for the Stripe API

Accessing the Stripe API with Python

Stripe Python Library is a Python package that gives applications access to the Stripe API without hand-rolling HTTP requests. It ships pre-defined classes for resources, like customers and charges, that initialize dynamically from whatever the API returns, which keeps it compatible across many Stripe API versions per the README. Configure it with a secret key from your Stripe Dashboard, then call resource methods through `StripeClient`.

Key Capabilities of the SDK

• ✓A `StripeClient` class, introduced in v8, that groups API calls under one configured object, replacing the older global `stripe.api_key` pattern the README says will eventually be deprecated.
• ✓Typed resource classes generated from API responses, so a `Customer` or `Charge` object initializes its own fields dynamically instead of you parsing raw JSON.
• ✓Async support: any request method works with an `_async` suffix, like `retrieve_async`, backed by `httpx` by default instead of the sync client's `requests`.
• ✓Automatic retries via `max_network_retries`, triggered by connection errors, timeouts, and HTTP 409 responses, with idempotency keys generated automatically so retries stay safe.
• ✓Swappable HTTP backends: `requests`, `httpx`, `aiohttp`, `pycurl`, or `urllib`, set through the `http_client` option on `StripeClient`.
• ✓Per-request overrides for API key, connected account, and Stripe API version via an `options` argument, useful for Connect platforms handling multiple accounts.
• ✓Type annotations since v7.1.0, tested against Pyright, with experimental support for `Unpack[TypedDict]` in MyPy.
• ✓Built-in request logging through the `STRIPE_LOG` environment variable or Python's own `logging` module, plus access to raw response codes and headers via `last_response`.

Getting Started: Installation

Install it from PyPI with `pip install --upgrade stripe`, or build from source with `python -m pip install .`. The README lists Python 3.9+ as the supported baseline under Stripe's Language Version Support Policy; Python 2.7 support ended after version 5.5.0, and versions from 6.0.0 onward dropped it entirely. If you plan to use the async client without already having an async HTTP library installed, `pip install stripe[async]` pulls one in, a feature the README notes as new in v13.0.1. Preview features are available through separate version suffixes: `bX` for public preview (e.g. `12.2.0b2`) and `aX` for private preview, both installed by pinning the exact version with `pip install stripe==<version>`.

Making API Calls with Python

Set your secret key and call resources through `StripeClient`: `client = StripeClient("sk_test_...")`, then `client.v1.customers.list()` or `client.v1.customers.retrieve("cus_123456789")`. Failed requests raise exceptions whose class indicates the error type, per the API Reference the README links to. For async code, add `_async` to the method name, e.g. `await client.v1.customers.retrieve_async("cus_xyz")`, and `.auto_paging_iter()` works with both sync and async iteration. You can also bypass the library's method definitions entirely with `client.raw_request("post", "/v1/beta_endpoint", ...)`, available since v11, for hitting undocumented or beta endpoints directly.

Other Ways to Integrate Stripe

Stripe Python Library FAQ

The problem it solves

Calling the Stripe API directly from Python means building your own HTTP client: signing requests, parsing JSON into usable objects, retrying failed calls safely, and keeping up with a versioned API that changes over time. That's real work to redo on every project. Stripe Python Library exists so Python developers don't have to. Per the README, its resource objects build their own fields from whatever the API sends back, which is what keeps the library working across different Stripe API versions without you rewriting client code each time Stripe ships changes.

Best use cases

• •Building a Django or Flask backend that creates customers, charges, or subscriptions through the Stripe API without writing raw HTTP request code.
• •Adding async payment processing to an asyncio-based service, using the `_async` method suffix and the `httpx`-backed async client.
• •Running on a Connect platform that needs to make API calls on behalf of connected accounts, using the per-request `stripe_account` option.
• •Testing preview API features early by installing a `bX` (public preview) or `aX` (private preview) version pinned to an exact release.
• •Debugging integration issues by turning on `STRIPE_LOG=debug` or reading `last_response.code` and `last_response.headers` off any returned resource.

Who should try it — and who should skip

Try Stripe Python Library if you're building a Python application, in Django, Flask, FastAPI, or a plain script, that needs to create charges, manage customers, or handle subscriptions through Stripe's API; the typed resources and built-in retry logic save you from rebuilding that plumbing. Skip it if your project is still on Python 3.8 or older, since the README requires 3.9+, or if you specifically need the Ruby or iOS SDKs; check stripe-ruby or stripe-ios instead.

Related repositories