Setup Stripe for Payments

Prerequisites

• A Stripe account
• The Stripe CLI installed for local webhook testing

1. Create Products and Prices

1. Go to Stripe Dashboard → Products
2. Create a product (e.g. "BetterStarter Core")
3. Add a one-time price for lifetime access (or a recurring price for subscriptions)
4. Copy the Product ID (prod_...) and Price ID (price_...)

2. Configure Environment Variables

Add the following to your .env.local:

# Stripe keys
STRIPE_SECRET_KEY=sk_test_xxxx
STRIPE_WEBHOOK_SECRET=whsec_xxxx

# Product and price IDs
VITE_STRIPE_PRODUCT_CORE_ID=prod_xxxx
VITE_STRIPE_PRICE_CORE_ONE_TIME_ID=price_xxxx

# Optional: auto-applied promotion code
VITE_STRIPE_PROMOTION_CODE_ID=promo_xxxx

3. Forward Webhooks Locally

Stripe sends events (payment completed, subscription updated, etc.) to your webhook endpoint. During development, use the Stripe CLI to forward these to your local server:

# Login to Stripe
stripe login

# Forward webhooks to your local server
stripe listen --forward-to localhost:3000/api/stripe/webhook

Copy the whsec_... signing secret from the CLI output and set it as STRIPE_WEBHOOK_SECRET in your .env.local.

4. Test a Purchase

1. Start the dev server and Stripe CLI webhook forwarding
2. Navigate to the pricing section on the homepage
3. Click the purchase button
4. Use the test card number 4242 4242 4242 4242 with any future expiry and any CVC
5. After checkout, you'll be redirected to /purchase/success

Architecture

The billing system is provider-agnostic by design:

• src/constants/billing.ts holds product/price IDs and config
• src/lib/billing/providers/stripe.ts implements the Stripe provider
• src/routes/api/stripe/webhook.ts handles incoming Stripe events
• src/lib/billing/server.ts exposes server functions for creating checkout sessions and portal sessions

To add another provider (e.g. Lemon Squeezy), implement the BillingProvider interface and register it in src/lib/billing/providers/index.ts.

Production Setup

1. Switch to live mode in the Stripe Dashboard and copy your live secret key (sk_live_...)
2. Create products and prices in live mode
3. Add a webhook endpoint at https://yourdomain.com/api/stripe/webhook and select the events: checkout.session.completed, customer.subscription.created, customer.subscription.updated, customer.subscription.deleted
4. Set STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, and the product/price IDs in your hosting platform's environment variables

Troubleshooting

• Webhook signature verification failed: Make sure STRIPE_WEBHOOK_SECRET matches the CLI or dashboard signing secret.
• Customer not found: Verify the user is logged in before checkout, or check the billing_customer table.
• Events not arriving: Confirm the Stripe CLI is running and forwarding to the correct port.