stripe-stack

<essential_principles>

Core Principles

1. Idempotency is Non-Negotiable

   • ALL webhook handlers MUST use database-backed idempotency
   • Never use in-memory Sets (lost on serverless cold starts)
   • Insert event record BEFORE processing, not after

2. Test/Live Mode Separation

   • Use environment variables for ALL keys (never hardcode)
   • Test keys: sk_test_, pk_test_, whsec_test_
   • Live keys: sk_live_, pk_live_, whsec_live_
   • Products/prices must be recreated in live mode

3. Shared Stripe Account

   • All NetZero Suite projects share ONE Stripe account
   • Same webhook secret can be used across projects
   • Each project has its own webhook endpoint URL

4. Lazy Client Initialization

   • Never initialize Stripe at module level (build errors)
   • Use factory function pattern for server-side client
   • Check for API key before creating instance

</essential_principles>

What Are You Building?

Before proceeding, identify your use case:

Workflow Routing

If setting up Stripe in a new project: → Read workflows/setup-new-project.md → Then read references/environment-vars.md → Use templates/stripe-client.ts and templates/env-example.txt

If adding webhook handling: → Read workflows/add-webhook-handler.md → Then read references/webhook-patterns.md → Use templates/webhook-handler-nextjs.ts and templates/idempotency-migration.sql

If implementing subscription billing: → Read workflows/implement-subscriptions.md → Then read references/pricing-models.md → Use templates/plans-config.ts

If adding credit/usage-based system: → Read workflows/add-credit-system.md → Then read references/pricing-models.md

If migrating test → production: → Read workflows/go-live-checklist.md

<quick_reference>

Quick Reference

Environment Variables (Standard)

# Server-side (never expose to client)
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

# Client-side (safe to expose)
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...

# Optional: Price IDs (for test→live switching)
STRIPE_PRICE_STARTER_MONTHLY=price_...
STRIPE_PRICE_PRO_MONTHLY=price_...

Common Webhook Events

Stripe Client Pattern

let _stripe: Stripe | null = null;

export function getStripe(): Stripe {
  if (!_stripe) {
    const key = process.env.STRIPE_SECRET_KEY;
    if (!key) throw new Error('STRIPE_SECRET_KEY not configured');
    _stripe = new Stripe(key, {
      apiVersion: '2025-12-15.clover',
      typescript: true
    });
  }
  return _stripe;
}

Idempotency Table Schema

CREATE TABLE stripe_webhook_events (
  id TEXT PRIMARY KEY,           -- Use Stripe event ID directly
  type TEXT NOT NULL,            -- Event type
  data JSONB NOT NULL,           -- Full event payload
  processed_at TIMESTAMPTZ DEFAULT NOW()
);

Webhook Handler Structure

export async function POST(request: NextRequest) {
  const body = await request.text();
  const signature = request.headers.get('stripe-signature');

  // 1. Verify signature
  const event = stripe.webhooks.constructEvent(body, signature, webhookSecret);

  // 2. Check idempotency (BEFORE processing)
  const { data: existing } = await supabase
    .from('stripe_webhook_events')
    .select('id')
    .eq('id', event.id)
    .single();

  if (existing) return NextResponse.json({ duplicate: true });

  // 3. Log event (INSERT before processing)
  await supabase.from('stripe_webhook_events').insert({
    id: event.id,
    type: event.type,
    data: event,
  });

  // 4. Process event
  switch (event.type) {
    case 'checkout.session.completed':
      await handleCheckout(event.data.object);
      break;
    // ... other handlers
  }

  return NextResponse.json({ received: true });
}

</quick_reference>

<integration_notes>

Integration Notes

Works With

• Supabase: Use service role client for webhook handlers (bypasses RLS)
• Prisma: Alternative to Supabase for idempotency table
• Vercel: Add runtime/maxDuration config for webhook routes
• Next.js App Router: Use request.text() for raw body

Related Skills

• supabase-sql-skill - For database migrations
• create-hooks-skill - For post-deployment notifications

GitHub Repository

Private templates and examples available at: github.com/ScientiaCapital/stripe-stack

</integration_notes>

<reference_index>

Reference Files

Template Files

Workflow Files

</reference_index>