tomevault-io 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
Converted and distributed by TomeVault — claim your Tome and manage your conversions.