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