Setting up Stripe with the boilerplate requires configuring your Stripe account, retrieving API keys, and setting up webhook endpoints. This setup applies to both payment systems (Better Auth and Custom Boilerplate).
Universal Setup: This configuration works for both Better Auth's external checkout and the Custom Boilerplate's advanced checkout methods.
Perfect for: Getting your payment system up and running quickly with proper webhook configuration and security for either payment approach.
pk_test_ or pk_live_)sk_test_ or sk_live_)price_) for your plansAdd your Stripe configuration to .env.local:
# Stripe Test Configuration
STRIPE_SECRET_KEY="sk_test_51A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2W3X4Y5Z6A7B8C9D0E1F2"
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_51A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2W3X4Y5Z6A7B8C9D0"
# Webhook Secret (configured later)
STRIPE_WEBHOOK_SECRET="whsec_1234567890abcdef..."
# Checkout Configuration
NEXT_PUBLIC_STRIPE_CHECKOUT_TYPE="EmbededForm"Test Mode: Use test keys (starting with sk_test_ and pk_test_) during development.
The boilerplate includes a pre-configured Stripe client in src/lib/stripe/stripe-client.ts:
// From src/lib/stripe/stripe-client.ts
import 'server-only'
import Stripe from 'stripe'
import { env } from '@/env'
export const stripeClient = new Stripe(env.STRIPE_SECRET_KEY, {
apiVersion: '2025-07-30.basil',
})API Version: The boilerplate uses Stripe API version 2025-07-30.basil for the latest features and compatibility.
Webhooks are essential for real-time payment event processing:
Set your webhook URL based on your environment:
Development:
https://your-ngrok-url.ngrok.io/api/auth/stripe/webhook
Production:
https://yourdomain.com/api/auth/stripe/webhook
Add these essential events for subscription management:
customer.subscription.created
customer.subscription.updated
customer.subscription.deleted
invoice.payment_succeeded
invoice.payment_failed
checkout.session.completed
whsec_)STRIPE_WEBHOOK_SECRETFor local development, use the Stripe CLI:
# Install Stripe CLI
# macOS: brew install stripe/stripe-cli/stripe
# Windows: scoop install stripe
# Linux: Download from https://github.com/stripe/stripe-cli
# Login to your account
stripe login
# Forward webhooks to local server
stripe listen --forward-to localhost:3000/api/auth/stripe/webhook
# Copy the webhook secret from the output
# Your webhook signing secret is whsec_1234567890abcdef...Development tip: The Stripe CLI automatically provides a webhook secret when forwarding events. Use this secret in your STRIPE_WEBHOOK_SECRET environment variable during development.
Webhook Endpoint: Both payment systems use the same webhook endpoint /api/auth/stripe/webhook but process events differently based on metadata.
Custom Boilerplate System Only: This configuration applies only if you're using the Custom Boilerplate checkout system. Better Auth uses external Stripe checkout automatically.
Choose your preferred checkout method with the NEXT_PUBLIC_STRIPE_CHECKOUT_TYPE environment variable:
NEXT_PUBLIC_STRIPE_CHECKOUT_TYPE="EmbededForm"Benefits:
Use when: You want the smoothest user experience
Verify your Stripe configuration:
# Start your development server
npm run dev
# Check the console for Stripe initialization
# Should see no errors about missing keysEnsure all required variables are set:
STRIPE_SECRET_KEYNEXT_PUBLIC_STRIPE_PUBLISHABLE_KEYSTRIPE_WEBHOOK_SECRETNEXT_PUBLIC_STRIPE_CHECKOUT_TYPEStripe configured! Your payment system is now ready to process payments with secure webhook handling and your chosen checkout method.