Stripe E-Commerce Shop Integration

Production-tested patterns for integrating Stripe payments into React e-commerce applications with Supabase backend. Supports both Vite and Next.js. All examples use UK GBP currency and follow enterprise security standards.

Framework Support

Quick Start Checklist

1. Install Dependencies: npm install @stripe/stripe-js @stripe/react-stripe-js stripe
2. Environment Variables: Set up .env with Stripe keys
3. Create Client Library: src/lib/stripe.ts
4. Create Server Library: src/lib/stripe-server.ts
5. Create API Endpoints: api/stripe/ directory
6. Create Types: src/types/stripe.ts
7. Set Up Webhook: Configure in Stripe Dashboard

Architecture Overview

┌─────────────────────────────────────────────────────────────────────┐
│                         CLIENT (React/Vite)                          │
├─────────────────────────────────────────────────────────────────────┤
│  CartContext.tsx → Checkout.tsx → Payment.tsx → StripeCheckout.tsx  │
│         ↓              ↓             ↓              ↓                │
│    Add Items     Create Order   Get Secret    PaymentElement         │
└────────────────────────────────┬────────────────────────────────────┘
                                 │ API Calls
┌────────────────────────────────▼────────────────────────────────────┐
│                      SERVER (Vercel API Routes)                      │
├─────────────────────────────────────────────────────────────────────┤
│  /api/stripe/create-payment-intent  →  Stripe API                   │
│  /api/stripe/create-checkout-session →  Stripe API                  │
│  /api/stripe/webhook               ←  Stripe Webhooks               │
└─────────────────────────────────────────────────────────────────────┘

Detailed Implementation

For complete code examples, see:

• ENVIRONMENT.md - Environment variables configuration
• CLIENT.md - Client-side Stripe setup (Vite examples)
• SERVER.md - Server-side Stripe setup and API endpoints (Vite/Vercel)
• NEXTJS.md - Next.js App Router specific patterns
• TYPES.md - TypeScript interfaces
• FLOW.md - Complete checkout flow implementation
• WEBHOOKS.md - Webhook handling for payment events
• DATABASE.md - Required Supabase database tables
• STRIPE-CLI.md - Stripe CLI for dashboard configuration & testing

Stripe MCP Server (AI Agent Integration)

For AI-assisted Stripe management, use the official Stripe MCP server:

Installation

# Add to Claude Code MCP config (~/.claude.json)
claude mcp add --scope user stripe -- npx -y @stripe/mcp --tools=all --api-key=sk_test_YOUR_KEY

Manual Configuration

{
  "mcpServers": {
    "stripe": {
      "command": "npx",
      "args": [
        "-y",
        "@stripe/mcp",
        "--tools=all",
        "--api-key=sk_test_YOUR_STRIPE_SECRET_KEY"
      ]
    }
  }
}

MCP Capabilities

The Stripe MCP enables natural language interactions:

• Create and manage products/prices
• Handle customer operations
• Process payments and refunds
• Search Stripe documentation
• Debug webhook issues
• Manage subscriptions

Documentation: https://docs.stripe.com/mcp

Key Principles

Security First

• NEVER expose secret keys on the client
• ALWAYS validate amounts server-side against database
• ALWAYS use webhook signature validation
• ALWAYS store payment records in database

UK/GBP Configuration

• Currency: 'gbp'
• Country: 'GB'
• Amounts in pence for Stripe API (multiply pounds by 100)

Two Payment Methods

1. Payment Intent (Embedded Form)

   • Payment form stays on your site
   • More control over UI/UX
   • Use PaymentElement component

2. Checkout Session (Stripe Hosted)

   • Redirects to Stripe's hosted page
   • Easier to implement
   • Built-in address collection

Common Commands

# Install Stripe packages
npm install @stripe/stripe-js @stripe/react-stripe-js stripe

# Install Stripe CLI (macOS)
brew install stripe/stripe-cli/stripe

# Login to Stripe CLI
stripe login

# Generate TypeScript types from Supabase (if using)
npx supabase gen types typescript --project-id YOUR_PROJECT_ID > src/types/supabase.ts

Testing

• Use Stripe test mode keys (start with pk_test_ and sk_test_)
• Test card number: 4242 4242 4242 4242
• Any future expiry date and any 3-digit CVC
• Use Stripe CLI for webhook testing: stripe listen --forward-to localhost:3000/api/stripe/webhook

Troubleshooting