rendertrust: Skill for Claude Code

Stripe Patterns Skill

Purpose

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

When This Skill Applies

Invoke this skill when:

• 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: lib/stripe-config.ts
  • Use createStripeClient() for consistent API version
  • Never hardcode API keys

API Routes

• Checkout Session: app/api/payments/create-checkout-session/route.ts
• Webhook Handler: app/api/payments/webhook/route.ts

Helpers

• Payment Helpers: utils/data/payments/ (use RLS context)
• Subscription Helpers: utils/data/subscriptions/
• Invoice Helpers: utils/data/invoices/

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(prisma, "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

ALWAYS verify webhook signatures: