Resources

scripts/
  validate-payments.sh
references/
  payment-patterns.md

Payment Integration Implementation

This skill guides you through implementing payment processing in applications, from provider selection to webhook handling. It leverages GoodVibes precision tools for secure, production-ready payment integrations.

When to Use This Skill

Use this skill when you need to:

Set up payment processing (one-time or recurring)
Implement checkout flows and payment forms
Handle subscription billing and management
Process payment webhooks securely
Test payment flows in development
Ensure PCI compliance and security
Migrate between payment providers

Workflow

Follow this sequence for payment integration:

1. Discover Existing Payment Infrastructure

Before implementing payment features, understand the current state:

precision_grep:
  queries:
    - id: payment-libs
      pattern: "stripe|lemonsqueezy|paddle"
      glob: "package.json"
    - id: webhook-routes
      pattern: "(webhook|payment|checkout)"
      glob: "src/**/*.{ts,js,tsx,jsx}"
  output:
    format: files_only

Check for:

Existing payment libraries
Webhook endpoints
Environment variables for API keys
Payment-related database models

Check project memory for payment decisions:

precision_read:
  files:
    - path: ".goodvibes/memory/decisions.md"
      extract: content
  output:
    format: minimal

Search for payment provider choices, checkout flow patterns, and subscription models.

2. Select Payment Provider

Choose based on your requirements:

Use Stripe when:

You need maximum flexibility and control
Supporting complex subscription models
Requiring advanced features (invoicing, tax, fraud detection)
Building custom payment flows
Need extensive API documentation

Use LemonSqueezy when:

You're selling digital products/SaaS
Want merchant of record (handles taxes, VAT, compliance)
Need simple subscription management
Prefer minimal compliance burden
Operating globally with automatic tax handling

Use Paddle when:

Selling software/SaaS products
Need merchant of record services
Want subscription and license management
Prefer revenue recovery features
Operating in B2B/enterprise markets

Document the decision:

precision_write:
  files:
    - path: ".goodvibes/memory/decisions.md"
      mode: overwrite
      content: |
        ## Payment Provider Selection
        
        **Decision**: Using [Provider] for payment processing
        **Rationale**: [Why this provider fits requirements]
        **Date**: YYYY-MM-DD
        
        Key factors:
        - [Factor 1]
        - [Factor 2]
        - [Factor 3]

3. Setup and Installation

Install the appropriate SDK:

Stripe:

precision_exec:
  commands:
    - cmd: "npm install stripe @stripe/stripe-js"
    # @types/stripe is not needed - Stripe ships with built-in types
  verbosity: minimal

LemonSqueezy:

precision_exec:
  commands:
    - cmd: "npm install @lemonsqueezy/lemonsqueezy.js"
  verbosity: minimal

Paddle:

precision_exec:
  commands:
    - cmd: "npm install @paddle/paddle-node-sdk"
  verbosity: minimal

Configure environment variables:

Create .env.example template:

precision_write:
  files:
    - path: ".env.example"
      mode: overwrite
      content: |
        # Payment Provider Configuration
        
        # Stripe (if using Stripe)
        STRIPE_SECRET_KEY=sk_test_...
        STRIPE_PUBLISHABLE_KEY=pk_test_...
        STRIPE_WEBHOOK_SECRET=whsec_...
        
        # LemonSqueezy (if using LemonSqueezy)
        LEMONSQUEEZY_API_KEY=...
        LEMONSQUEEZY_STORE_ID=...
        LEMONSQUEEZY_WEBHOOK_SECRET=...
        
        # Paddle (if using Paddle)
        PADDLE_API_KEY=...
        PADDLE_WEBHOOK_SECRET=...
        PADDLE_ENVIRONMENT=sandbox

Verify secrets are gitignored:

precision_grep:
  queries:
    - id: check-gitignore
      pattern: "^\\.env$"
      path: ".gitignore"
  output:
    format: files_only

If not found, add .env to .gitignore.

4. Implement Checkout Flow

One-Time Payments (Stripe)

Create checkout session endpoint:

precision_write:
  files:
    - path: "src/app/api/checkout/route.ts"
      content: |
        import { NextRequest, NextResponse } from 'next/server';
        import Stripe from 'stripe';
        import { getServerSession } from 'next-auth';
        import { authOptions } from '@/lib/auth';
        import { z } from 'zod';
        
        const stripeSecretKey = process.env.STRIPE_SECRET_KEY;
        if (!stripeSecretKey) {
          throw new Error('STRIPE_SECRET_KEY is required');
        }
        
        const stripe = new Stripe(stripeSecretKey, {
          apiVersion: '2024-11-20.acacia',
        });
        
        export async function POST(request: NextRequest) {
          try {
            // Check authentication
            const authSession = await getServerSession();
            if (!authSession?.user) {
              return NextResponse.json(
                { error: 'Unauthorized' },
                { status: 401 }
              );
            }
            
            // Validate input with Zod
            const schema = z.object({
              priceId: z.string().min(1),
              successUrl: z.string().url(),
              cancelUrl: z.string().url(),
            });
            
            const body = await request.json();
            const result = schema.safeParse(body);
            
            if (!result.success) {
              return NextResponse.json(
                { error: 'Invalid input', details: result.error.flatten() },
                { status: 400 }
              );
            }
            
            const { priceId, successUrl, cancelUrl } = result.data;
            
            // Validate URLs against allowed origins
            const appUrl = process.env.NEXT_PUBLIC_APP_URL;
            if (!appUrl) throw new Error('NEXT_PUBLIC_APP_URL is required');
            const allowedOrigins = [appUrl];
            const successOrigin = new URL(successUrl).origin;
            const cancelOrigin = new URL(cancelUrl).origin;
            
            if (!allowedOrigins.includes(successOrigin) || !allowedOrigins.includes(cancelOrigin)) {
              return NextResponse.json(
                { error: 'Invalid redirect URLs' },
                { status: 400 }
              );
            }
            
            const stripeSession = await stripe.checkout.sessions.create({
              mode: 'payment',
              line_items: [
                {
                  price: priceId,
                  quantity: 1,
                },
              ],
              success_url: successUrl,
              cancel_url: cancelUrl,
              metadata: {
                userId: authSession.user.id,
              },
            });
            
            return NextResponse.json({ sessionId: stripeSession.id });
          } catch (error: unknown) {
            const message = error instanceof Error ? error.message : 'Unknown error';
            console.error('Checkout error:', message);
            return NextResponse.json(
              { error: 'Failed to create checkout session' },
              { status: 500 }
            );
          }
        }

One-Time Payments (LemonSqueezy)

precision_write:
  files:
    - path: "src/app/api/checkout/route.ts"
      content: |
        import { NextRequest, NextResponse } from 'next/server';
        import { lemonSqueezySetup, createCheckout } from '@lemonsqueezy/lemonsqueezy.js';
        import { getServerSession } from 'next-auth';
        import { authOptions } from '@/lib/auth';
        
        const lemonSqueezyApiKey = process.env.LEMONSQUEEZY_API_KEY;
        if (!lemonSqueezyApiKey) {
          throw new Error('LEMONSQUEEZY_API_KEY is required');
        }
        lemonSqueezySetup({ apiKey: lemonSqueezyApiKey });
        
        export async function POST(request: NextRequest) {
          try {
            const authSession = await getServerSession(authOptions);
            if (!authSession?.user) {
              return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
            }
            
            const { variantId, email } = await request.json();
            
            const lemonSqueezyStoreId = process.env.LEMONSQUEEZY_STORE_ID;
            if (!lemonSqueezyStoreId) {
              throw new Error('LEMONSQUEEZY_STORE_ID is required');
            }
            
            const { data, error } = await createCheckout(
              lemonSqueezyStoreId,
              variantId,
              {
                checkoutData: {
                  email,
                  custom: {
                    user_id: authSession.user.id,
                  },
                },
              }
            );
            
            if (error) {
              throw new Error(error.message);
            }
            
            return NextResponse.json({ checkoutUrl: data.attributes.url });
          } catch (error: unknown) {
            const message = error instanceof Error ? error.message : 'Unknown error';
            console.error('Checkout error:', message);
            return NextResponse.json(
              { error: 'Failed to create checkout' },
              { status: 500 }
            );
          }
        }

5. Subscription Billing

Create Subscription Plans (Stripe)

precision_write:
  files:
    - path: "src/lib/stripe/plans.ts"
      content: |
        export const SUBSCRIPTION_PLANS = {
          starter: {
            name: 'Starter',
            priceId: (() => {
              const priceId = process.env.STRIPE_PRICE_STARTER;
              if (!priceId) throw new Error('STRIPE_PRICE_STARTER is required');
              return priceId;
            })(),
            price: 9,
            interval: 'month' as const,
            features: ['Feature 1', 'Feature 2'],
          },
          pro: {
            name: 'Pro',
            priceId: (() => {
              const priceId = process.env.STRIPE_PRICE_PRO;
              if (!priceId) throw new Error('STRIPE_PRICE_PRO is required');
              return priceId;
            })(),
            price: 29,
            interval: 'month' as const,
            features: ['All Starter features', 'Feature 3', 'Feature 4'],
          },
        } as const;
        
        export type PlanId = keyof typeof SUBSCRIPTION_PLANS;

Subscription Checkout

precision_write:
  files:
    - path: "src/app/api/subscribe/route.ts"
      content: |
        import { NextRequest, NextResponse } from 'next/server';
        import Stripe from 'stripe';
        import { z } from 'zod';
        import { SUBSCRIPTION_PLANS } from '@/lib/stripe/plans';
        import { getServerSession } from 'next-auth';
        import { authOptions } from '@/lib/auth';
        
        // Validate required environment variables
        const secretKey = process.env.STRIPE_SECRET_KEY;
        if (!secretKey) throw new Error('STRIPE_SECRET_KEY is required');
        const stripe = new Stripe(secretKey, {
          apiVersion: '2024-11-20.acacia',
        });
        
        const subscribeSchema = z.object({
          planId: z.string().min(1),
          customerId: z.string().min(1),
          successUrl: z.string().url(),
          cancelUrl: z.string().url(),
        });
        
        export async function POST(request: NextRequest) {
          try {
            const authSession = await getServerSession(authOptions);
            if (!authSession?.user) {
              return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
            }
            
            const body = await request.json();
            const result = subscribeSchema.safeParse(body);
            
            if (!result.success) {
              return NextResponse.json(
                { error: result.error.flatten() },
                { status: 400 }
              );
            }
            
            const { planId, customerId, successUrl, cancelUrl } = result.data;
            
            const plan = SUBSCRIPTION_PLANS[planId as keyof typeof SUBSCRIPTION_PLANS];
            if (!plan) {
              return NextResponse.json({ error: 'Invalid plan' }, { status: 400 });
            }
            
            const stripeSession = await stripe.checkout.sessions.create({
              mode: 'subscription',
              customer: customerId,
              line_items: [
                {
                  price: plan.priceId,
                  quantity: 1,
                },
              ],
              success_url: successUrl,
              cancel_url: cancelUrl,
              subscription_data: {
                trial_period_days: 14,
              },
            });
            
            return NextResponse.json({ sessionId: stripeSession.id });
          } catch (error: unknown) {
            const message = error instanceof Error ? error.message : 'Unknown error';
            console.error('Subscription error:', message);
            return NextResponse.json(
              { error: 'Failed to create subscription' },
              { status: 500 }
            );
          }
        }

Manage Subscriptions

precision_write:
  files:
    - path: "src/app/api/subscription/manage/route.ts"
      content: |
        import { NextRequest, NextResponse } from 'next/server';
        import Stripe from 'stripe';
        import { getServerSession } from 'next-auth';
        import { authOptions } from '@/lib/auth';
        
        const secretKey = process.env.STRIPE_SECRET_KEY;
        if (!secretKey) throw new Error('STRIPE_SECRET_KEY is required');
        const stripe = new Stripe(secretKey, {
          apiVersion: '2024-11-20.acacia',
        });
        
        // Cancel subscription
        export async function DELETE(request: NextRequest) {
          try {
            const authSession = await getServerSession(authOptions);
            if (!authSession?.user) {
              return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
            }
            
            const { subscriptionId } = await request.json();
            
            const subscription = await stripe.subscriptions.update(subscriptionId, {
              cancel_at_period_end: true,
            });
            
            return NextResponse.json({ subscription });
          } catch (error: unknown) {
            const message = error instanceof Error ? error.message : 'Unknown error';
            console.error('Cancel error:', message);
            return NextResponse.json(
              { error: 'Failed to cancel subscription' },
              { status: 500 }
            );
          }
        }
        
        // Update subscription
        export async function PATCH(request: NextRequest) {
          try {
            const authSession = await getServerSession(authOptions);
            if (!authSession?.user) {
              return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
            }
            
            const { subscriptionId, newPriceId } = await request.json();
            
            const subscription = await stripe.subscriptions.retrieve(subscriptionId);
            
            const updated = await stripe.subscriptions.update(subscriptionId, {
              items: [
                {
                  id: subscription.items.data[0].id,
                  price: newPriceId,
                },
              ],
              proration_behavior: 'create_prorations',
            });
            
            return NextResponse.json({ subscription: updated });
          } catch (error: unknown) {
            const message = error instanceof Error ? error.message : 'Unknown error';
            console.error('Update error:', message);
            return NextResponse.json(
              { error: 'Failed to update subscription' },
              { status: 500 }
            );
          }
        }

6. Webhook Handling

Webhooks are critical for payment processing. They notify your application of payment events.

Stripe Webhook Handler

precision_write:
  files:
    - path: "src/app/api/webhooks/stripe/route.ts"
      content: |
        import { NextRequest, NextResponse } from 'next/server';
        import Stripe from 'stripe';
        import { headers } from 'next/headers';
        import { db } from '@/lib/db';
        
        const secretKey = process.env.STRIPE_SECRET_KEY;
        if (!secretKey) throw new Error('STRIPE_SECRET_KEY is required');
        const stripe = new Stripe(secretKey, {
          apiVersion: '2024-11-20.acacia',
        });
        
        const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET;
        if (!webhookSecret) {
          throw new Error('STRIPE_WEBHOOK_SECRET is required');
        }
        
        export async function POST(request: NextRequest) {
          const body = await request.text();
          const headersList = await headers();
          const signature = headersList.get('stripe-signature');
          
          if (!signature) {
            return NextResponse.json(
              { error: 'Missing stripe-signature header' },
              { status: 400 }
            );
          }
          
          let event: Stripe.Event;
          
          try {
            // Verify webhook signature
            event = stripe.webhooks.constructEvent(body, signature, webhookSecret);
          } catch (error: unknown) {
            const message = error instanceof Error ? error.message : 'Unknown error';
            console.error('Webhook signature verification failed:', message);
            return NextResponse.json(
              { error: 'Invalid signature' },
              { status: 400 }
            );
          }
          
          // Handle the event
          try {
            switch (event.type) {
              case 'checkout.session.completed': {
                const session = event.data.object as Stripe.Checkout.Session;
                await handleCheckoutComplete(session);
                break;
              }
                
              case 'customer.subscription.created': {
                const subscription = event.data.object as Stripe.Subscription;
                await handleSubscriptionCreated(subscription);
                break;
              }
                
              case 'customer.subscription.updated':
                await handleSubscriptionUpdated(event.data.object as Stripe.Subscription);
                break;
                
              case 'customer.subscription.deleted':
                await handleSubscriptionCanceled(event.data.object as Stripe.Subscription);
                break;
                
              case 'invoice.payment_succeeded':
                await handlePaymentSucceeded(event.data.object as Stripe.Invoice);
                break;
                
              case 'invoice.payment_failed':
                await handlePaymentFailed(event.data.object as Stripe.Invoice);
                break;
                
              default:
                // Replace with structured logger in production
                console.log(`Unhandled event type: ${event.type}`);
            }
            
            return NextResponse.json({ received: true });
          } catch (error: unknown) {
            const message = error instanceof Error ? error.message : 'Unknown error';
            console.error('Webhook handler error:', message);
            return NextResponse.json(
              { error: 'Webhook handler failed' },
              { status: 500 }
            );
          }
        }
        
        async function handleCheckoutComplete(session: Stripe.Checkout.Session) {
          // Update database with payment details
          await db.payment.create({
            data: {
              id: session.payment_intent as string,
              userId: session.metadata?.userId,
              amount: session.amount_total ?? 0,
              currency: session.currency ?? 'usd',
              status: 'succeeded',
            },
          });
          // Grant access to product/service based on metadata
        }
        
        async function handleSubscriptionCreated(subscription: Stripe.Subscription) {
          // Create subscription record in database
          await db.subscription.create({
            data: {
              id: subscription.id,
              userId: subscription.metadata?.userId,
              status: subscription.status,
              currentPeriodEnd: new Date(subscription.current_period_end * 1000),
            },
          });
        }
        
        async function handleSubscriptionUpdated(subscription: Stripe.Subscription) {
          // Update subscription status in database
          await db.subscription.update({
            where: { id: subscription.id },
            data: {
              status: subscription.status,
              currentPeriodEnd: new Date(subscription.current_period_end * 1000),
            },
          });
        }
        
        async function handleSubscriptionCanceled(subscription: Stripe.Subscription) {
          // Mark subscription as canceled in database
          await db.subscription.update({
            where: { id: subscription.id },
            data: {
              status: 'canceled',
              canceledAt: new Date(),
            },
          });
          // Revoke access at period end
        }
        
        async function handlePaymentSucceeded(invoice: Stripe.Invoice) {
          // Record successful payment
          await db.payment.create({
            data: {
              id: invoice.payment_intent as string,
              userId: invoice.subscription_details?.metadata?.userId,
              amount: invoice.amount_paid,
              currency: invoice.currency,
              status: 'succeeded',
            },
          });
        }
        
        async function handlePaymentFailed(invoice: Stripe.Invoice) {
          // Notify user of failed payment
          await db.payment.create({
            data: {
              id: invoice.payment_intent as string,
              userId: invoice.subscription_details?.metadata?.userId,
              amount: invoice.amount_due,
              currency: invoice.currency,
              status: 'failed',
            },
          });
          // Send notification email
        }

LemonSqueezy Webhook Handler

precision_write:
  files:
    - path: "src/app/api/webhooks/lemonsqueezy/route.ts"
      content: |
        import { NextRequest, NextResponse } from 'next/server';
        import crypto from 'crypto';
        import { db } from '@/lib/db';
        
        const webhookSecret = process.env.LEMONSQUEEZY_WEBHOOK_SECRET;
        if (!webhookSecret) {
          throw new Error('LEMONSQUEEZY_WEBHOOK_SECRET is required');
        }
        
        export async function POST(request: NextRequest) {
          const body = await request.text();
          const signature = request.headers.get('x-signature');
          
          if (!signature) {
            return NextResponse.json({ error: 'Missing signature' }, { status: 400 });
          }
          
          // Verify webhook signature
          const hmac = crypto.createHmac('sha256', webhookSecret);
          const digest = hmac.update(body).digest('hex');
          
          const signatureBuffer = Buffer.from(signature, 'utf8');
          const digestBuffer = Buffer.from(digest, 'utf8');
          if (signatureBuffer.length !== digestBuffer.length || !crypto.timingSafeEqual(signatureBuffer, digestBuffer)) {
            console.error('Webhook signature verification failed');
            return NextResponse.json({ error: 'Invalid signature' }, { status: 400 });
          }
          
          const event = JSON.parse(body);
          
          try {
            switch (event.meta.event_name) {
              case 'order_created':
                await handleOrderCreated(event.data);
                break;
                
              case 'subscription_created':
                await handleSubscriptionCreated(event.data);
                break;
                
              case 'subscription_updated':
                await handleSubscriptionUpdated(event.data);
                break;
                
              case 'subscription_cancelled':
                await handleSubscriptionCancelled(event.data);
                break;
                
              case 'subscription_payment_success':
                await handlePaymentSuccess(event.data);
                break;
                
              default:
                // Replace with structured logger in production
                console.log(`Unhandled event: ${event.meta.event_name}`);
            }
            
            return NextResponse.json({ received: true });
          } catch (error: unknown) {
            const message = error instanceof Error ? error.message : 'Unknown error';
            console.error('Webhook handler error:', message);
            return NextResponse.json(
              { error: 'Webhook handler failed' },
              { status: 500 }
            );
          }
        }
        
        interface LemonSqueezyWebhookData {
          id: string;
          attributes: Record<string, unknown>;
        }
        
        async function handleOrderCreated(data: LemonSqueezyWebhookData) {
          await db.order.create({
            data: {
              id: data.id,
              status: 'completed',
              attributes: data.attributes,
            },
          });
        }
        
        async function handleSubscriptionCreated(data: LemonSqueezyWebhookData) {
          await db.subscription.create({
            data: {
              id: data.id,
              status: 'active',
              userId: data.attributes.user_id as string,
              attributes: data.attributes,
            },
          });
        }
        
        async function handleSubscriptionUpdated(data: LemonSqueezyWebhookData) {
          await db.subscription.update({
            where: { id: data.id },
            data: {
              status: data.attributes.status as string,
              attributes: data.attributes,
            },
          });
        }
        
        async function handleSubscriptionCancelled(data: LemonSqueezyWebhookData) {
          await db.subscription.update({
            where: { id: data.id },
            data: {
              status: 'cancelled',
              cancelledAt: new Date(),
            },
          });
        }
        
        async function handlePaymentSuccess(data: LemonSqueezyWebhookData) {
          await db.payment.create({
            data: {
              id: data.id,
              status: 'succeeded',
              amount: data.attributes.total as number,
              attributes: data.attributes,
            },
          });
        }

Webhook Idempotency

Always implement idempotency to handle duplicate webhook deliveries:

precision_write:
  files:
    - path: "src/lib/webhooks/idempotency.ts"
      content: |
        import { db } from '@/lib/db';
        
        export async function isProcessed(eventId: string): Promise<boolean> {
          const existing = await db.webhookEvent.findUnique({
            where: { id: eventId },
          });
          
          return !!existing;
        }
        
        export async function markProcessed(eventId: string): Promise<void> {
          await db.webhookEvent.create({
            data: {
              id: eventId,
              processedAt: new Date(),
            },
          });
        }
        
        export async function withIdempotency<T>(
          eventId: string,
          handler: () => Promise<T>
        ): Promise<T | null> {
          // Use database transaction to prevent TOCTOU race condition
          return db.$transaction(async (tx) => {
            const existing = await tx.webhookEvent.findUnique({
              where: { id: eventId },
            });
            
            if (existing) {
              // Replace with structured logger in production
              console.log(`Event ${eventId} already processed, skipping`);
              return null;
            }
            
            const result = await handler();
            
            await tx.webhookEvent.create({
              data: {
                id: eventId,
                processedAt: new Date(),
              },
            });
            
            return result;
          });
        }

Update webhook handlers to use idempotency:

// In Stripe webhook
const eventId = event.id;
await withIdempotency(eventId, async () => {
  // Handle event
});

7. Testing Payment Flows

Use Test Mode Keys

Always use test mode keys in development:

precision_grep:
  queries:
    - id: check-test-keys
      pattern: "(sk_test|pk_test)"
      path: ".env"
  output:
    format: files_only

Stripe CLI for Webhook Testing

Install and configure Stripe CLI:

precision_exec:
  commands:
    - cmd: "stripe listen --forward-to localhost:3000/api/webhooks/stripe"
  background: true
  verbosity: minimal

Test Card Numbers

Document test card numbers in development docs:

precision_write:
  files:
    - path: "docs/testing-payments.md"
      content: |
        # Payment Testing Guide
        
        ## Test Cards (Stripe)
        
        - Success: 4242 4242 4242 4242
        - Decline: 4000 0000 0000 0002
        - Requires authentication: 4000 0025 0000 3155
        - Insufficient funds: 4000 0000 0000 9995
        
        Use any future expiry date and any 3-digit CVC.
        
        ## Test Webhooks
        
        1. Start webhook listener: `stripe listen --forward-to localhost:3000/api/webhooks/stripe`
        2. Trigger events: `stripe trigger payment_intent.succeeded`
        
        ## LemonSqueezy Testing
        
        Use sandbox mode in .env:
        LEMONSQUEEZY_API_KEY=... (sandbox key)

Automated Testing

Create tests for webhook handlers:

precision_write:
  files:
    - path: "src/__tests__/webhooks/stripe.test.ts"
      content: |
        import { POST } from '@/app/api/webhooks/stripe/route';
        import { NextRequest } from 'next/server';
        import Stripe from 'stripe';
        
        describe('Stripe Webhook Handler', () => {
          it('should verify webhook signature', async () => {
            const mockEvent = {
              id: 'evt_test_123',
              type: 'checkout.session.completed',
              data: { object: {} },
            };
            
            const request = new NextRequest('http://localhost:3000/api/webhooks/stripe', {
              method: 'POST',
              body: JSON.stringify(mockEvent),
              headers: {
                'stripe-signature': 'invalid_signature',
              },
            });
            
            const response = await POST(request);
            expect(response.status).toBe(400);
          });
          
          it('should handle checkout.session.completed', async () => {
            // Test event handling
          });
        });

8. Security and PCI Compliance

Never Handle Card Data Directly

Use hosted checkout pages or Elements to keep card data out of your servers:

precision_grep:
  queries:
    - id: check-card-handling
      pattern: "(card_number|cvv|cvc|card.*exp)"
      glob: "src/**/*.{ts,js,tsx,jsx}"
  output:
    format: files_only

If any matches are found, refactor to use provider's hosted solutions.

Enforce HTTPS

precision_write:
  files:
    - path: "src/middleware.ts"
      content: |
        import { NextRequest, NextResponse } from 'next/server';
        
        export function middleware(request: NextRequest) {
          // Enforce HTTPS in production
          if (
            process.env.NODE_ENV === 'production' &&
            request.headers.get('x-forwarded-proto') !== 'https'
          ) {
            return NextResponse.redirect(
              `https://${request.headers.get('host')}${request.nextUrl.pathname}`,
              301
            );
          }
          
          return NextResponse.next();
        }
        
        export const config = {
          matcher: '/api/checkout/:path*',
        };

Secure API Keys

Verify API keys are not hardcoded:

precision_grep:
  queries:
    - id: hardcoded-keys
      pattern: "(sk_live|sk_test)_[a-zA-Z0-9]{24,}"
      glob: "src/**/*.{ts,js,tsx,jsx}"
  output:
    format: files_only

If found, move to environment variables immediately.

Content Security Policy

Add CSP headers for payment pages:

precision_write:
  files:
    - path: "next.config.js"
      mode: overwrite
      content: |
        module.exports = {
          async headers() {
            return [
              {
                source: '/(checkout|subscribe)/:path*',
                headers: [
                  {
                    key: 'Content-Security-Policy',
                    value: [
                      "default-src 'self'",
                      "script-src 'self' 'unsafe-inline' https://js.stripe.com",
                      "frame-src https://js.stripe.com",
                      "connect-src 'self' https://api.stripe.com",
                    ].join('; '),
                  },
                ],
              },
            ];
          },
        };

9. Validation

Run the validation script to ensure best practices:

precision_exec:
  commands:
    - cmd: "bash plugins/goodvibes/skills/outcome/payment-integration/scripts/validate-payments.sh ."
      expect:
        exit_code: 0
  verbosity: standard

The script checks:

Payment library installation
API keys in .env.example (not .env)
Webhook endpoint exists
Webhook signature verification
No hardcoded secrets
HTTPS enforcement
Error handling

10. Database Schema for Payments

Add payment tracking to your database:

model Customer {
  id              String   @id @default(cuid())
  userId          String   @unique
  stripeCustomerId String?  @unique
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
  
  subscriptions   Subscription[]
  payments        Payment[]
  
  @@index([stripeCustomerId])
}

model Subscription {
  id                   String   @id @default(cuid())
  customerId           String
  customer             Customer @relation(fields: [customerId], references: [id])
  stripeSubscriptionId String   @unique
  stripePriceId        String
  status               String
  currentPeriodEnd     DateTime
  cancelAtPeriodEnd    Boolean  @default(false)
  createdAt            DateTime @default(now())
  updatedAt            DateTime @updatedAt
  
  @@index([customerId])
  @@index([status])
}

model Payment {
  id              String   @id @default(cuid())
  customerId      String
  customer        Customer @relation(fields: [customerId], references: [id])
  stripePaymentId String   @unique
  amount          Int
  currency        String
  status          String
  createdAt       DateTime @default(now())
  
  @@index([customerId])
  @@index([status])
}

model WebhookEvent {
  id          String   @id
  processedAt DateTime @default(now())
  
  @@index([processedAt])
}

Common Patterns

Pattern: Proration on Plan Changes

When upgrading/downgrading subscriptions:

const updated = await stripe.subscriptions.update(subscriptionId, {
  items: [{ id: itemId, price: newPriceId }],
  proration_behavior: 'create_prorations', // Credit/charge immediately
});

Pattern: Trial Periods

Offer free trials:

const session = await stripe.checkout.sessions.create({
  mode: 'subscription',
  subscription_data: {
    trial_period_days: 14,
    trial_settings: {
      end_behavior: {
        missing_payment_method: 'cancel', // Cancel if no payment method
      },
    },
  },
});

Pattern: Webhook Retry Logic

Payment providers retry failed webhooks. Always:

Return 200 OK quickly (process async if needed)
Implement idempotency
Log all webhook events

Pattern: Failed Payment Recovery

Handle dunning (failed payment recovery):

case 'invoice.payment_failed':
  const invoice = event.data.object as Stripe.Invoice;
  if (invoice.attempt_count >= 3) {
    // Cancel subscription after 3 failures
    await stripe.subscriptions.cancel(invoice.subscription as string);
    await notifyCustomer(invoice.customer as string, 'payment_failed_final');
  } else {
    await notifyCustomer(invoice.customer as string, 'payment_failed_retry');
  }
  break;

Anti-Patterns to Avoid

DON'T: Store Card Details

Never store card numbers, CVV, or full card data. Use tokenization.

DON'T: Skip Webhook Verification

Always verify webhook signatures. Unverified webhooks are a security risk.

DON'T: Use Client-Side Pricing

Never trust prices from the client. Always use server-side price lookup:

// BAD
const { amount } = await request.json();
await stripe.charges.create({ amount });

// GOOD
const { priceId } = await request.json();
const price = await stripe.prices.retrieve(priceId);
await stripe.charges.create({ amount: price.unit_amount });

DON'T: Ignore Failed Webhooks

Monitor webhook delivery and investigate failures. Set up alerts.

DON'T: Hardcode Currency

Support multiple currencies if serving international customers:

const session = await stripe.checkout.sessions.create({
  currency: userCountry === 'US' ? 'usd' : 'eur',
});

References

See references/payment-patterns.md for:

Provider comparison table
Complete webhook event reference
Subscription lifecycle state machine
Testing strategies
Security checklist

Next Steps

After implementing payment integration:

Test thoroughly - Use test mode, simulate failures
Monitor webhooks - Set up logging and alerting
Document flows - Create internal docs for payment processes
Plan for scale - Consider rate limits, concurrent webhooks
Implement analytics - Track conversion rates, churn
Review compliance - Ensure PCI-DSS compliance if applicable
Set up monitoring - Track payment success rates, errors