Integrate Stripe Payments and Subscriptions

Covers implementing and verifying Stripe payments: checkout, subscriptions, webhooks, and refunds, with explicit server-side authorization and retry boundaries. Three payment-flow patterns: a Stripe-hosted Checkout Session (fastest to implement, reduces direct card-data handling, supports one-time and recurring payments), Payment Intents with a custom UI (via Stripe.js/Elements, more implementation work, more customization), and Setup Intents to save a payment method without charging (used for subscriptions and future payments, requires customer confirmation). Subscriptions are modeled as Product (what's sold), Price (amount and cadence), Subscription (the customer's recurring payment), and Invoice (generated per billing cycle). Customer management covers creating and updating customer records, storing multiple payment methods, and tracking metadata.

import os
import stripe

stripe.api_key = os.environ["STRIPE_SECRET_KEY"]

# Create a checkout session
session = stripe.checkout.Session.create(
    payment_method_types=['card'],
    line_items=[{
        'price_data': {
            'currency': 'usd',
            'product_data': {
                'name': 'Premium Subscription',
            },
            'unit_amount': 2000,  # $20.00
            'recurring': {
                'interval': 'month',
            },
        },
        'quantity': 1,
    }],
    mode='subscription',
    success_url='https://yourdomain.com/success?session_id={CHECKOUT_SESSION_ID}',
    cancel_url='https://yourdomain.com/cancel',
)

# Redirect user to session.url
print(session.url)

Webhook handling must verify Stripe-Signature against the raw request bytes via stripe.Webhook.construct_event with the correct endpoint secret - a bare HMAC does not implement Stripe's timestamped header format or replay tolerance. Critical events include payment_intent.succeeded, payment_intent.payment_failed, customer.subscription.updated/.deleted, charge.refunded, and invoice.payment_succeeded. The documented durable-fulfillment pattern: verify signature and event/account/mode, atomically insert event.id into a durable inbox with a unique constraint, return 2xx only after durable acceptance, reconcile state in a worker applying a guarded transition keyed on order/fulfillment (not just event ID, since different events can describe the same payment), and commit the state change with an outbox entry together so duplicate delivery returns the recorded result rather than fulfilling twice. A check-then-handle-then-mark sequence is explicitly called out as non-atomic, and Checkout success redirects are UI signals, not proof of payment.

Use it for implementing payment processing, subscription billing, one-time payments and refunds, disputes, customer payment-method management, SCA/3D Secure for European payments, or Stripe Connect marketplace flows.

Do NOT use it for tasks unrelated to Stripe integration, and do not treat any code sample here as a complete, deployable fulfillment processor - the sample Flask webhook handler is explicitly a placeholder, not durable processing logic, and the skill records no live transaction result.

Requires an explicitly authorized Stripe test account/sandbox, server-owned order and customer records, the installed SDK/API version, and expected webhook types; amounts, currencies, and price/customer IDs must come from authenticated server policy, never arbitrary client parameters. Test secret keys and webhook signing secrets must load from the project secret mechanism and never be printed. Refund amounts must be validated as positive minor-unit integers before calling stripe.Refund.create. Test cards are provided for success, decline, 3D Secure, and insufficient-funds cases. A worked verification case is specified: deliver the same valid payment event twice and concurrently, then a stale/invalid signature and an out-of-order state event, expecting one durable fulfillment, rejected invalid signatures, no rollback of newer state, and rejection of a zero-amount refund becoming a silent full refund.

References Stripe's own subscription-integration, webhook, fulfillment, and request-idempotency documentation for version-specific detail this single-file skill does not duplicate or bundle as a production wrapper.

Developers implementing production Stripe payment flows who need explicit server-side authorization boundaries, idempotency and webhook-deduplication patterns, and a checklist of common pitfalls - unverified webhooks, missing webhook events, hardcoded amounts, no retry logic, skipped test-mode edge cases - rather than just a happy-path integration sketch.