Stripe Overview

Vibestacks comes with a complete Stripe integration for subscription billing, powered by Better Auth's Stripe plugin. This gives you production-ready payment infrastructure out of the box.

What's Included

• Subscription management - Create, upgrade, downgrade, and cancel subscriptions
• Multiple pricing plans - Configure free, starter, pro, and enterprise tiers
• Annual & monthly billing - Built-in support for billing intervals with discounts
• Free trials - Optional trial periods with automatic conversion
• Stripe Checkout - Secure, hosted payment pages (no PCI compliance hassle)
• Customer portal - Let users manage their own billing and payment methods
• Webhook handling - Automatic processing of Stripe events
• Type-safe configuration - All plans defined in a single config file

Config-Driven Design

Everything is controlled from a single file: config/app.ts. Toggle features on/off without touching implementation code.

export const stripeConfig = {
  enabled: true,                    // Toggle entire Stripe integration
  createCustomerOnSignUp: true,     // Auto-create Stripe customer
  
  plans: [
    { name: "free", priceId: null, /* ... */ },
    { name: "starter", trial: null, /* ... */ },           // No trial
    { name: "pro", trial: { enabled: true, days: 14 }, /* ... */ },  // 14-day trial
  ],
}

Want to disable trials? Set trial: null. Want 5 plans? Add them to the array. Want to disable Stripe entirely while you build? Set enabled: false. The UI adapts automatically.

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                        Your App                              │
├─────────────────────────────────────────────────────────────┤
│  config/app.ts          │  Pricing Page        │  Dashboard │
│  └─ stripeConfig        │  └─ PricingSection   │  └─ Billing│
│     └─ plans[]          │     └─ PricingCard   │            │
├─────────────────────────────────────────────────────────────┤
│                    lib/auth.ts                               │
│                    └─ Better Auth + Stripe Plugin            │
├─────────────────────────────────────────────────────────────┤
│                    lib/auth-client.ts                        │
│                    └─ subscription.upgrade()                 │
│                    └─ subscription.cancel()                  │
│                    └─ subscription.list()                    │
├─────────────────────────────────────────────────────────────┤
│                       Stripe API                             │
│  └─ Checkout Sessions  └─ Subscriptions  └─ Customer Portal │
└─────────────────────────────────────────────────────────────┘

How It Works

1. User clicks "Subscribe" on your pricing page
2. Client calls subscription.upgrade() which creates a Stripe Checkout session
3. User is redirected to Stripe Checkout to enter payment details
4. After payment, Stripe sends a webhook to your app
5. Better Auth processes the webhook and creates the subscription in your database
6. User is redirected back to your success URL with an active subscription

Key Files

Quick Start

If you're setting up Stripe for the first time:

1. Create a Stripe account (if you don't have one)
2. Get your API keys from the Stripe Dashboard
3. Follow the Configuration guide to set up your environment
4. Create your products and prices in Stripe Dashboard
5. Update your Plans & Pricing configuration

Test vs Live Mode

Stripe has two modes:

• Test mode - Use test API keys (sk_test_xxx) for development. No real charges.
• Live mode - Use live API keys (sk_live_xxx) for production. Real money.

Common Test Cards

Use any future expiry date and any 3-digit CVC.

FAQ

Next Steps

• Configuration - Set up API keys and webhooks
• Plans & Pricing - Configure your subscription tiers
• Trials - Set up free trial periods