What is stripe-patterns?

The Stripe Patterns skill provides a comprehensive framework for implementing secure and consistent Stripe payment integrations. It offers standardized patterns for checkout flows, subscription management, and robust webhook handling, incorporating critical security practices like signature verification and idempotency to ensure reliable financial transactions and data integrity.

When should I use stripe-patterns?

stripe-patterns is useful in the following scenarios: • Developing secure checkout sessions and subscription lifecycles using standardized, production-ready code patterns. • Implementing idempotent webhook handlers to safely process Stripe events and prevent duplicate transaction errors. • Ensuring API security by verifying Stripe webhook signatures and managing environment-specific API keys. • Streamlining the QA process with detailed payment testing evidence templates and safety checklists for test-mode operations. • Architecting scalable payment infrastructures by utilizing pre-defined helpers for invoices, subscriptions, and RLS-context data handling.

name	stripe-patterns
description	Stripe payment integration patterns. Use when implementing payment flows, handling webhooks, or working with subscriptions. Routes to existing patterns and provides evidence templates for payment testing.

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:

import { stripe } from "@/lib/stripe-config";

const signature = request.headers.get("stripe-signature");
const event = stripe.webhooks.constructEvent(
  body,
  signature,
  process.env.STRIPE_WEBHOOK_SECRET,
);

Common Patterns

Create Checkout Session

import { createStripeClient } from "@/lib/stripe-config";
import { withUserContext } from "@/lib/rls-context";

export async function createCheckout(userId: string, priceId: string) {
  const stripe = createStripeClient();

  // Store user context for success handling
  const session = await stripe.checkout.sessions.create({
    mode: "subscription",
    line_items: [{ price: priceId, quantity: 1 }],
    success_url: `${process.env.NEXT_PUBLIC_APP_URL}/success?session_id={CHECKOUT_SESSION_ID}`,
    cancel_url: `${process.env.NEXT_PUBLIC_APP_URL}/pricing`,
    metadata: { userId },
  });

  return session;
}

Handle Subscription Events

// Webhook event types to handle
const SUBSCRIPTION_EVENTS = [
  "customer.subscription.created",
  "customer.subscription.updated",
  "customer.subscription.deleted",
  "invoice.payment_succeeded",
  "invoice.payment_failed",
];

Evidence Template for Linear

When completing payment work, attach this evidence block:

**Payment Testing Evidence**

- [ ] Test mode verified (`sk_test_` key)
- [ ] Webhook signature verification tested
- [ ] Idempotency tested (duplicate event handling)
- [ ] Success flow tested (card 4242...)
- [ ] Failure flow tested (card 4000000000000002)
- [ ] Subscription lifecycle tested (create/update/cancel)

**Test Results:**

- Checkout session: [session_id]
- Webhook events processed: [count]
- Subscription status: [active/cancelled]

Authoritative References

Stripe Config: lib/stripe-config.ts
Webhook Route: app/api/payments/webhook/route.ts
Payment Tests: __tests__/payments/
Stripe Docs: https://stripe.com/docs

stripe-patterns

When & Why to Use This Skill

Use Cases