Stripe Setup

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.

Stripe Account Setup

1

Create Stripe Account

  1. Go to stripe.com and create an account
  2. Complete the verification process
  3. Access your dashboard at dashboard.stripe.com
2

Retrieve API Keys

  1. Navigate to Developers → API Keys
  2. Copy your Publishable key (starts with pk_test_ or pk_live_)
  3. Reveal and copy your Secret key (starts with sk_test_ or sk_live_)
  4. Keep these keys secure - never commit them to version control
3

Configure Products and Prices

  1. Go to Products in your Stripe dashboard
  2. Create your products and pricing plans
  3. Note the Price IDs (starts with price_) for your plans
  4. These will be used in your plan configuration

Environment Configuration

Add 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.

Stripe Client Configuration

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.

Webhook Configuration

Webhooks are essential for real-time payment event processing:

Create Webhook Endpoint

1

Access Webhook Settings

  1. In your Stripe dashboard, go to Developers → Webhooks
  2. Click Add endpoint
2

Configure Endpoint URL

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
3

Select Events

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
4

Get Webhook Secret

  1. After creating the webhook, click on it
  2. In the Signing secret section, click Reveal
  3. Copy the secret (starts with whsec_)
  4. Add it to your environment variables as STRIPE_WEBHOOK_SECRET

Local Development Webhooks

For 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.

Checkout Method Configuration (Custom System Only)

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:
  • Best user experience (no redirect)
  • Full customization control
  • Faster checkout process
  • Mobile-optimized
Use when: You want the smoothest user experience

Verification Checklist

1

Test API Connection

Verify your Stripe configuration:
# Start your development server
npm run dev

# Check the console for Stripe initialization
# Should see no errors about missing keys
2

Test Webhook Delivery

  1. Trigger a test event in your Stripe dashboard
  2. Check your application logs for webhook processing
  3. Verify events are being received and processed
3

Validate Environment Variables

Ensure all required variables are set:
  • ✅ STRIPE_SECRET_KEY
  • ✅ NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY
  • ✅ STRIPE_WEBHOOK_SECRET
  • ✅ NEXT_PUBLIC_STRIPE_CHECKOUT_TYPE
Stripe configured! Your payment system is now ready to process payments with secure webhook handling and your chosen checkout method.
    Stripe Setup | ShipSaaS Documentation | ShipSaaS - Launch your SaaS with AI in days