Setting up Stripe

API Keys

web/.env
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=
STRIPE_SECRET_KEY=

To get your Stripe API keys:

  1. Create a Stripe account
  2. Go to the Developers section in your Stripe Dashboard
  3. Under “API keys” you’ll find both your publishable and secret keys
  • For development, use the test mode keys
  • For production, switch to live mode to get production keys

Webhook Setup

Webhooks are essential for handling Stripe events (successful payments, subscription updates, etc.).

  1. Install the Stripe CLI to get your webhook secret

  2. Login to the Stripe CLI:

stripe login
  1. Open a new terminal and start listening for webhooks:
cd app
pnpm stripe:listen

This command will output your webhook signing secret - copy it to

web/.env
STRIPE_WEBHOOK_SECRET=

Products and Prices Setup

Creating Products

  1. Go to Products in your Stripe Dashboard
  2. Click “Add product”
  3. Create two products (example):
  • Starter Plan
  • Pro Plan

Setting Up Prices

For each product, you’ll need to create multiple prices:

web/.env
# Stripe Subscriptions
NEXT_PUBLIC_STRIPE_STARTER_MONTHLY_PRICE_ID=
NEXT_PUBLIC_STRIPE_STARTER_ANNUALLY_PRICE_ID=
NEXT_PUBLIC_STRIPE_PRO_MONTHLY_PRICE_ID=
NEXT_PUBLIC_STRIPE_PRO_ANNUALLY_PRICE_ID=

# Stripe Onetime Payments
NEXT_PUBLIC_STRIPE_STARTER_ONETIME_PRICE_ID=
NEXT_PUBLIC_STRIPE_PRO_ONETIME_PRICE_ID=

For each product:

  1. Click “Add price”
  2. Create recurring prices:
  • Monthly subscription (e.g., $9/month)
  • Annual subscription (e.g., $90/year)
  1. Create one-time prices if needed
  2. Copy the price IDs to your .env

Price ID Location

To find your price IDs:

  1. Go to Products
  2. Click on a product
  3. Under “Pricing”, you’ll see all prices for that product
  4. Click the ”…” menu next to each price
  5. Select “Copy ID” - it will look like price_XXXXXXXXXXXXXXXXX

Webhooks

Webhooks are essential for handling Stripe events (successful payments, subscription updates, etc.).

  1. Open webhooks in the Stripe Dashboard

  2. Click “Add webhook”

  3. Set your webhook URL to: https://yourdomain.com/api/webhooks/stripe

  4. Add the following events:

checkout.session.completed
customer.subscription.deleted
customer.subscription.updated
invoice.paid
payment_intent.succeeded

Testing

Use Stripe’s test cards for payments:

  • Success: 4242 4242 4242 4242
  • Decline: 4000 0000 0000 0002
  • Use any future date for expiry and any 3 digits for CVC

See Stripe Testing for more information.

Going Live

Before going live:

  1. Complete Stripe’s account activation process
  2. Switch to live mode in the Stripe Dashboard
  3. Update your environment variables with live mode keys
  4. Set up production webhooks
  5. Test the entire payment flow in live mode with a real card (use a small amount)
  6. Monitor your Stripe Dashboard for real transactions

Common Issues

  • Webhook errors: Ensure your webhook endpoint is accessible and the signing secret is correct
  • Payment failures: Check the Events section in Stripe Dashboard
  • Price ID issues: Verify you’re using the correct price IDs for test/live mode in combination with the correct stripe keys