Set up Stripe API keys, webhook secrets, and configure the Stripe integration in Vibestacks. Step-by-step guide for test and production environments.

This guide walks you through configuring Stripe for both local development and production.

Environment Variables

Add these variables to your .env.local file:

.env.local

# Stripe API Keys
# Get these from: https://dashboard.stripe.com/apikeys
STRIPE_SECRET_KEY="sk_test_xxxxxxxxxxxx"

# Stripe Webhook Secret
# For local dev: Use Stripe CLI (see below)
# For production: https://dashboard.stripe.com/webhooks
STRIPE_WEBHOOK_SECRET="whsec_xxxxxxxxxxxx"

Test vs Live Keys

Test keys start with sk_test_ - use for development
Live keys start with sk_live_ - use for production only

Never commit live keys to your repository.

Getting Your API Keys

Access the Stripe Dashboard

Go to dashboard.stripe.com/apikeys and sign in to your Stripe account.

Toggle Test Mode

Make sure Test mode is enabled (toggle in the top-right corner). You should see "Test Data" in the sidebar.

Copy Your Secret Key

Click Reveal test key next to "Secret key" and copy it. It starts with sk_test_.

Add it to your .env.local:

STRIPE_SECRET_KEY="sk_test_your_key_here"

Setting Up Webhooks

Webhooks allow Stripe to notify your app when events happen (subscription created, payment failed, etc.).

For local development, use the Stripe CLI to forward webhooks to your localhost.

Install Stripe CLI

brew install stripe/stripe-cli/stripe

scoop install stripe

Or download from Stripe CLI releases.

# Debian/Ubuntu
curl -s https://packages.stripe.dev/api/security/keypair/stripe-cli-gpg/public | gpg --dearmor | sudo tee /usr/share/keyrings/stripe.gpg
echo "deb [signed-by=/usr/share/keyrings/stripe.gpg] https://packages.stripe.dev/stripe-cli-debian-local stable main" | sudo tee -a /etc/apt/sources.list.d/stripe.list
sudo apt update && sudo apt install stripe

stripe login

This opens your browser to authenticate with your Stripe account.

Forward Webhooks to Localhost

stripe listen --forward-to localhost:3000/api/auth/stripe/webhook

You'll see output like:

Ready! Your webhook signing secret is whsec_xxxxxxxxxxxxx

Copy this whsec_xxx value to your .env.local:

STRIPE_WEBHOOK_SECRET="whsec_xxxxxxxxxxxxx"

Keep It Running

Leave the stripe listen command running in a terminal while developing. It will log all webhook events.

Webhook Secret Changes

The webhook secret from stripe listen changes each time you restart the CLI. Update your .env.local if you restart it.

For production, create a webhook endpoint in the Stripe Dashboard.

Create Webhook Endpoint

Go to dashboard.stripe.com/webhooks and click Add endpoint.

Configure the Endpoint

Endpoint URL: https://yourdomain.com/api/auth/stripe/webhook
Description: Vibestacks subscription webhooks
Listen to: Events on your account

Select Events

Click Select events and add these events:

checkout.session.completed
customer.subscription.created
customer.subscription.updated
customer.subscription.deleted
invoice.paid
invoice.payment_failed

Minimum Required Events

At minimum, you need checkout.session.completed and the customer.subscription.* events for subscriptions to work.

Get the Signing Secret

After creating the endpoint, click on it and reveal the Signing secret.

Add it to your production environment variables:

STRIPE_WEBHOOK_SECRET="whsec_xxxxxxxxxxxxx"

App Configuration

The Stripe integration is configured in config/app.ts:

config/app.ts

export const stripeConfig = {
  // Enable/disable Stripe entirely
  enabled: true,
  
  // Create Stripe customer when user signs up
  createCustomerOnSignUp: true,

  // Redirect URLs after checkout
  urls: {
    success: "/dashboard/billing?success=true",
    cancel: "/pricing?canceled=true",
    billingReturn: "/dashboard/billing",
  },

  // Your subscription plans (see Plans & Pricing guide)
  plans: [
    // ...
  ],
} as const;

Configuration Options

Option	Type	Default	Description
`enabled`	`boolean`	`true`	Enable/disable Stripe integration
`createCustomerOnSignUp`	`boolean`	`true`	Auto-create Stripe customer on registration
`urls.success`	`string`	-	Redirect URL after successful checkout
`urls.cancel`	`string`	-	Redirect URL if user cancels checkout
`urls.billingReturn`	`string`	-	Return URL from Stripe billing portal

Disabling Stripe

If you don't need payments yet, disable Stripe entirely:

config/app.ts

export const stripeConfig = {
  enabled: false,
  // ...
} as const;

This will:

Skip loading the Stripe plugin in auth.ts
Hide subscription methods in auth-client.ts
Allow your app to run without Stripe credentials

Verifying Your Setup

After configuration, verify everything works:

Start Your Dev Server

pnpm dev

Start Stripe CLI (if local)

stripe listen --forward-to localhost:3000/api/auth/stripe/webhook

Test a Checkout Flow

Go to your pricing page
Click on a paid plan
Complete checkout with test card 4242 4242 4242 4242
Verify you're redirected to the success URL
Check the Stripe CLI logs for webhook events

Troubleshooting

Next Steps

Plans & Pricing - Configure your subscription tiers
Webhooks - Deep dive into webhook handling

Configuration