name: stripe-patterns
description: Stripe integration templates with reusable code for Checkout, Payment Intents, and Subscriptions. Use when implementing Stripe payments, building checkout flows, handling subscriptions, or integrating payment processing.
allowed-tools: Read, Write, Edit, Bash, Grep, Glob
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