Stripe

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.

Install

• pip install stripe Python

Imports

• stripe

  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+)

  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

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_...'
)