medy-gribkov Stripe Payments Integration
Secure payment flows with webhook handling, idempotency, and SCA support.
Checkout Sessions
BAD: Client-side price, no idempotency
// ❌ Trusting client data, XSS risk
app.post('/checkout', async (req, res) => {
const { priceId, amount } = req.body; // Never trust client
const session = await stripe.checkout.sessions.create({
line_items: [{ price: priceId, quantity: 1 }],
success_url: req.body.successUrl, // XSS risk
});
res.json({ url: session.url });
});
GOOD: Server-side price lookup, idempotency, metadata
import Stripe from 'stripe';
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
apiVersion: '2024-12-18.acacia',
});
app.post('/checkout', async (req, res) => {
const { productId, userId } = req.body;
const prices = await stripe.prices.list({ product: productId, active: true });
if (!prices.data.length) return res.status(400).json({ error: 'Invalid product' });
const session = await stripe.checkout.sessions.create({
line_items: [{ price: prices.data[0].id, quantity: 1 }],
mode: 'payment',
success_url: `${process.env.BASE_URL}/success?session_id={CHECKOUT_SESSION_ID}`,
cancel_url: `${process.env.BASE_URL}/cancel`,
metadata: { userId, productId },
}, {
idempotencyKey: `checkout_${userId}_${productId}_${Date.now()}`,
});
res.json({ url: session.url });
});
Payment Intents with SCA
BAD: Deprecated Charges API, no 3D Secure
// ❌ Deprecated, no SCA support
app.post('/charge', async (req, res) => {
await stripe.charges.create({
amount: req.body.amount,
source: req.body.token, // Deprecated
});
});
GOOD: Payment Intent with automatic SCA, React Elements
// Server-side
app.post('/payment-intent', async (req, res) => {
const order = await db.orders.findUnique({ where: { id: req.body.orderId } });
if (!order) return res.status(404).json({ error: 'Order not found' });
const paymentIntent = await stripe.paymentIntents.create({
amount: order.totalCents,
currency: 'usd',
automatic_payment_methods: { enabled: true },
metadata: { orderId: order.id },
}, { idempotencyKey: `pi_${order.id}` });
res.json({ clientSecret: paymentIntent.client_secret });
});
// Client-side React
import { Elements, PaymentElement, useStripe, useElements } from '@stripe/react-stripe-js';
function CheckoutForm() {
const stripe = useStripe();
const elements = useElements();
return (
<form (e) => {
e.preventDefault();
if (!stripe || !elements) return;
await stripe.confirmPayment({
elements,
confirmParams: { return_url: `${window.location.origin}/complete` },
});
}}>
<PaymentElement />
<button disabled={!stripe}>Pay</button>
</form>
);
}
Subscriptions
BAD: Duplicate customers, no proration
// ❌ Creates duplicate customers
app.post('/subscribe', async (req, res) => {
const customer = await stripe.customers.create({ email: req.body.email });
const sub = await stripe.subscriptions.create({ customer: customer.id, items: [{ price: req.body.priceId }] });
res.json(sub);
});
GOOD: Idempotent customer, trials, proration
async function subscribe(userId: string, priceId: string, trialDays?: number) {
const user = await db.users.findUnique({ where: { id: userId } });
const customer = user.stripeCustomerId
? await stripe.customers.retrieve(user.stripeCustomerId) as Stripe.Customer
: await stripe.customers.create(
{ email: user.email, metadata: { userId } },
{ idempotencyKey: `customer_${userId}` }
);
if (!user.stripeCustomerId) {
await db.users.update({ where: { id: userId }, data: { stripeCustomerId: customer.id } });
}
return await stripe.subscriptions.create({
customer: customer.id,
items: [{ price: priceId }],
trial_period_days: trialDays,
payment_settings: { save_default_payment_method: 'on_subscription' },
metadata: { userId },
}, { idempotencyKey: `sub_${userId}_${priceId}` });
}
// Upgrade/downgrade with proration
async function changePlan(subId: string, newPriceId: string) {
const sub = await stripe.subscriptions.retrieve(subId);
return await stripe.subscriptions.update(subId, {
items: [{ id: sub.items.data[0].id, price: newPriceId }],
proration_behavior: 'create_prorations',
});
}
Webhook Verification (Critical)
BAD: No signature verification
// ❌ CRITICAL SECURITY FLAW
app.post('/webhook', async (req, res) => {
const event = req.body;
await fulfillOrder(event.data.object.metadata.orderId); // Attacker-controlled!
});
GOOD: Signature verification, idempotent processing
import { buffer } from 'micro';
export const config = { api: { bodyParser: false } }; // Next.js
export default async function webhook(req, res) {
const buf = await buffer(req);
const sig = req.headers['stripe-signature']!;
let event: Stripe.Event;
try {
event = stripe.webhooks.constructEvent(buf, sig, process.env.STRIPE_WEBHOOK_SECRET!);
} catch (err) {
return res.status(400).send(`Webhook Error: ${err.message}`);
}
// Idempotency check
const existing = await db.webhookEvents.findUnique({ where: { stripeEventId: event.id } });
if (existing) return res.json({ received: true, duplicate: true });
await db.webhookEvents.create({ data: { stripeEventId: event.id, type: event.type } });
switch (event.type) {
case 'payment_intent.succeeded':
await handlePayment(event.data.object as Stripe.PaymentIntent);
break;
case 'customer.subscription.updated':
await syncSubscription(event.data.object as Stripe.Subscription);
break;
}
res.json({ received: true });
}
Customer Portal and Refunds
// Self-service billing portal
app.post('/portal', async (req, res) => {
const user = await db.users.findUnique({ where: { id: req.body.userId } });
if (!user?.stripeCustomerId) return res.status(400).json({ error: 'No customer' });
const session = await stripe.billingPortal.sessions.create({
customer: user.stripeCustomerId,
return_url: `${process.env.BASE_URL}/account`,
});
res.json({ url: session.url });
});
// Refunds with idempotency
async function refund(paymentIntentId: string) {
return await stripe.refunds.create({
payment_intent: paymentIntentId,
}, { idempotencyKey: `refund_${paymentIntentId}` });
}
// Cancel subscription
async function cancelSub(subId: string, immediately = false) {
return immediately
? await stripe.subscriptions.cancel(subId)
: await stripe.subscriptions.update(subId, { cancel_at_period_end: true });
}
Error Handling
BAD: Generic errors, no retry
// ❌ No error specificity
try {
await stripe.paymentIntents.create({ /* ... */ });
} catch (err) {
res.status(500).json({ error: 'Something went wrong' });
}
GOOD: Type-specific errors with retry logic
async function createPayment(params: Stripe.PaymentIntentCreateParams, retries = 3) {
for (let i = 0; i < retries; i++) {
try {
return await stripe.paymentIntents.create(params, {
idempotencyKey: params.metadata?.orderId,
});
} catch (err) {
if (err instanceof Stripe.errors.StripeCardError) {
throw new Error(`Card declined: ${err.message}`); // Don't retry
} else if (err instanceof Stripe.errors.StripeRateLimitError) {
if (i < retries - 1) {
await new Promise(r => setTimeout(r, 1000 * (i + 1)));
continue;
}
} else if (err instanceof Stripe.errors.StripeAuthenticationError) {
throw new Error('Invalid API key'); // Don't retry
}
throw err;
}
}
throw new Error('Payment failed after retries');
}
Testing
// Test cards
const TEST_CARDS = {
success: '4242424242424242',
declined: '4000000000000002',
requiresAuth: '4000002500003155', // 3D Secure
insufficientFunds: '4000000000009995',
};
// Test clocks for subscription testing
async function createTestClock(customerId: string) {
const clock = await stripe.testHelpers.testClocks.create({
frozen_time: Math.floor(Date.now() / 1000),
});
await stripe.customers.update(customerId, { test_clock: clock.id });
return clock;
}
// Advance time
async function advanceTime(clockId: string, days: number) {
const clock = await stripe.testHelpers.testClocks.retrieve(clockId);
return await stripe.testHelpers.testClocks.advance(clockId, {
frozen_time: clock.frozen_time + (days * 86400),
});
}
Configuration
# .env.local
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
// Validate on startup
if (!process.env.STRIPE_SECRET_KEY) throw new Error('STRIPE_SECRET_KEY required');
if (!process.env.STRIPE_WEBHOOK_SECRET) console.warn('Webhooks will fail without STRIPE_WEBHOOK_SECRET');
const isTestMode = process.env.STRIPE_SECRET_KEY.startsWith('sk_test_');
console.log(`Stripe: ${isTestMode ? 'TEST' : 'LIVE'} mode`);