id: stripe-integration name: Stripe Integration version: 1.0.0 layer: 2

description: | Get paid from day one. Payments, subscriptions, billing portal, webhooks, metered billing, Stripe Connect. The complete guide to implementing Stripe correctly, including all the edge cases that will bite you at 3am.

This isn't just API calls - it's the full payment system: handling failures, managing subscriptions, dealing with dunning, and keeping revenue flowing.

principles:

• "Webhooks are source of truth, not API responses"
• "Handle every edge case for money"
• "Idempotency keys on everything"
• "Test with real cards in test mode"
• "Never store card details yourself"
• "Logs everything for debugging payment issues"

owns:

• stripe-payments
• subscription-management
• billing-portal
• stripe-webhooks
• checkout-sessions
• payment-intents
• stripe-connect
• metered-billing
• dunning-management
• payment-failure-handling
• stripe-customer-sync
• pricing-tables

does_not_own:

• pricing-strategy → product-strategy
• tax-calculation → finance-ops
• accounting → finance-ops
• fraud-detection → security
• user-authentication → auth-patterns

triggers:

• "stripe"
• "payments"
• "subscription"
• "billing"
• "checkout"
• "pricing"
• "metered billing"
• "stripe connect"
• "webhooks payment"
• "payment intent"
• "customer portal"
• "dunning"
• "failed payment"
• "refund"

pairs_with:

• nextjs-supabase-auth # User auth
• supabase-backend # Database for billing state
• webhook-patterns # General webhook handling
• security # PCI compliance

requires:

• supabase-backend

stack: libraries: - stripe - "@stripe/stripe-js" - "@stripe/react-stripe-js"

expertise_level: battle-tested identity: | You are a payments engineer who has processed billions in transactions. You've seen every edge case - declined cards, webhook failures, subscription nightmares, currency issues, refund fraud. You know that payments code must be bulletproof because errors cost real money. You're paranoid about race conditions, idempotency, and webhook verification.

patterns:

• name: Idempotency Key Everything description: Use idempotency keys on all payment operations to prevent duplicate charges when: Any operation that creates or modifies financial data example: | import { v4 as uuid } from 'uuid';

  const idempotencyKey =

  charge_${userId}_${orderId}

  ;

  const charge = await stripe.charges.create({ amount: 5000, currency: 'usd', customer: customerId }, { idempotencyKey });

• name: Webhook State Machine description: Handle webhooks as state transitions, not triggers when: Processing subscription lifecycle events example: | // Store webhook events before processing const event = await db.webhookEvents.create({ ... });

  switch (event.type) { case 'customer.subscription.created': await transition(subscription, 'active'); break; case 'invoice.payment_failed': await transition(subscription, 'past_due'); break; }

• name: Test Mode Throughout Development description: Use Stripe test mode with real test cards for all development when: Building any Stripe integration example: |

  Environment setup

  STRIPE_SECRET_KEY=sk_test_... STRIPE_PUBLISHABLE_KEY=pk_test_...

  Use Stripe test cards

  4242 4242 4242 4242 - Success 4000 0000 0000 0002 - Declined 4000 0000 0000 9995 - Insufficient funds

• name: Sync Before Act description: Always fetch latest state from Stripe before making decisions when: User-triggered operations on existing Stripe objects example: | // Don't trust local state for financial decisions const subscription = await stripe.subscriptions.retrieve(subId);

  if (subscription.status === 'active') { // Safe to proceed with upgrade }

• name: Separate Webhook Receiver from Processor description: Receive webhook, verify signature, queue for processing, return 200 when: Implementing webhook handlers example: | // Webhook endpoint (fast, synchronous) export async function POST(req: Request) { const payload = await req.text(); const sig = req.headers.get('stripe-signature')!;

  const event = stripe.webhooks.constructEvent(payload, sig, secret);
  
  // Queue for processing
  await queue.add('stripe-webhook', event);
  
  return new Response(null, { status: 200 });
  

  }

• name: Dunning with Grace Periods description: Give customers time to fix payment failures before degrading service when: Handling failed subscription payments example: |

  Stripe's Smart Retries handle initial failures

  Add grace period before action:

  Day 0: Payment fails, email sent

  Day 3: Reminder email

  Day 7: Final warning

  Day 10: Downgrade or suspend

anti_patterns:

• name: Trust the API Response description: Assuming the API call succeeded means the operation completed why: API might return success but webhook reveals the real outcome instead: | Webhooks are source of truth. API responses are optimistic. Wait for webhook confirmation before showing success to user.

• name: Webhook Without Signature Verification description: Processing webhook events without verifying they came from Stripe why: Attackers can forge webhook payloads to credit accounts or trigger actions instead: | Always verify webhook signature: const event = stripe.webhooks.constructEvent( payload, signature, webhookSecret );

• name: Subscription Status Checks Without Refresh description: Checking subscription.status from database without fetching from Stripe why: Local state goes stale, payment failures happen between checks instead: | await stripe.subscriptions.retrieve(subId) before any financial decision. Cache with short TTL (minutes, not hours).

• name: Synchronous Webhook Processing description: Doing slow work in webhook handler before returning 200 why: Stripe times out at 5 seconds and retries, causing duplicate processing instead: | Verify signature → Queue event → Return 200 immediately. Process asynchronously with retry logic.

• name: Customer Creation Without Error Handling description: Creating customers without handling duplicate errors why: Race conditions cause duplicate customer records instead: | Use idempotency keys. Check for existing customer by email first. Handle resource_already_exists error gracefully.

• name: Hardcoded Prices description: Hardcoding price IDs or amounts in code why: Price changes require code deployment, A/B testing is impossible instead: | Store price IDs in database or config. Use Stripe's Price objects. Support multiple active prices per product.

handoffs: receives_from: - skill: nextjs-supabase-auth receives: Authenticated user context - skill: supabase-backend receives: User and subscription data models hands_to: - skill: frontend provides: Checkout flow and billing portal integration - skill: backend provides: Subscription status for feature gating - skill: testing-automation trigger: test|integration test|payment testing provides: Payment flow test scenarios and webhook mocking requirements

tags:

• payments
• stripe
• billing
• subscriptions
• webhooks
• saas
• monetization

Quick Wins - Immediate security and reliability improvements

quick_wins:

• name: Add webhook signature verification effort: 5 minutes impact: critical description: Prevent fake webhook attacks that grant unauthorized access code: |

  // Before: DANGEROUS - accepts any POST
  export async function POST(req: Request) {
    const body = await req.json();
    await processEvent(body); // Anyone can fake this!
  }
  
  // After: SECURE - verifies Stripe signature
  export async function POST(req: Request) {
    const rawBody = await req.text();
    const sig = req.headers.get('stripe-signature')!;
  
    try {
      const event = stripe.webhooks.constructEvent(
        rawBody,
        sig,
        process.env.STRIPE_WEBHOOK_SECRET!
      );
      await processEvent(event);
      return new Response(null, { status: 200 });
    } catch (err) {
      return new Response('Invalid signature', { status: 400 });
    }
  }
  

• name: Add idempotency keys to payments effort: 10 minutes impact: high description: Prevent duplicate charges when users click twice or network retries code: |

  // Before: RISKY - can create duplicate charges
  const paymentIntent = await stripe.paymentIntents.create({
    amount: 1000,
    currency: 'usd',
    customer: customerId,
  });
  
  // After: SAFE - same key = same result
  const paymentIntent = await stripe.paymentIntents.create(
    {
      amount: 1000,
      currency: 'usd',
      customer: customerId,
    },
    {
      idempotencyKey: `payment_${orderId}_${userId}`,
    }
  );
  

• name: Add metadata to checkout sessions effort: 5 minutes impact: high description: Enable user identification in webhooks for access provisioning code: |

  const session = await stripe.checkout.sessions.create({
    // ... existing config
    metadata: {
      userId: user.id,
      orderId: order.id,
      planType: plan.type,
    },
    subscription_data: {
      metadata: {
        userId: user.id,  // Persists to subscription object
      },
    },
  });
  
  // In webhook:
  const { userId } = event.data.object.metadata;
  await grantAccess(userId);
  

• name: Move keys to environment variables effort: 5 minutes impact: critical description: Never commit API keys to source control code: |

  # .env.local (never commit this file)
  STRIPE_SECRET_KEY=sk_test_xxx
  STRIPE_PUBLISHABLE_KEY=pk_test_xxx
  STRIPE_WEBHOOK_SECRET=whsec_xxx
  
  # .gitignore (add if not present)
  .env
  .env.local
  .env.*.local
  

  // Access via environment
  const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
    apiVersion: '2024-12-18.acacia',
  });
  

• name: Add payment failure webhook handler effort: 15 minutes impact: high description: Recover 30-40% of failed payments with proper dunning code: |

  case 'invoice.payment_failed':
    const invoice = event.data.object as Stripe.Invoice;
    const { userId } = invoice.subscription_details?.metadata || {};
  
    if (userId) {
      // Send email with payment update link
      await sendEmail(userId, 'payment_failed', {
        updateUrl: await createBillingPortalSession(invoice.customer),
        amount: formatCurrency(invoice.amount_due, invoice.currency),
      });
  
      // Log for monitoring
      await logPaymentFailure({
        userId,
        invoiceId: invoice.id,
        reason: invoice.last_finalization_error?.message,
      });
    }
    break;
  

• name: Implement webhook event deduplication effort: 10 minutes impact: medium description: Handle webhook retries safely without processing events twice code: |

  export async function POST(req: Request) {
    // ... signature verification ...
  
    // Check if we've already processed this event
    const existing = await db.webhookEvents.findUnique({
      where: { stripeEventId: event.id },
    });
  
    if (existing?.processedAt) {
      // Already processed, return success
      return new Response(null, { status: 200 });
    }
  
    // Record event before processing
    await db.webhookEvents.upsert({
      where: { stripeEventId: event.id },
      create: { stripeEventId: event.id, type: event.type },
      update: {},
    });
  
    try {
      await processEvent(event);
      await db.webhookEvents.update({
        where: { stripeEventId: event.id },
        data: { processedAt: new Date() },
      });
    } catch (error) {
      // Log error but return 200 to prevent infinite retries
      console.error('Webhook processing failed:', error);
    }
  
    return new Response(null, { status: 200 });
  }