Stripe Integration Patterns

Comprehensive Stripe integration templates for FastAPI backends and Next.js frontends, including Checkout Sessions, Payment Intents, and Subscription billing.

Use When

• Implementing Stripe payment processing in applications

• Building checkout flows for one-time or recurring payments

• Integrating subscription billing systems

• Setting up webhook handlers for payment events

• Creating secure payment forms with Stripe Elements

• Validating Stripe API configuration

Security Requirements

CRITICAL: All templates follow strict security rules:

• All API keys use placeholders: your_stripe_key_here

• Code reads from environment variables only

• .env.example templates provided with placeholders

• .gitignore protects secret files

• Documentation explains how to obtain Stripe keys

NEVER hardcode actual Stripe API keys in any files!

Integration Patterns

1. Checkout Sessions (Redirect Flow)

Best for: Quick integration, hosted payment pages, minimal frontend code

Flow:

• Create Checkout Session on backend with line items and success URL

• Redirect customer to Stripe-hosted checkout page

• Handle checkout.session.completed webhook for fulfillment

Use: scripts/setup-stripe-checkout.sh and templates/checkout_session.py

2. Payment Intents (Custom UI)

Best for: Custom payment forms, direct card collection, advanced UX control

Flow:

• Create PaymentIntent on backend when checkout begins

• Pass client secret to frontend

• Collect payment details with Stripe Elements

• Confirm payment on client side

• Monitor webhooks for payment success/failure

Use: scripts/setup-payment-intents.sh and templates/payment_intent.py

3. Subscriptions (Recurring Billing)

Best for: Recurring revenue, subscription services, membership access

Flow:

• Create or retrieve Customer object

• Attach payment method to customer

• Create Subscription with pricing and billing cycle

• Handle subscription lifecycle events via webhooks

Use: scripts/setup-subscriptions.sh and templates/subscription.py

Available Scripts

setup-stripe-checkout.sh

Creates complete Checkout Session implementation with FastAPI endpoint, webhook handler, and success/cancel pages.

bash scripts/setup-stripe-checkout.sh

setup-payment-intents.sh

Sets up Payment Intent workflow with client secret handling, Stripe Elements integration, and payment confirmation.

bash scripts/setup-payment-intents.sh

setup-subscriptions.sh

Implements subscription billing with customer management, subscription creation, and lifecycle webhook handlers.

bash scripts/setup-subscriptions.sh

validate-stripe-config.sh

Validates Stripe configuration including API keys, webhook secrets, environment setup, and .gitignore protection.

bash scripts/validate-stripe-config.sh

Available Templates

Backend Templates (Python/FastAPI)

checkout_session.py - Complete Checkout Session endpoint

• Creates session with line items

• Handles success/cancel redirects

• Returns session ID for redirect

payment_intent.py - Payment Intent workflow

• Creates PaymentIntent with amount/currency

• Returns client secret for frontend

• Handles payment confirmation

subscription.py - Subscription management

• Customer creation and retrieval

• Payment method attachment

• Subscription creation with pricing

Frontend Templates (TypeScript/Next.js)

stripe_elements.tsx - Stripe Elements component

• Card input with validation

• Payment Intent confirmation

• Error handling and status updates

checkout_page.tsx - Complete checkout page

• Product display with pricing

• Checkout Session redirect flow

• Success/cancel page handling

Available Examples

fastapi-checkout-example.py

Complete working example with:

• FastAPI application setup

• Checkout Session creation endpoint

• Webhook handler for fulfillment

• Environment configuration

• Error handling

nextjs-payment-form-example.tsx

Full payment form implementation:

• Stripe Elements integration

• Payment Intent confirmation

• Loading states and error display

• Success/failure handling

subscription-flow-example.py

End-to-end subscription workflow:

• Customer creation

• Payment method collection

• Subscription creation

• Webhook event processing

• Subscription lifecycle management

Setup Instructions

1. Obtain Stripe Keys

Test Mode (for development):

• Visit https://dashboard.stripe.com/test/apikeys

• Copy "Publishable key" and "Secret key"

• Use test card: 4242 4242 4242 4242

Live Mode (for production):

• Complete account verification

• Visit https://dashboard.stripe.com/apikeys

• Copy production keys

• NEVER commit live keys to git!

2. Configure Environment

Create .env file (use .env.example as template):

.env (NEVER commit this file)

STRIPE_SECRET_KEY=your_stripe_secret_key_here STRIPE_PUBLISHABLE_KEY=your_stripe_publishable_key_here STRIPE_WEBHOOK_SECRET=your_webhook_secret_here

Add to .gitignore :

.env .env.local .env.development .env.production !.env.example

3. Install Dependencies

Backend (Python):

pip install stripe fastapi uvicorn python-dotenv

Frontend (Next.js):

npm install @stripe/stripe-js @stripe/react-stripe-js

4. Set Up Webhooks

Local Development:

• Install Stripe CLI: https://stripe.com/docs/stripe-cli

• Run stripe login

• Forward events: stripe listen --forward-to localhost:8000/webhook

• Copy webhook signing secret to .env

Production:

• Add endpoint in Stripe Dashboard

• Select events to listen for

• Copy webhook signing secret

Best Practices

Security

• Always use environment variables for API keys

• Validate webhook signatures to prevent tampering

• Use HTTPS in production for all endpoints

• Never log sensitive payment information

• Implement proper error handling without exposing keys

Payment Flow

• Create PaymentIntent as early as possible (when amount is known)

• Store PaymentIntent ID for retrieval on page refresh

• Use idempotency keys for safe retries

• Handle all possible payment statuses

• Implement proper loading states in UI

Subscriptions

• Use default_incomplete payment behavior

• Collect payment method before creating subscription

• Handle trial periods correctly

• Monitor subscription status changes via webhooks

• Implement proper cancellation and upgrade flows

Testing

• Use Stripe test cards: https://stripe.com/docs/testing

• Test webhook events with Stripe CLI

• Verify error handling for declined cards

• Test 3D Secure authentication flows

• Validate success and failure paths

Common Use Cases

One-Time Payment

Use Checkout Sessions for simplicity or Payment Intents for custom UI.

Recurring Billing

Use Subscriptions with automatic invoice generation.

Free Trial

Create subscription with trial_period_days parameter.

Usage-Based Billing

Use Subscriptions with metered billing and usage reports.

Multiple Payment Methods

Store payment methods on Customer object and set default.

Troubleshooting

Payment Fails Silently

• Check webhook endpoint is accessible

• Verify webhook signature validation

• Review Stripe Dashboard event logs

Checkout Session Expires

• Sessions expire after 24 hours

• Create new session for retry

Subscription Status Stuck

• Check for failed payments in Dashboard

• Verify payment method is valid

• Review subscription payment settings

CORS Errors

• Configure CORS middleware in FastAPI

• Allow Stripe.js origins in production

References

• Stripe Checkout: https://docs.stripe.com/payments/checkout

• Payment Intents: https://docs.stripe.com/payments/payment-intents

• Subscriptions: https://docs.stripe.com/billing/subscriptions

• Webhooks: https://docs.stripe.com/webhooks

• Testing: https://docs.stripe.com/testing