Dec 27, 2024
Building Scalable E-Commerce with Stripe: Payment Architecture for Growth
10 min · Stripe · E-Commerce · Payments · Architecture · Integration
Building Scalable E-Commerce with Stripe: Payment Architecture for Growth
Stripe has become the de facto standard for online payments. It handles complexity—PCI compliance, fraud prevention, payment methods, currencies—so you can focus on your business.
However, integrating Stripe into a scalable e-commerce platform requires thoughtful architecture. This guide covers production patterns used by companies processing billions in GMV.
Stripe Architecture Overview
A robust e-commerce payment system has these components:
┌─────────────────────────────────────┐
│ E-Commerce Frontend │
│ (Checkout Page, Payment Form) │
└────────────┬────────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ Stripe Elements / Payment Element │
│ (Client-side payment capture) │
└────────────┬────────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ Your Backend API │
│ (Create PaymentIntent, Confirm) │
└────────┬──────────────────────────┬──┘
│ │
▼ ▼
┌─────────────┐ ┌──────────────┐
│ Stripe API │ │ Webhooks │
│ (Sync) │ │ (Async) │
└──────┬──────┘ └──────┬───────┘
│ │
└───────────┬───────────┘
▼
┌────────────────────────┐
│ Database │
│ (Payments, Orders) │
└────────────────────────┘Setting Up Stripe
Install Dependencies
npm install stripe
npm install --save-dev @stripe/stripe-jsEnvironment Setup
# .env.local
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_your_key
STRIPE_SECRET_KEY=sk_live_your_key
STRIPE_WEBHOOK_SECRET=whsec_your_secretInitialize Stripe Client
import Stripe from 'stripe';
export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
apiVersion: '2024-12-10',
appInfo: {
name: 'My E-Commerce Store',
version: '1.0.0',
},
});Payment Intent Flow
The Payment Intent is Stripe's recommended approach for handling payments:
interface CreatePaymentIntentRequest {
orderId: string;
customerId: string;
amount: number;
currency: string;
email: string;
}
export async function createPaymentIntent(
request: CreatePaymentIntentRequest
): Promise<{ clientSecret: string; paymentIntentId: string }> {
try {
// Verify order exists and amount is correct
const order = await db.order.findUnique({
where: { id: request.orderId },
});
if (!order) {
throw new Error('Order not found');
}
if (order.totalAmount * 100 !== request.amount) {
throw new Error('Amount mismatch');
}
// Check for existing payment intent
const existingPayment = await db.payment.findUnique({
where: { orderId: request.orderId },
});
if (
existingPayment &&
existingPayment.status === 'succeeded'
) {
throw new Error('Order already paid');
}
// Create or update payment intent
let paymentIntent;
if (
existingPayment &&
existingPayment.stripePaymentIntentId
) {
// Update existing intent
paymentIntent = await stripe.paymentIntents.update(
existingPayment.stripePaymentIntentId,
{
amount: request.amount,
description: `Order ${request.orderId}`,
metadata: {
orderId: request.orderId,
customerId: request.customerId,
},
}
);
} else {
// Create new intent
paymentIntent = await stripe.paymentIntents.create({
amount: request.amount, // Amount in cents
currency: request.currency,
description: `Order ${request.orderId}`,
customer: request.customerId,
receipt_email: request.email,
metadata: {
orderId: request.orderId,
customerId: request.customerId,
},
// Automatic payment methods for modern wallets
automatic_payment_methods: {
enabled: true,
},
// Save payment method for future use
setup_future_usage: 'on_session',
});
}
// Store/update payment record
await db.payment.upsert({
where: { orderId: request.orderId },
create: {
orderId: request.orderId,
customerId: request.customerId,
stripePaymentIntentId: paymentIntent.id,
amount: request.amount,
currency: request.currency,
status: 'created',
metadata: paymentIntent.metadata,
},
update: {
stripePaymentIntentId: paymentIntent.id,
status: 'created',
},
});
return {
clientSecret: paymentIntent.client_secret!,
paymentIntentId: paymentIntent.id,
};
} catch (error) {
console.error('Payment intent creation failed:', error);
throw error;
}
}Frontend: Collecting Payment Details
Use Stripe Elements for secure payment collection:
// app/checkout/page.tsx
'use client';
import { loadStripe } from '@stripe/stripe-js';
import {
Elements,
PaymentElement,
useStripe,
useElements,
} from '@stripe/react-stripe-js';
import { useState } from 'react';
const stripePromise = loadStripe(
process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY!
);
export default function CheckoutPage() {
const [orderId, setOrderId] = useState<string>('');
return (
<div className="max-w-2xl mx-auto py-12">
<h1 className="text-3xl font-bold mb-8">Checkout</h1>
<Elements
stripe={stripePromise}
options={{
mode: 'payment',
amount: 5000, // $50.00 in cents
currency: 'usd',
appearance: {
theme: 'dark',
variables: {
colorPrimary: '#3b82f6',
},
},
}}
>
<CheckoutForm orderId={orderId} />
</Elements>
</div>
);
}
interface CheckoutFormProps {
orderId: string;
}
function CheckoutForm({ orderId }: CheckoutFormProps) {
const stripe = useStripe();
const elements = useElements();
const [loading, setLoading] = useState(false);
const [error, setError] = useState<string | null>(null);
const [processing, setProcessing] = useState(false);
const handleSubmit = async (e: React.FormEvent) => {
e.preventDefault();
if (!stripe || !elements) {
return;
}
setLoading(true);
setError(null);
try {
// Step 1: Create payment intent on backend
const response = await fetch('/api/checkout/create-payment-intent', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ orderId }),
});
if (!response.ok) {
throw new Error('Failed to create payment intent');
}
const { clientSecret } = await response.json();
// Step 2: Confirm payment with Stripe
setProcessing(true);
const result = await stripe.confirmPayment({
elements,
clientSecret,
confirmParams: {
return_url: `${window.location.origin}/checkout/success`,
},
});
if (result.error) {
setError(result.error.message || 'Payment failed');
} else if (result.paymentIntent?.status === 'succeeded') {
// Payment successful - redirect to success page
window.location.href = '/checkout/success';
}
} catch (err) {
setError(
err instanceof Error ? err.message : 'An error occurred'
);
} finally {
setLoading(false);
setProcessing(false);
}
};
return (
<form onSubmit={handleSubmit} className="space-y-6">
{/* Payment Element handles all payment methods */}
<PaymentElement />
{error && (
<div className="text-red-600 text-sm">
{error}
</div>
)}
<button
disabled={!stripe || processing || loading}
className="w-full bg-blue-600 hover:bg-blue-700 disabled:bg-gray-400 text-white font-bold py-3 rounded-lg transition"
>
{processing ? 'Processing...' : 'Pay Now'}
</button>
</form>
);
}Webhook Handling
Webhooks are critical for handling async payment events. Never rely solely on client-side confirmations:
// app/api/webhooks/stripe/route.ts
import { stripe } from '@/lib/stripe';
import { headers } from 'next/headers';
import { NextRequest, NextResponse } from 'next/server';
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: 'No signature' },
{ status: 400 }
);
}
let event: Stripe.Event;
try {
event = stripe.webhooks.constructEvent(
body,
signature,
process.env.STRIPE_WEBHOOK_SECRET!
);
} catch (err) {
console.error('Webhook signature verification failed:', err);
return NextResponse.json(
{ error: 'Signature verification failed' },
{ status: 400 }
);
}
try {
switch (event.type) {
case 'payment_intent.succeeded':
await handlePaymentSucceeded(
event.data.object as Stripe.PaymentIntent
);
break;
case 'payment_intent.payment_failed':
await handlePaymentFailed(
event.data.object as Stripe.PaymentIntent
);
break;
case 'charge.refunded':
await handleRefund(event.data.object as Stripe.Charge);
break;
case 'customer.subscription.updated':
await handleSubscriptionUpdated(
event.data.object as Stripe.Subscription
);
break;
case 'invoice.payment_succeeded':
await handleInvoicePaymentSucceeded(
event.data.object as Stripe.Invoice
);
break;
default:
console.log(`Unhandled event type: ${event.type}`);
}
return NextResponse.json({ received: true });
} catch (err) {
console.error('Webhook processing failed:', err);
// Return 500 so Stripe retries
return NextResponse.json(
{ error: 'Webhook processing failed' },
{ status: 500 }
);
}
}
async function handlePaymentSucceeded(
paymentIntent: Stripe.PaymentIntent
): Promise<void> {
const orderId = paymentIntent.metadata?.orderId;
if (!orderId) {
console.error('No orderId in payment intent metadata');
return;
}
// Update payment status
await db.payment.update({
where: { orderId },
data: {
status: 'succeeded',
stripePaymentIntentId: paymentIntent.id,
stripeChargeId:
typeof paymentIntent.charges.data[0] === 'string'
? paymentIntent.charges.data[0]
: paymentIntent.charges.data[0]?.id,
confirmedAt: new Date(),
},
});
// Update order status
await db.order.update({
where: { id: orderId },
data: {
status: 'paid',
paidAt: new Date(),
},
});
// Send confirmation email
const order = await db.order.findUnique({
where: { id: orderId },
include: { customer: true, items: true },
});
if (order) {
await sendOrderConfirmationEmail(order);
}
// Trigger fulfillment
await startFulfillmentProcess(orderId);
}
async function handlePaymentFailed(
paymentIntent: Stripe.PaymentIntent
): Promise<void> {
const orderId = paymentIntent.metadata?.orderId;
if (!orderId) {
console.error('No orderId in payment intent metadata');
return;
}
// Update payment status
await db.payment.update({
where: { orderId },
data: {
status: 'failed',
failureReason:
paymentIntent.last_payment_error?.message || 'Unknown error',
},
});
// Update order status
await db.order.update({
where: { id: orderId },
data: {
status: 'payment_failed',
},
});
// Notify customer
const order = await db.order.findUnique({
where: { id: orderId },
include: { customer: true },
});
if (order) {
await sendPaymentFailedEmail(
order.customer.email,
order
);
}
}
async function handleRefund(charge: Stripe.Charge): Promise<void> {
// Find associated order through payment
const payment = await db.payment.findUnique({
where: { stripeChargeId: charge.id },
});
if (!payment) {
console.warn(`No payment found for charge ${charge.id}`);
return;
}
// Create refund record
await db.refund.create({
data: {
orderId: payment.orderId,
amount: charge.amount_refunded,
stripeRefundId: charge.refunded ? charge.id : null,
reason: charge.metadata?.reason || 'Customer request',
processedAt: new Date(),
},
});
// Update order if fully refunded
if (charge.refunded === charge.amount) {
await db.order.update({
where: { id: payment.orderId },
data: { status: 'refunded' },
});
}
}Subscription Handling
For recurring payments:
interface CreateSubscriptionRequest {
customerId: string;
priceId: string;
paymentMethodId?: string;
trialDays?: number;
}
export async function createSubscription(
request: CreateSubscriptionRequest
): Promise<Stripe.Subscription> {
const subscription = await stripe.subscriptions.create({
customer: request.customerId,
items: [{ price: request.priceId }],
payment_settings: {
save_default_payment_method: 'on_subscription',
default_mandate_id: request.paymentMethodId,
},
trial_period_days: request.trialDays,
metadata: {
createdAt: new Date().toISOString(),
},
});
// Store subscription in database
await db.subscription.create({
data: {
stripeSubscriptionId: subscription.id,
customerId: request.customerId,
priceId: request.priceId,
status: subscription.status,
currentPeriodStart: new Date(
subscription.current_period_start * 1000
),
currentPeriodEnd: new Date(
subscription.current_period_end * 1000
),
},
});
return subscription;
}
export async function cancelSubscription(
subscriptionId: string,
immediate: boolean = false
): Promise<void> {
await stripe.subscriptions.update(subscriptionId, {
cancel_at_period_end: !immediate,
});
await db.subscription.update({
where: { stripeSubscriptionId: subscriptionId },
data: {
status: 'canceled',
canceledAt: new Date(),
},
});
}PCI Compliance
Stripe handles most PCI compliance, but you must:
- Never log sensitive data: No card numbers, CVVs, or authentication codes
- Use Stripe for payment processing: Never implement custom payment card handling
- Secure your API keys: Use environment variables, rotate regularly
- Implement HTTPS: All payment data must be encrypted in transit
- Validate data on backend: Don't trust client-side validation for payments
// Good: Never log sensitive payment data
const payment = await stripe.paymentIntents.retrieve(piId);
console.log('Payment status:', payment.status); // OK
// console.log('Card:', payment.payment_method); // NEVER do this
// Good: Validate amounts on backend before charging
const orderAmount = (await db.order.findUnique({ where: { id } }))
.totalAmount;
if (orderAmount * 100 !== paymentAmount) {
throw new Error('Amount mismatch - potential fraud');
}Fraud Prevention
Leverage Stripe's fraud tools:
// Enable Radar for fraud detection
const paymentIntent = await stripe.paymentIntents.create({
amount: 5000,
currency: 'usd',
radar_options: {
session: sessionId, // Track customer session
},
// Risk assessment rules
statement_descriptor: 'MY STORE',
});
// Handle declined charges
if (
paymentIntent.last_payment_error?.decline_code ===
'declined'
) {
// Potential fraud or insufficient funds
// Notify fraud team and customer
}Scaling Considerations
Rate Limiting: Stripe has rate limits. Implement exponential backoff:
async function stripeWithRetry<T>(
fn: () => Promise<T>,
maxRetries: number = 3
): Promise<T> {
for (let attempt = 0; attempt < maxRetries; attempt++) {
try {
return await fn();
} catch (error) {
if (
error instanceof Stripe.errors.RateLimitError &&
attempt < maxRetries - 1
) {
const delay = Math.pow(2, attempt) * 1000; // exponential backoff
await new Promise((resolve) => setTimeout(resolve, delay));
continue;
}
throw error;
}
}
throw new Error('Max retries exceeded');
}Idempotency: Always use idempotency keys for critical operations:
const paymentIntent = await stripe.paymentIntents.create(
{
amount: 5000,
currency: 'usd',
},
{
idempotencyKey: `order-${orderId}-${Date.now()}`,
}
);Analytics & Monitoring
Track payment metrics:
interface PaymentMetrics {
totalProcessed: number;
successRate: number;
averageAmount: number;
declinedTransactions: number;
refundRate: number;
avgProcessingTime: number;
}
async function getPaymentMetrics(
period: 'day' | 'week' | 'month'
): Promise<PaymentMetrics> {
const startDate = getStartDate(period);
const payments = await db.payment.findMany({
where: { createdAt: { gte: startDate } },
});
const successful = payments.filter(
(p) => p.status === 'succeeded'
).length;
const failed = payments.filter(
(p) => p.status === 'failed'
).length;
const refunded = payments.filter(
(p) => p.status === 'refunded'
).length;
return {
totalProcessed: successful + failed,
successRate: (successful / (successful + failed)) * 100,
averageAmount:
payments.reduce((sum, p) => sum + p.amount, 0) /
payments.length,
declinedTransactions: failed,
refundRate: (refunded / successful) * 100,
avgProcessingTime: 0, // Calculate from timestamps
};
}Conclusion
Stripe provides the infrastructure for processing payments reliably and securely. By implementing proper architecture patterns—Payment Intents, webhook handling, idempotency—you can build payment systems that scale to millions in transactions while maintaining security and reliability.
The key is treating payments as a critical system: monitor it obsessively, test thoroughly, and always have fallback strategies for failures.