Stripe & Payments

The boilerplate provides TWO DISTINCT PAYMENT SYSTEMS to handle different business needs: Better Auth's external checkout for simplicity, and a comprehensive custom checkout system for advanced scenarios.

Important: These are two separate systems with different capabilities. Choose the one that best fits your business requirements.

Two Payment Systems Overview

External Checkout Only

Stripe-hosted checkout pages (external redirect)
Customer portal for subscription management
Authenticated users only
Automatic customer & subscription management
Zero configuration required

Best for: Simple SaaS with standard subscription needs

Perfect for: Choose Better Auth for simplicity or Custom System for advanced features like guest checkout, installments, coupons, and multiple checkout methods.

System Architecture Comparison

Simple External Flow:

User Login → Better Auth Plugin → Stripe External Checkout → Customer Portal

Features:

External Stripe checkout only
Stripe customer portal for management
Authenticated users required
Automatic webhook processing
Zero custom checkout code

Limitations:

No guest checkout
No custom checkout UI
No installment payments
No coupon integration

Advanced Multi-Method Flow:

Any User → Custom Checkout Components → 4 Checkout Methods → Custom Webhooks

Features:

4 checkout methods (Embedded/External/React/Links)
Guest checkout with auto-account creation
Payment installments (split payments)
Coupon code support
One-time or subscription payments
Multi-seat subscriptions

Advanced capabilities:

Custom webhook processing
Flexible user flows
Conversion optimization

System Selection: Better Auth uses external Stripe checkout exclusively, while the Custom System detects checkout type via metadata (source: 'custom_checkout', guest_checkout: 'true') for intelligent routing.

System Components Breakdown

Automatic Integration

Better Auth Stripe plugin (src/lib/better-auth/auth.ts)
External Stripe checkout (redirect only)
Customer portal integration
Automatic webhook processing

User Flow:

User must be authenticated
Redirects to Stripe checkout
Returns to success page
Manages subscription via Stripe portal

Quick Setup Guide

Configure Stripe Keys

Set up your Stripe environment variables in .env.local:

# Stripe Configuration
STRIPE_SECRET_KEY="sk_test_your_stripe_secret_key"
STRIPE_WEBHOOK_SECRET="whsec_your_webhook_secret"
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_your_publishable_key"

# Checkout Method
NEXT_PUBLIC_STRIPE_CHECKOUT_TYPE="EmbededForm"

Choose Checkout Method

Select your preferred checkout experience:

EmbededForm - Integrated forms (recommended)
ExternalForm - Stripe-hosted pages
ReactStripeForm - Custom React integration
PaymentLink - Simple payment links

Configure Plans

Create your subscription plans in the admin panel at /admin/plansSubscription Plans Interface: Stripe subscription plans selection interface

Stripe subscription plans selection interface

Test Payments

Use Stripe test cards to verify your payment flow

Environment Variables

Required Stripe configuration for the payment system:

# Server-side (Required)
STRIPE_SECRET_KEY="sk_test_..." # or sk_live_... for production
STRIPE_WEBHOOK_SECRET="whsec_..." # From Stripe Dashboard

# Client-side (Required)
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_..." # or pk_live_...
NEXT_PUBLIC_STRIPE_CHECKOUT_TYPE="EmbededForm" # See checkout methods

# Optional
NEXT_PUBLIC_BILLING_MODE="subscription" # or "oneTime"

System Feature Comparison

🔌

Better Auth System

External checkout only

✅

Zero configuration setup

✅

Automatic customer creation

✅

Stripe customer portal

✅

Real-time webhook sync

❌

Guest checkout support

❌

Custom checkout UI

❌

Payment installments

❌

Coupon integration

🎯

Custom Boilerplate System

Complete checkout suite

✅

4 checkout methods

✅

Guest checkout + auto-account

✅

Payment installments (split)

✅

Coupon code support

✅

One-time or subscriptions

✅

Multi-seat subscriptions

✅

Custom webhook processing

✅

Conversion optimization

Which System Should You Choose?

Choose Better Auth System if:

You want zero configuration
Simple subscription model is sufficient
Users can create accounts before purchasing
You prefer Stripe-hosted checkout pages
You don't need custom checkout flows

Choose Custom Boilerplate System if:

You need guest checkout (no account required)
You want to optimize conversion rates
You need payment installments (BNPL)
You want coupon/discount support
You need multiple checkout methods
You require custom checkout UI/UX

Pro Tip: You can start with Better Auth for simplicity and migrate to the Custom System later if you need advanced features like guest checkout or installments.

Stripe & Payments Topics

⚙️

Payment system ready! Your application has enterprise-grade payment processing with flexible checkout options and comprehensive subscription management.