Stripe Integration Expert

Stripe Integration Expert

Comprehensive guidance for integrating Stripe payments including subscriptions, usage-based billing, webhooks, and multi-platform support (Next.js, iOS, Android, Flutter) with Supabase database synchronization.

Philosophy: Use Stripe Checkout for simplicity, Payment Intents for customization. Always verify webhooks. For Supabase sync, prefer Stripe Sync Engine (one-click, zero maintenance) unless you need custom schemas. Never expose secret keys to clients.

Critical Rules

API Keys Security

NEVER:

• Expose secret keys in client code
• Commit keys to version control
• Log full API keys
• Use secret keys in browser/mobile apps

ALWAYS:

• Use environment variables for all keys
• Use publishable key for client-side Stripe.js
• Use restricted keys for specific operations
• Rotate keys immediately if compromised

Webhook Security (CRITICAL)

// CORRECT: Use raw body for signature verification
const body = await req.text()  // Raw string, NOT parsed
const signature = req.headers.get('stripe-signature')!
const event = stripe.webhooks.constructEvent(body, signature, webhookSecret)

// WRONG: This will FAIL signature verification
const body = await req.json()  // DON'T parse first!