Stripe

14.2.0 verified Tue May 12 auth: yes python install: verified quickstart: verified

Official Python SDK for the Stripe Payments API. Actively maintained by Stripe. Versioned on a date-based API release cycle (e.g. 2026-02-25.clover). SDK major versions track breaking Python API changes separately from API version pinning. Current API version: 2026-02-25.clover.

pip install stripe

Common errors

error ModuleNotFoundError: No module named 'stripe' ↓

cause The Stripe Python library is not installed in your current Python environment.

fix

pip install stripe

error stripe.error.AuthenticationError: Invalid API Key provided: sk_test_******************** (HINT: API keys start with 'pk_' or 'sk_'; 'sk_test_' and 'sk_live_' keys are secret.) ↓

cause The API key configured for the Stripe SDK is incorrect, revoked, or has insufficient permissions, or you might be using a publishable key (pk_) where a secret key (sk_) is required.

fix

Verify your secret API key (e.g., sk_test_XYZ or sk_live_ABC) in your Stripe dashboard and ensure it's correctly assigned to stripe.api_key.

error stripe.error.InvalidRequestError: No such customer: cus_XYZ ↓

cause The Stripe object ID (e.g., customer, Payment Intent, Charge) provided in the API call does not exist, is misspelled, or belongs to a different API key mode (e.g., using a test ID with a live key).

fix

Verify the object ID is correct and belongs to the API key environment (test or live) you are currently using for your API requests.

error AttributeError: module 'stripe' has no attribute 'checkout' ↓

cause You are attempting to access `stripe.checkout` as a direct attribute or module for creating a checkout session, but the `Session` object is nested under it.

fix

To create a checkout session, use stripe.checkout.Session.create(...).

Warnings

breaking SDK v14.0 (November 2025) pinned API version to 2025-09-30.clover and included breaking changes: InvoiceLineItem.modify() now requires invoice and line_item_id as explicit method parameters. Code passing them via params dict breaks. ↓

fix Update InvoiceLineItem.modify(invoice='in_...', line_item_id='il_...', params={})

breaking Stripe API uses date-based versioning (e.g. 2026-02-25.clover). Each SDK major version pins a new API version. Upgrading SDK major version automatically changes which API version your requests use, which can break existing integrations. ↓

fix Pin SDK version in production. When upgrading major versions, review the API changelog for breaking changes between API versions at docs.stripe.com/changelog.

breaking V2 API endpoints (e.g. /v2/billing) use indexed query format for include[] params: ?include[0]=foo&include[1]=bar. Code mocking the old repeated format (?include=foo&include=bar) breaks in unit tests. ↓

fix Update mock server expectations for v2 endpoint include params to use indexed format.

gotcha stripe.api_key is a global. In multi-threaded or async apps, setting it globally can cause key leakage between requests. Using different keys per request requires StripeClient, not the global API. ↓

fix Use StripeClient(api_key='...') instances per request for multi-tenant applications.

gotcha Publishable keys (pk_live_..., pk_test_...) are for Stripe.js front-end only. Using them server-side in the Python SDK returns 401 Unauthorized. ↓

fix Use secret keys (sk_live_... or sk_test_...) in the Python SDK.

gotcha Webhook signature verification requires the raw request body, not parsed JSON. Frameworks that pre-parse the body (e.g. Django REST Framework with JSONParser) will cause signature verification to fail. ↓

fix Access request.body (Django) or request.data (Flask) before any parsing. Use @csrf_exempt in Django and ensure the body is read as bytes.

breaking The 'stripe' library or its 'webhook' submodule could not be found. This typically indicates that the 'stripe' package is not installed in the environment or the submodule has been removed/renamed in the installed version. ↓

fix Ensure the 'stripe' library is installed using `pip install stripe`. If the module existed in an older version, consider pinning an older SDK version or updating the import statement.

breaking The `stripe` library or its submodules (e.g., `stripe.webhook`) cannot be imported if the package is not installed or not available in the Python environment's `sys.path`. This results in a `ModuleNotFoundError`. ↓

fix Ensure the `stripe` library is correctly installed in the Python environment using `pip install stripe`. If using a virtual environment, ensure it is activated. Verify the installation by running `python -c "import stripe.webhook"`.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.16s 43.3M

3.10 slim (glibc) - - 0.12s 44M

3.11 alpine (musl) - - 0.26s 47.0M

3.11 slim (glibc) - - 0.23s 47M

3.12 alpine (musl) - - 0.48s 37.9M

3.12 slim (glibc) - - 0.46s 38M

3.13 alpine (musl) - - 0.47s 37.7M

3.13 slim (glibc) - - 0.41s 38M

3.9 alpine (musl) - - 0.14s 42.1M

3.9 slim (glibc) - - 0.14s 43M

Imports

stripe

wrong

from stripe import PaymentIntent
PaymentIntent.create(...)

correct

import stripe
stripe.api_key = 'sk_live_...'
pi = stripe.PaymentIntent.create(amount=2000, currency='usd')

Top-level import recommended. Direct class imports work but are less idiomatic and miss global api_key propagation for some patterns.

StripeClient (v10+)

wrong

stripe.api_key = '...'
stripe.PaymentIntent.create(...)

correct

from stripe import StripeClient
client = StripeClient('sk_live_...')
pi = client.payment_intents.create({'amount': 2000, 'currency': 'usd'})

StripeClient is the new explicit client pattern introduced in v7+. Preferred for multi-key setups and async usage. Old global api_key pattern still works but is discouraged.

Quickstart verified last tested: 2026-05-12

Basic payment intent creation and webhook verification. Always verify webhook signatures — do not trust payload content without verification.

import stripe

stripe.api_key = 'sk_test_...'

# Create a payment intent
pi = stripe.PaymentIntent.create(
    amount=2000,
    currency='usd',
    payment_method_types=['card']
)
print(pi.client_secret)

# Verify webhook
import stripe.webhook
event = stripe.Webhook.construct_event(
    payload=request.body,
    sig_header=request.headers['Stripe-Signature'],
    secret='whsec_...'
)