stripe-patterns

Stripe Patterns Skill

TEMPLATE: This skill uses {{PLACEHOLDER}} tokens. Replace with your project values before use.

Purpose

Guide safe and consistent Stripe integration. Routes to existing payment patterns and provides evidence templates for testing.

When This Skill Applies

• Creating or modifying checkout flows
• Implementing Stripe webhooks
• Working with subscriptions or invoices
• Testing payment functionality
• Handling refunds or disputes

Canonical Code References

Configuration

• Stripe Client Factory: {{STRIPE_CONFIG_PATH}}
  • Use factory function for consistent API version
  • Never hardcode API keys

API Routes

• Checkout Session: {{CHECKOUT_ROUTE_PATH}}
• Webhook Handler: {{WEBHOOK_ROUTE_PATH}}

Helpers

• Payment Helpers: {{PAYMENT_HELPERS_PATH}} (use RLS context)
• Subscription Helpers: {{SUBSCRIPTION_HELPERS_PATH}}
• Invoice Helpers: {{INVOICE_HELPERS_PATH}}

Critical Rules

Test Mode Safety Checklist

Before ANY payment work:

• Verify STRIPE_SECRET_KEY starts with sk_test_
• Confirm test webhook secret (whsec_... from Stripe CLI)
• Use test card numbers only (4242...)
• Never use production keys in development

Idempotency Checklist

For webhook handlers:

• Store event ID before processing
• Check for duplicate events
• Use database transactions
• Return 200 OK even on idempotency skip

// Idempotent webhook pattern
await withSystemContext(db, "webhook", async (client) => {
  // Check if already processed
  const existing = await client.webhook_events.findUnique({
    where: { stripe_event_id: event.id },
  });
  if (existing) {
    console.log(`Skipping duplicate event: ${event.id}`);
    return;
  }

  // Process and record
  await client.webhook_events.create({
    data: {
      stripe_event_id: event.id,
      event_type: event.type,
      processed_at: new Date(),
    },
  });
});

Webhook Signature Verification