July 21, 2025
19 min read
Stripe has revolutionized online payments by providing developers with robust, secure, and easy-to-implement payment processing solutions. Combined with Next.js, a powerful React framework known for its performance and developer experience, you can create seamless payment flows that scale with your business needs.
This comprehensive guide will take you through every aspect of integrating Stripe Checkout with Next.js, from basic setup to advanced features like webhook handling, subscription management, and production deployment strategies. Whether you're building an e-commerce platform, SaaS application, or marketplace, this tutorial provides the foundation for secure, scalable payment processing.
Before implementing Stripe Checkout with Next.js, ensure your development environment meets these requirements:
Essential Tools:
Stripe Account Setup: Create a Stripe account at stripe.com and familiarize yourself with the dashboard. You'll need access to:
Next.js Project Foundation: Start with a fresh Next.js project or use an existing one:
npx create-next-app@latest stripe-checkout-app
cd stripe-checkout-app
npm install
Create a robust environment configuration that supports both development and production:
# .env.local
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
NEXT_PUBLIC_APP_URL=http://localhost:3000
DATABASE_URL=your_database_connection_string
Environment Variables Best Practices:
NEXT_PUBLIC_ prefix only for client-side variablesUnderstanding the complete payment flow is crucial for proper implementation:
Client-Side Flow:
Server-Side Flow:
Design your data structure to support payment tracking:
// Example database schema
const PaymentSession = {
id: 'uuid',
userId: 'string',
stripeSessionId: 'string',
amount: 'number',
currency: 'string',
status: 'pending | completed | failed',
productId: 'string',
createdAt: 'timestamp',
updatedAt: 'timestamp'
};
const Product = {
id: 'uuid',
name: 'string',
description: 'text',
price: 'number',
currency: 'string',
stripePriceId: 'string',
isActive: 'boolean'
};
Install the comprehensive Stripe package suite:
npm install stripe @stripe/stripe-js @stripe/react-stripe-js
npm install --save-dev @types/stripe-v3 # For TypeScript projects
Package Overview:
Create a centralized Stripe configuration service:
// lib/stripe.js
import Stripe from 'stripe';
import { loadStripe } from '@stripe/stripe-js';
// Server-side Stripe instance
export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY, {
apiVersion: '2023-10-16',
typescript: true,
});
// Client-side Stripe promise
let stripePromise;
export const getStripe = () => {
if (!stripePromise) {
stripePromise = loadStripe(process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY);
}
return stripePromise;
};
// Configuration constants
export const CURRENCY = 'usd';
export const MIN_AMOUNT = 50; // $0.50 minimum
export const MAX_AMOUNT = 500000; // $5,000 maximum
Configure Stripe with advanced options for production readiness:
// lib/stripe-config.js
export const stripeConfig = {
apiVersion: '2023-10-16',
maxNetworkRetries: 3,
timeout: 20000,
telemetry: false, // Disable for privacy
typescript: true,
stripeAccount: process.env.STRIPE_ACCOUNT_ID, // For Connect platforms
};
export const checkoutSessionDefaults = {
payment_method_types: ['card', 'apple_pay', 'google_pay'],
billing_address_collection: 'required',
shipping_address_collection: {
allowed_countries: ['US', 'CA', 'GB', 'AU'],
},
allow_promotion_codes: true,
automatic_tax: { enabled: true },
customer_creation: 'always',
};
Create a robust API endpoint for checkout session creation:
// pages/api/checkout/session.js
import { stripe } from '../../../lib/stripe';
import { validateCartItems } from '../../../lib/cart-validation';
export default async function handler(req, res) {
if (req.method !== 'POST') {
res.setHeader('Allow', 'POST');
return res.status(405).end('Method Not Allowed');
}
try {
const { items, customerId, metadata = {} } = req.body;
// Validate request data
const validation = await validateCartItems(items);
if (!validation.valid) {
return res.status(400).json({
error: 'Invalid cart items',
details: validation.errors
});
}
// Calculate total and prepare line items
const lineItems = items.map(item => ({
price_data: {
currency: 'usd',
product_data: {
name: item.name,
description: item.description,
images: item.images || [],
metadata: {
productId: item.id,
category: item.category,
},
},
unit_amount: Math.round(item.price * 100), // Convert to cents
},
quantity: item.quantity,
adjustable_quantity: {
enabled: true,
minimum: 1,
maximum: 10,
},
}));
// Create checkout session
const session = await stripe.checkout.sessions.create({
payment_method_types: ['card', 'apple_pay', 'google_pay'],
line_items: lineItems,
mode: 'payment',
customer: customerId || undefined,
customer_creation: customerId ? undefined : 'always',
billing_address_collection: 'required',
shipping_address_collection: {
allowed_countries: ['US', 'CA', 'GB'],
},
allow_promotion_codes: true,
automatic_tax: { enabled: true },
success_url: `${req.headers.origin}/success?session_id={CHECKOUT_SESSION_ID}`,
cancel_url: `${req.headers.origin}/cart`,
metadata: {
userId: req.user?.id || 'anonymous',
cartId: metadata.cartId,
source: 'web_checkout',
...metadata,
},
expires_at: Math.floor(Date.now() / 1000) + (30 * 60), // 30 minutes
});
// Log session creation for monitoring
console.log(`Checkout session created: ${session.id}`, {
amount: session.amount_total,
currency: session.currency,
customer: session.customer,
});
res.status(200).json({ sessionId: session.id });
} catch (error) {
console.error('Checkout session creation failed:', error);
res.status(500).json({
error: 'Failed to create checkout session',
message: process.env.NODE_ENV === 'development' ? error.message : 'Internal server error'
});
}
}
Handle subscription-based payments with recurring billing:
// pages/api/checkout/subscription.js
import { stripe } from '../../../lib/stripe';
export default async function handler(req, res) {
if (req.method !== 'POST') {
res.setHeader('Allow', 'POST');
return res.status(405).end('Method Not Allowed');
}
try {
const { priceId, customerId, trialDays = 0 } = req.body;
// Validate price exists and is active
const price = await stripe.prices.retrieve(priceId);
if (!price.active) {
return res.status(400).json({ error: 'Price is not active' });
}
const sessionConfig = {
payment_method_types: ['card'],
mode: 'subscription',
line_items: [
{
price: priceId,
quantity: 1,
},
],
success_url: `${req.headers.origin}/dashboard?session_id={CHECKOUT_SESSION_ID}`,
cancel_url: `${req.headers.origin}/pricing`,
customer: customerId,
customer_creation: customerId ? undefined : 'always',
allow_promotion_codes: true,
billing_address_collection: 'required',
metadata: {
priceId,
planType: price.nickname || 'standard',
},
};
// Add trial period if specified
if (trialDays > 0) {
sessionConfig.subscription_data = {
trial_period_days: trialDays,
metadata: {
trial_days: trialDays.toString(),
},
};
}
const session = await stripe.checkout.sessions.create(sessionConfig);
res.status(200).json({
sessionId: session.id,
subscriptionId: session.subscription
});
} catch (error) {
console.error('Subscription checkout failed:', error);
res.status(500).json({ error: 'Failed to create subscription checkout' });
}
}
Create a sophisticated checkout button with loading states and error handling:
// components/CheckoutButton.jsx
import { useState } from 'react';
import { getStripe } from '../lib/stripe';
import { useAuth } from '../hooks/useAuth';
const CheckoutButton = ({
items,
customerId = null,
className = '',
children = 'Checkout',
disabled = false,
onSuccess = () => {},
onError = () => {},
}) => {
const [loading, setLoading] = useState(false);
const [error, setError] = useState(null);
const { user } = useAuth();
const handleCheckout = async () => {
try {
setLoading(true);
setError(null);
// Validate items before proceeding
if (!items || items.length === 0) {
throw new Error('No items in cart');
}
// Create checkout session
const response = await fetch('/api/checkout/session', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
items,
customerId: customerId || user?.stripeCustomerId,
metadata: {
userId: user?.id,
source: 'checkout_button',
},
}),
});
const data = await response.json();
if (!response.ok) {
throw new Error(data.error || 'Failed to create checkout session');
}
// Redirect to Stripe Checkout
const stripe = await getStripe();
const { error: stripeError } = await stripe.redirectToCheckout({
sessionId: data.sessionId,
});
if (stripeError) {
throw stripeError;
}
onSuccess(data);
} catch (err) {
console.error('Checkout error:', err);
setError(err.message);
onError(err);
} finally {
setLoading(false);
}
};
return (
<div className="checkout-button-container">
<button
onClick={handleCheckout}
disabled={disabled || loading}
className={`checkout-button ${className} ${loading ? 'loading' : ''}`}
aria-label={loading ? 'Processing...' : 'Proceed to checkout'}
>
{loading ? (
<div className="flex items-center space-x-2">
<div className="spinner" />
<span>Processing...</span>
</div>
) : (
children
)}
</button>
{error && (
<div className="error-message mt-2 text-red-600 text-sm">
{error}
</div>
)}
</div>
);
};
export default CheckoutButton;
Build a complete shopping cart with Stripe integration:
// components/ShoppingCart.jsx
import { useState, useEffect } from 'react';
import CheckoutButton from './CheckoutButton';
import { formatCurrency } from '../utils/format';
const ShoppingCart = () => {
const [cartItems, setCartItems] = useState([]);
const [total, setTotal] = useState(0);
useEffect(() => {
// Load cart from localStorage or API
const savedCart = JSON.parse(localStorage.getItem('cart') || '[]');
setCartItems(savedCart);
calculateTotal(savedCart);
}, []);
const calculateTotal = (items) => {
const sum = items.reduce((acc, item) => acc + (item.price * item.quantity), 0);
setTotal(sum);
};
const updateQuantity = (productId, newQuantity) => {
if (newQuantity === 0) {
removeItem(productId);
return;
}
const updatedCart = cartItems.map(item =>
item.id === productId ? { ...item, quantity: newQuantity } : item
);
setCartItems(updatedCart);
calculateTotal(updatedCart);
localStorage.setItem('cart', JSON.stringify(updatedCart));
};
const removeItem = (productId) => {
const updatedCart = cartItems.filter(item => item.id !== productId);
setCartItems(updatedCart);
calculateTotal(updatedCart);
localStorage.setItem('cart', JSON.stringify(updatedCart));
};
if (cartItems.length === 0) {
return (
<div className="empty-cart text-center py-8">
<h2 className="text-2xl font-semibold mb-4">Your cart is empty</h2>
<p className="text-gray-600">Add some items to get started!</p>
</div>
);
}
return (
<div className="shopping-cart max-w-4xl mx-auto p-6">
<h2 className="text-2xl font-bold mb-6">Shopping Cart</h2>
<div className="cart-items space-y-4 mb-6">
{cartItems.map((item) => (
<div key={item.id} className="cart-item flex items-center justify-between p-4 border rounded-lg">
<div className="item-info flex items-center space-x-4">
{item.image && (
<img src={item.image} alt={item.name} className="w-16 h-16 object-cover rounded" />
)}
<div>
<h3 className="font-semibold">{item.name}</h3>
<p className="text-gray-600 text-sm">{item.description}</p>
<p className="font-medium">{formatCurrency(item.price)}</p>
</div>
</div>
<div className="item-controls flex items-center space-x-3">
<div className="quantity-controls flex items-center space-x-2">
<button
onClick={() => updateQuantity(item.id, item.quantity - 1)}
className="quantity-btn w-8 h-8 flex items-center justify-center border rounded"
disabled={item.quantity <= 1}
>
-
</button>
<span className="w-8 text-center">{item.quantity}</span>
<button
onClick={() => updateQuantity(item.id, item.quantity + 1)}
className="quantity-btn w-8 h-8 flex items-center justify-center border rounded"
>
+
</button>
</div>
<button
onClick={() => removeItem(item.id)}
className="remove-btn text-red-600 hover:text-red-800"
>
Remove
</button>
</div>
</div>
))}
</div>
<div className="cart-summary border-t pt-6">
<div className="total-amount text-right mb-4">
<p className="text-xl font-semibold">
Total: {formatCurrency(total)}
</p>
</div>
<CheckoutButton
items={cartItems}
className="w-full bg-blue-600 text-white py-3 px-6 rounded-lg font-medium hover:bg-blue-700 transition-colors"
onSuccess={() => {
// Clear cart on successful checkout initiation
localStorage.removeItem('cart');
setCartItems([]);
setTotal(0);
}}
>
Proceed to Checkout ({formatCurrency(total)})
</CheckoutButton>
</div>
</div>
);
};
export default ShoppingCart;
Create comprehensive success and error handling pages:
// pages/success.js
import { useEffect, useState } from 'react';
import { useRouter } from 'next/router';
import Link from 'next/link';
export default function Success() {
const router = useRouter();
const { session_id } = router.query;
const [session, setSession] = useState(null);
const [loading, setLoading] = useState(true);
const [error, setError] = useState(null);
useEffect(() => {
if (session_id) {
fetchSessionDetails();
}
}, [session_id]);
const fetchSessionDetails = async () => {
try {
const response = await fetch(`/api/checkout/session/${session_id}`);
const data = await response.json();
if (response.ok) {
setSession(data);
} else {
setError(data.error);
}
} catch (err) {
setError('Failed to load payment details');
} finally {
setLoading(false);
}
};
if (loading) {
return (
<div className="success-page flex items-center justify-center min-h-screen">
<div className="text-center">
<div className="spinner mb-4" />
<p>Loading payment details...</p>
</div>
</div>
);
}
if (error) {
return (
<div className="success-page max-w-md mx-auto mt-16 p-6 text-center">
<div className="error-icon mb-4">❌</div>
<h1 className="text-2xl font-bold text-red-600 mb-2">Error</h1>
<p className="text-gray-600 mb-6">{error}</p>
<Link href="/" className="btn btn-primary">
Return Home
</Link>
</div>
);
}
return (
<div className="success-page max-w-2xl mx-auto mt-16 p-6">
<div className="text-center mb-8">
<div className="success-icon text-6xl mb-4">✅</div>
<h1 className="text-3xl font-bold text-green-600 mb-2">
Payment Successful!
</h1>
<p className="text-gray-600">
Thank you for your purchase. Your order has been confirmed.
</p>
</div>
{session && (
<div className="order-details bg-gray-50 rounded-lg p-6 mb-6">
<h2 className="text-xl font-semibold mb-4">Order Details</h2>
<div className="order-info space-y-2">
<div className="flex justify-between">
<span>Order ID:</span>
<span className="font-mono">{session.id}</span>
</div>
<div className="flex justify-between">
<span>Amount Paid:</span>
<span className="font-semibold">
{formatCurrency(session.amount_total / 100, session.currency)}
</span>
</div>
<div className="flex justify-between">
<span>Payment Method:</span>
<span>{session.payment_method_types.join(', ')}</span>
</div>
{session.customer_email && (
<div className="flex justify-between">
<span>Email:</span>
<span>{session.customer_email}</span>
</div>
)}
</div>
</div>
)}
<div className="actions text-center space-x-4">
<Link href="/orders" className="btn btn-primary">
View Orders
</Link>
<Link href="/" className="btn btn-secondary">
Continue Shopping
</Link>
</div>
</div>
);
}
Create a comprehensive error page with recovery options:
// pages/payment/error.js
import { useEffect, useState } from 'react';
import { useRouter } from 'next/router';
import Link from 'next/link';
export default function PaymentError() {
const router = useRouter();
const { error_code, error_message } = router.query;
const [retryAttempts, setRetryAttempts] = useState(0);
const errorMessages = {
card_declined: 'Your card was declined. Please try a different payment method.',
expired_card: 'Your card has expired. Please use a different card.',
insufficient_funds: 'Insufficient funds. Please use a different payment method.',
processing_error: 'There was a processing error. Please try again.',
default: 'Payment failed. Please try again or contact support.',
};
const getErrorMessage = () => {
return errorMessages[error_code] || error_message || errorMessages.default;
};
const handleRetry = () => {
setRetryAttempts(prev => prev + 1);
router.push('/cart');
};
return (
<div className="error-page max-w-2xl mx-auto mt-16 p-6">
<div className="text-center mb-8">
<div className="error-icon text-6xl mb-4">❌</div>
<h1 className="text-3xl font-bold text-red-600 mb-2">
Payment Failed
</h1>
<p className="text-gray-600 mb-6">
{getErrorMessage()}
</p>
</div>
<div className="troubleshooting bg-yellow-50 border border-yellow-200 rounded-lg p-6 mb-6">
<h2 className="text-lg font-semibold mb-3">Troubleshooting Tips:</h2>
<ul className="space-y-2 text-sm">
<li>• Ensure your card has sufficient funds</li>
<li>• Check that your billing information is correct</li>
<li>• Try a different payment method</li>
<li>• Contact your bank if the problem persists</li>
</ul>
</div>
<div className="actions text-center space-x-4">
<button
onClick={handleRetry}
className="btn btn-primary"
disabled={retryAttempts >= 3}
>
{retryAttempts >= 3 ? 'Max Retries Reached' : 'Try Again'}
</button>
<Link href="/support" className="btn btn-secondary">
Contact Support
</Link>
<Link href="/" className="btn btn-outline">
Return Home
</Link>
</div>
{retryAttempts >= 3 && (
<div className="mt-6 p-4 bg-red-50 border border-red-200 rounded text-center">
<p className="text-red-700">
Multiple payment attempts failed. Please contact our support team for assistance.
</p>
</div>
)}
</div>
);
}
Create a robust webhook system to handle all Stripe events:
// pages/api/webhooks/stripe.js
import { stripe } from '../../../lib/stripe';
import { buffer } from 'micro';
import { processPaymentSuccess } from '../../../lib/payment-processor';
import { sendConfirmationEmail } from '../../../lib/email-service';
import { updateSubscriptionStatus } from '../../../lib/subscription-service';
export const config = {
api: {
bodyParser: false,
},
};
const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET;
export default async function webhookHandler(req, res) {
if (req.method !== 'POST') {
res.setHeader('Allow', 'POST');
return res.status(405).end('Method Not Allowed');
}
const sig = req.headers['stripe-signature'];
const buf = await buffer(req);
let event;
try {
event = stripe.webhooks.constructEvent(buf.toString(), sig, webhookSecret);
} catch (err) {
console.error(`Webhook signature verification failed: ${err.message}`);
return res.status(400).send(`Webhook Error: ${err.message}`);
}
console.log(`Received webhook: ${event.type}`);
try {
switch (event.type) {
case 'checkout.session.completed':
await handleCheckoutSessionCompleted(event.data.object);
break;
case 'payment_intent.succeeded':
await handlePaymentSucceeded(event.data.object);
break;
case 'payment_intent.payment_failed':
await handlePaymentFailed(event.data.object);
break;
case 'customer.subscription.created':
case 'customer.subscription.updated':
case 'customer.subscription.deleted':
await handleSubscriptionChange(event.data.object, event.type);
break;
case 'invoice.payment_succeeded':
await handleInvoicePaymentSucceeded(event.data.object);
break;
case 'invoice.payment_failed':
await handleInvoicePaymentFailed(event.data.object);
break;
case 'customer.created':
await handleCustomerCreated(event.data.object);
break;
default:
console.log(`Unhandled event type: ${event.type}`);
}
res.status(200).json({ received: true, event: event.type });
} catch (error) {
console.error(`Webhook processing failed: ${error.message}`);
res.status(500).json({ error: 'Webhook processing failed' });
}
}
async function handleCheckoutSessionCompleted(session) {
console.log(`Processing completed checkout session: ${session.id}`);
try {
// Process the successful payment
await processPaymentSuccess({
sessionId: session.id,
customerId: session.customer,
amountTotal: session.amount_total,
currency: session.currency,
paymentStatus: session.payment_status,
metadata: session.metadata,
});
// Send confirmation email
if (session.customer_email) {
await sendConfirmationEmail({
email: session.customer_email,
sessionId: session.id,
amount: session.amount_total,
currency: session.currency,
});
}
// Update inventory if applicable
if (session.metadata.updateInventory === 'true') {
await updateInventoryFromSession(session);
}
console.log(`Successfully processed checkout session: ${session.id}`);
} catch (error) {
console.error(`Failed to process checkout session ${session.id}:`, error);
throw error;
}
}
async function handleSubscriptionChange(subscription, eventType) {
console.log(`Processing subscription ${eventType}: ${subscription.id}`);
await updateSubscriptionStatus({
subscriptionId: subscription.id,
customerId: subscription.customer,
status: subscription.status,
currentPeriodStart: subscription.current_period_start,
currentPeriodEnd: subscription.current_period_end,
cancelAtPeriodEnd: subscription.cancel_at_period_end,
eventType,
});
// Handle specific subscription events
switch (eventType) {
case 'customer.subscription.created':
await handleNewSubscription(subscription);
break;
case 'customer.subscription.deleted':
await handleCancelledSubscription(subscription);
break;
}
}
async function handlePaymentFailed(paymentIntent) {
console.log(`Payment failed: ${paymentIntent.id}`);
// Notify customer of failed payment
if (paymentIntent.receipt_email) {
await sendPaymentFailedEmail({
email: paymentIntent.receipt_email,
paymentIntentId: paymentIntent.id,
amount: paymentIntent.amount,
currency: paymentIntent.currency,
});
}
// Update internal records
await updatePaymentStatus({
paymentIntentId: paymentIntent.id,
status: 'failed',
failureReason: paymentIntent.last_payment_error?.message,
});
}
Implement dynamic pricing with promotional codes:
// lib/pricing-engine.js
export class PricingEngine {
constructor() {
this.discountRules = new Map();
this.loadDiscountRules();
}
async calculatePrice(items, promoCode = null, customerId = null) {
let subtotal = items.reduce((sum, item) => sum + (item.price * item.quantity), 0);
let discounts = [];
let taxes = 0;
// Apply customer-specific discounts
if (customerId) {
const customerDiscount = await this.getCustomerDiscount(customerId);
if (customerDiscount) {
discounts.push(customerDiscount);
subtotal *= (1 - customerDiscount.percentage / 100);
}
}
// Apply promotional codes
if (promoCode) {
const promoDiscount = await this.validatePromoCode(promoCode);
if (promoDiscount.valid) {
discounts.push(promoDiscount);
subtotal = this.applyPromoDiscount(subtotal, promoDiscount);
}
}
// Calculate taxes
taxes = subtotal * 0.08; // 8% tax rate (simplified)
return {
subtotal: Math.round(subtotal * 100) / 100,
discounts,
taxes: Math.round(taxes * 100) / 100,
total: Math.round((subtotal + taxes) * 100) / 100,
};
}
async validatePromoCode(code) {
// Check database for valid promo codes
const promo = await this.getPromoCode(code);
if (!promo) {
return { valid: false, error: 'Invalid promo code' };
}
if (promo.expiresAt < new Date()) {
return { valid: false, error: 'Promo code has expired' };
}
if (promo.usageCount >= promo.maxUsage) {
return { valid: false, error: 'Promo code usage limit reached' };
}
return {
valid: true,
code: promo.code,
type: promo.type, // 'percentage' or 'fixed'
value: promo.value,
description: promo.description,
};
}
applyPromoDiscount(amount, discount) {
if (discount.type === 'percentage') {
return amount * (1 - discount.value / 100);
} else if (discount.type === 'fixed') {
return Math.max(0, amount - discount.value);
}
return amount;
}
}
Implement comprehensive multi-currency handling:
// lib/currency-handler.js
import { stripe } from './stripe';
export class CurrencyHandler {
constructor() {
this.supportedCurrencies = [
'usd', 'eur', 'gbp', 'cad', 'aud', 'jpy', 'cny'
];
this.exchangeRates = new Map();
this.loadExchangeRates();
}
async loadExchangeRates() {
try {
// Fetch current exchange rates from API
const response = await fetch('https://api.exchangerate-api.com/v4/latest/USD');
const data = await response.json();
Object.entries(data.rates).forEach(([currency, rate]) => {
this.exchangeRates.set(currency.toLowerCase(), rate);
});
} catch (error) {
console.error('Failed to load exchange rates:', error);
// Use fallback rates
this.loadFallbackRates();
}
}
convertPrice(amount, fromCurrency, toCurrency) {
if (fromCurrency === toCurrency) return amount;
const fromRate = this.exchangeRates.get(fromCurrency.toLowerCase()) || 1;
const toRate = this.exchangeRates.get(toCurrency.toLowerCase()) || 1;
// Convert to USD first, then to target currency
const usdAmount = amount / fromRate;
const convertedAmount = usdAmount * toRate;
return Math.round(convertedAmount * 100) / 100;
}
formatCurrency(amount, currency, locale = 'en-US') {
return new Intl.NumberFormat(locale, {
style: 'currency',
currency: currency.toUpperCase(),
}).format(amount);
}
async createLocalizedCheckoutSession(items, currency, country) {
// Adjust prices for local currency
const localizedItems = items.map(item => ({
...item,
price: this.convertPrice(item.price, 'usd', currency),
}));
// Create checkout session with localized settings
return await stripe.checkout.sessions.create({
payment_method_types: this.getPaymentMethodsForCountry(country),
line_items: localizedItems.map(item => ({
price_data: {
currency: currency.toLowerCase(),
product_data: {
name: item.name,
description: item.description,
},
unit_amount: Math.round(item.price * 100),
},
quantity: item.quantity,
})),
mode: 'payment',
success_url: `${process.env.NEXT_PUBLIC_APP_URL}/success?session_id={CHECKOUT_SESSION_ID}`,
cancel_url: `${process.env.NEXT_PUBLIC_APP_URL}/cart`,
automatic_tax: { enabled: true },
billing_address_collection: 'required',
shipping_address_collection: {
allowed_countries: [country],
},
});
}
getPaymentMethodsForCountry(country) {
const paymentMethods = {
US: ['card', 'apple_pay', 'google_pay'],
GB: ['card', 'apple_pay', 'google_pay', 'klarna'],
DE: ['card', 'apple_pay', 'google_pay', 'sofort', 'giropay'],
FR: ['card', 'apple_pay', 'google_pay', 'bancontact'],
// Add more countries as needed
};
return paymentMethods[country] || ['card'];
}
}
Implement comprehensive security measures:
// middleware/security.js
import rateLimit from 'express-rate-limit';
import helmet from 'helmet';
import { validateApiKey } from '../lib/auth';
// Rate limiting for checkout endpoints
export const checkoutRateLimit = rateLimit({
windowMs: 15 * 60 * 1000, // 15 minutes
max: 10, // Limit each IP to 10 requests per windowMs
message: 'Too many checkout attempts from this IP',
standardHeaders: true,
legacyHeaders: false,
});
// Webhook security middleware
export function webhookSecurity(req, res, next) {
// Validate webhook signature
const signature = req.headers['stripe-signature'];
if (!signature) {
return res.status(400).json({ error: 'Missing signature' });
}
// Additional IP validation for webhooks
const allowedIPs = [
'54.187.174.169',
'54.187.205.235',
'54.187.216.72',
// Add Stripe's webhook IPs
];
const clientIP = req.ip || req.connection.remoteAddress;
if (!allowedIPs.includes(clientIP)) {
console.warn(`Webhook from unauthorized IP: ${clientIP}`);
// In development, we might want to allow this
if (process.env.NODE_ENV === 'production') {
return res.status(403).json({ error: 'Unauthorized IP' });
}
}
next();
}
// Input validation for checkout sessions
export function validateCheckoutInput(req, res, next) {
const { items, customerId, metadata } = req.body;
// Validate items array
if (!Array.isArray(items) || items.length === 0) {
return res.status(400).json({ error: 'Invalid or empty items array' });
}
// Validate each item
for (const item of items) {
if (!item.name || typeof item.name !== 'string') {
return res.status(400).json({ error: 'Invalid item name' });
}
if (!item.price || typeof item.price !== 'number' || item.price <= 0) {
return res.status(400).json({ error: 'Invalid item price' });
}
if (!item.quantity || typeof item.quantity !== 'number' || item.quantity <= 0) {
return res.status(400).json({ error: 'Invalid item quantity' });
}
// Prevent price manipulation
if (item.price > 100000) { // $1000 max per item
return res.status(400).json({ error: 'Item price exceeds maximum allowed' });
}
}
// Validate customer ID format if provided
if (customerId && typeof customerId !== 'string') {
return res.status(400).json({ error: 'Invalid customer ID format' });
}
// Sanitize metadata
if (metadata && typeof metadata === 'object') {
for (const [key, value] of Object.entries(metadata)) {
if (typeof key !== 'string' || typeof value !== 'string') {
return res.status(400).json({ error: 'Invalid metadata format' });
}
}
}
next();
}
Create a robust testing environment:
// __tests__/checkout.test.js
import { render, screen, fireEvent, waitFor } from '@testing-library/react';
import CheckoutButton from '../components/CheckoutButton';
import { stripe } from '../lib/stripe';
// Mock Stripe
jest.mock('../lib/stripe', () => ({
getStripe: jest.fn(() => Promise.resolve({
redirectToCheckout: jest.fn(() => Promise.resolve({ error: null })),
})),
}));
// Mock fetch
global.fetch = jest.fn();
describe('CheckoutButton', () => {
beforeEach(() => {
fetch.mockClear();
});
test('handles successful checkout flow', async () => {
fetch.mockResolvedValueOnce({
ok: true,
json: async () => ({ sessionId: 'cs_test_123' }),
});
const mockItems = [
{ id: '1', name: 'Test Product', price: 10, quantity: 1 }
];
render(<CheckoutButton items={mockItems} />);
const button = screen.getByRole('button', { name: /checkout/i });
fireEvent.click(button);
await waitFor(() => {
expect(fetch).toHaveBeenCalledWith('/api/checkout/session', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
items: mockItems,
customerId: null,
metadata: { userId: undefined, source: 'checkout_button' },
}),
});
});
});
test('displays error message on checkout failure', async () => {
fetch.mockResolvedValueOnce({
ok: false,
json: async () => ({ error: 'Payment failed' }),
});
const mockItems = [
{ id: '1', name: 'Test Product', price: 10, quantity: 1 }
];
render(<CheckoutButton items={mockItems} />);
const button = screen.getByRole('button', { name: /checkout/i });
fireEvent.click(button);
await waitFor(() => {
expect(screen.getByText('Payment failed')).toBeInTheDocument();
});
});
test('disables button during loading', async () => {
fetch.mockImplementation(() => new Promise(() => {})); // Never resolves
const mockItems = [
{ id: '1', name: 'Test Product', price: 10, quantity: 1 }
];
render(<CheckoutButton items={mockItems} />);
const button = screen.getByRole('button');
fireEvent.click(button);
await waitFor(() => {
expect(button).toBeDisabled();
expect(screen.getByText('Processing...')).toBeInTheDocument();
});
});
});
Set up webhook testing with proper validation:
// __tests__/webhooks.test.js
import handler from '../pages/api/webhooks/stripe';
import { createMocks } from 'node-mocks-http';
import { stripe } from '../lib/stripe';
// Mock Stripe webhook construction
jest.mock('../lib/stripe', () => ({
stripe: {
webhooks: {
constructEvent: jest.fn(),
},
},
}));
describe('/api/webhooks/stripe', () => {
test('processes checkout.session.completed event', async () => {
const mockEvent = {
type: 'checkout.session.completed',
data: {
object: {
id: 'cs_test_123',
customer: 'cus_test_123',
amount_total: 1000,
currency: 'usd',
payment_status: 'paid',
customer_email: 'test@example.com',
metadata: {},
},
},
};
stripe.webhooks.constructEvent.mockReturnValue(mockEvent);
const { req, res } = createMocks({
method: 'POST',
headers: {
'stripe-signature': 'test_signature',
},
body: 'webhook_payload',
});
await handler(req, res);
expect(res._getStatusCode()).toBe(200);
expect(JSON.parse(res._getData())).toEqual({
received: true,
event: 'checkout.session.completed',
});
});
test('rejects invalid webhook signatures', async () => {
stripe.webhooks.constructEvent.mockImplementation(() => {
throw new Error('Invalid signature');
});
const { req, res } = createMocks({
method: 'POST',
headers: {
'stripe-signature': 'invalid_signature',
},
body: 'webhook_payload',
});
await handler(req, res);
expect(res._getStatusCode()).toBe(400);
expect(res._getData()).toContain('Webhook Error');
});
});
Configure your application for production deployment:
// next.config.js
const nextConfig = {
env: {
CUSTOM_KEY: process.env.CUSTOM_KEY,
},
headers: async () => [
{
source: '/api/:path*',
headers: [
{ key: 'X-Content-Type-Options', value: 'nosniff' },
{ key: 'X-Frame-Options', value: 'DENY' },
{ key: 'X-XSS-Protection', value: '1; mode=block' },
{ key: 'Referrer-Policy', value: 'strict-origin-when-cross-origin' },
],
},
],
async rewrites() {
return [
{
source: '/api/webhooks/stripe',
destination: '/api/webhooks/stripe',
},
];
},
};
module.exports = nextConfig;
Implement comprehensive monitoring:
// lib/monitoring.js
import { createLogger, format, transports } from 'winston';
export const logger = createLogger({
level: process.env.LOG_LEVEL || 'info',
format: format.combine(
format.timestamp(),
format.errors({ stack: true }),
format.json()
),
defaultMeta: { service: 'stripe-checkout' },
transports: [
new transports.File({ filename: 'logs/error.log', level: 'error' }),
new transports.File({ filename: 'logs/combined.log' }),
],
});
if (process.env.NODE_ENV !== 'production') {
logger.add(new transports.Console({
format: format.simple()
}));
}
// Payment event tracking
export function trackPaymentEvent(event, data) {
logger.info('Payment Event', {
event,
...data,
timestamp: new Date().toISOString(),
});
// Send to analytics service
if (process.env.ANALYTICS_ENDPOINT) {
fetch(process.env.ANALYTICS_ENDPOINT, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ event, data }),
}).catch(err => logger.error('Analytics tracking failed', err));
}
}
// Performance monitoring
export function measurePerformance(operation) {
return async (target, propertyKey, descriptor) => {
const originalMethod = descriptor.value;
descriptor.value = async function (...args) {
const start = Date.now();
try {
const result = await originalMethod.apply(this, args);
const duration = Date.now() - start;
logger.info('Performance Metric', {
operation,
duration,
success: true,
});
return result;
} catch (error) {
const duration = Date.now() - start;
logger.error('Performance Metric', {
operation,
duration,
success: false,
error: error.message,
});
throw error;
}
};
return descriptor;
};
}
Integrating Stripe Checkout with Next.js opens up powerful possibilities for creating seamless, secure payment experiences. This comprehensive guide has covered everything from basic setup to advanced features like webhook handling, multi-currency support, and production deployment strategies.
Robust Architecture: We've built a scalable payment system that handles error cases gracefully, implements proper security measures, and provides excellent user experience throughout the payment flow.
Security First: Every aspect of the implementation prioritizes security, from input validation and rate limiting to secure webhook handling and environment variable management.
Production Ready: The code examples include comprehensive error handling, logging, monitoring, and testing strategies that ensure your payment system performs reliably in production environments.
User Experience Focused: From loading states and error messages to success confirmations and retry mechanisms, every interaction is designed to provide clarity and confidence to your users.
Subscription Management: Handle recurring payments and subscription lifecycle events with sophisticated webhook processing and customer communication.
Multi-Currency Support: Implement global payment solutions with proper currency conversion, localized payment methods, and regional compliance considerations.
Comprehensive Testing: Ensure reliability with unit tests, integration tests, and webhook simulation that covers all critical payment flows.
Performance Optimization: Monitor and optimize payment performance with detailed logging, analytics integration, and performance measurement tools.
Always Validate on Server: Never trust client-side data when it comes to pricing and payment amounts. Always validate and calculate prices on your secure server.
Handle All Edge Cases: Payment flows have many potential failure points. Implement comprehensive error handling and provide clear user feedback for every scenario.
Monitor Everything: Payment systems require constant monitoring. Track success rates, error patterns, performance metrics, and user behavior to maintain optimal performance.
Stay Updated: Stripe regularly updates their APIs and adds new features. Stay current with their documentation and implement new capabilities that benefit your users.
As your application grows, consider these advanced topics:
The foundation you've built with this implementation can scale to handle millions of transactions while maintaining security, performance, and user experience standards that drive business success.
Start building with Stripe Checkout and Next.js today and experience the power of modern, scalable payment processing that grows with your business needs.
MTechZilla specializes in building scalable e-commerce and payment solutions with modern web technologies. Our expertise in Stripe integration, Next.js development, and payment system architecture helps businesses create secure, high-converting checkout experiences that drive revenue growth.
Since 2021, we’ve been empowering startups and growing companies with impactful web, mobile, and desktop applications across diverse industries.
Tell us about the project
sales@mtechzilla.com
Partner with us
partnership@mtechzilla.com
Drop your resume at
jobs@mtechzilla.com
