Stripe Integration Guide

/stripe-integration

Master Stripe payment processing integration for robust, PCI-compliant payment flows including checkout, subscriptions, webhooks, and refunds. Deliver working server and client code as chat artifacts in the user's stack; ask the user to paste their existing payment code when debugging.

When to Use This Skill

• Implementing payment processing in web/mobile applications
• Setting up subscription billing systems
• Handling one-time payments and recurring charges
• Processing refunds and disputes
• Managing customer payment methods
• Implementing SCA (Strong Customer Authentication) for European payments
• Building marketplace payment flows with Stripe Connect

Core Concepts

1. Payment Flows

Checkout Sessions

• Recommended for most integrations
• Supports all UI paths:
  • Stripe-hosted checkout page
  • Embedded checkout form
  • Custom UI with Elements (Payment Element, Express Checkout Element) using ui_mode='custom'
• Provides built-in checkout capabilities (line items, discounts, tax, shipping, address collection, saved payment methods, and checkout lifecycle events)
• Lower integration and maintenance burden than Payment Intents

Payment Intents (bespoke control)

• You calculate the final amount with taxes, discounts, subscriptions, and currency conversion yourself
• More complex implementation and long-term maintenance burden
• Requires Stripe.js for PCI compliance

Setup Intents (save payment methods)

• Collect a payment method without charging
• Used for subscriptions and future payments
• Requires customer confirmation

2. Webhooks

Critical events:

• payment_intent.succeeded: payment completed
• payment_intent.payment_failed: payment failed
• customer.subscription.updated: subscription changed
• customer.subscription.deleted: subscription canceled
• charge.refunded: refund processed
• invoice.payment_succeeded: subscription payment successful

Always verify webhook signatures with the endpoint's signing secret before trusting the payload, respond 2xx quickly, and make handlers idempotent (Stripe retries).

3. Subscriptions

Components:

• Product: what you're selling
• Price: how much and how often
• Subscription: customer's recurring payment
• Invoice: generated for each billing cycle

4. Customer Management

• Create and manage customer records
• Store multiple payment methods
• Track customer metadata
• Manage billing details

PCI Awareness

• Card numbers must never touch your server: use Stripe-hosted Checkout, Elements, or mobile SDKs so card data goes directly to Stripe
• Keep secret keys server-side only; the browser gets only the publishable key and client secrets
• Never log full card numbers, CVCs, or raw webhook secrets

Quick Start

import stripe

stripe.api_key = "sk_test_..."

# Create a checkout session
session = stripe.checkout.Session.create(
    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)

Testing

# Use test mode keys
stripe.api_key = "sk_test_..."

# Test card numbers
TEST_CARDS = {
    'success': '4242424242424242',
    'declined': '4000000000000002',
    '3d_secure': '4000002500003155',
    'insufficient_funds': '4000000000009995'
}

def test_payment_flow():
    """Test complete payment flow."""
    # Create test customer
    customer = stripe.Customer.create(
        email="[email protected]"
    )

    # Create payment intent
    intent = stripe.PaymentIntent.create(
        amount=1000,
        automatic_payment_methods={
            'enabled': True
        },
        currency='usd',
        customer=customer.id
    )

    # Confirm with test card
    confirmed = stripe.PaymentIntent.confirm(
        intent.id,
        payment_method='pm_card_visa'  # Test payment method
    )

    assert confirmed.status == 'succeeded'

Always develop against test mode keys, exercise the failure cards (declined, insufficient funds, 3D Secure) as well as the success path, and test webhook handling with Stripe's test events before going live.

Usage

/stripe-integration $ARGUMENTS