Skip to main content

Stripe Setup Guide

This guide will help you set up your Stripe products and prices to make the billing system work.

Prerequisites​

  1. Stripe account (sign up at https://stripe.com)
  2. Stripe CLI installed (https://stripe.com/docs/stripe-cli)
  3. Stripe CLI authenticated (stripe login)

Step 1: Install Stripe CLI (if not installed)​

macOS​

brew install stripe/stripe-cli/stripe

Linux​

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

Windows​

Download from: https://github.com/stripe/stripe-cli/releases/latest

Step 2: Authenticate Stripe CLI​

stripe login

This will open your browser to authenticate.

Step 3: Create Products and Prices​

Run the automated script:

./scripts/setup-stripe-products.sh

This will create all products and prices with the correct lookup keys.

Option B: Manual Creation via Stripe Dashboard​

  1. Go to https://dashboard.stripe.com/test/products
  2. Create the following products:

GovFit Platform Access​

  • Name: GovFit Platform Access
  • Price: $1,000.00 / month
  • Lookup Key: govfit_platform_access

1-Credit Pack​

  • Name: 1-Credit Pack
  • Monthly Price: $618.00 / month - Lookup Key: creditpack_1_monthly
  • One-time Price: $650.00 - Lookup Key: creditpack_1_onetime

4-Credit Pack​

  • Name: 4-Credit Pack
  • Monthly Price: $1,800.00 / month - Lookup Key: creditpack_4_monthly
  • One-time Price: $2,000.00 - Lookup Key: creditpack_4_onetime

12-Credit Pack​

  • Name: 12-Credit Pack
  • Monthly Price: $4,250.00 / month - Lookup Key: creditpack_12_monthly
  • One-time Price: $5,000.00 - Lookup Key: creditpack_12_onetime

28-Credit Pack​

  • Name: 28-Credit Pack
  • Monthly Price: $8,000.00 / month - Lookup Key: creditpack_28_monthly
  • One-time Price: $10,000.00 - Lookup Key: creditpack_28_onetime

Step 4: Set Up Webhook​

For Development (Local Testing)​

  1. Start Stripe CLI webhook forwarding:
stripe listen --forward-to localhost:3010/stripe/webhook
  1. Copy the webhook signing secret (starts with whsec_)
  2. Add it to your .env.local:
STRIPE_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxx

For Production​

  1. Go to https://dashboard.stripe.com/webhooks
  2. Click "Add endpoint"
  3. Set URL: https://your-api-domain.com/stripe/webhook
  4. Select these events:
    • checkout.session.completed
    • invoice.paid
    • invoice.payment_failed
    • customer.subscription.deleted
    • customer.subscription.updated
  5. Copy the webhook signing secret
  6. Add it to your production environment variables

Step 5: Add Environment Variables​

Add these to your .env.local (or .env files):

# Backend
STRIPE_SECRET_KEY=sk_test_xxxxxxxxxxxxx
STRIPE_PUBLISHABLE_KEY=pk_test_xxxxxxxxxxxxx
STRIPE_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxx

# Frontend
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_xxxxxxxxxxxxx

Step 6: Test the Integration​

  1. Start your backend: cd apps/backend && npm run dev
  2. Start your frontend: cd apps/frontend && npm run dev
  3. In a new terminal, start webhook forwarding: stripe listen --forward-to localhost:3010/stripe/webhook
  4. Navigate to /govintel/billing in your app
  5. Try purchasing a credit pack
  6. Use Stripe's test card: 4242 4242 4242 4242
    • Any future expiry date
    • Any 3-digit CVC
    • Any postal code

Troubleshooting​

"Price not found" or "Invalid price" errors​

Solution: Make sure the lookup keys in Stripe exactly match:

  • govfit_platform_access
  • creditpack_1_monthly, creditpack_1_onetime
  • creditpack_4_monthly, creditpack_4_onetime
  • creditpack_12_monthly, creditpack_12_onetime
  • creditpack_28_monthly, creditpack_28_onetime

"Webhook signature verification failed"​

Solution: Make sure STRIPE_WEBHOOK_SECRET matches the one from stripe listen output or your Stripe Dashboard webhook settings.

"successUrl must be a URL address"​

Solution: This error means Stripe can't find the price with the given lookup key. Make sure you've created all products and prices in Step 3.

Verification Checklist​

  • Stripe CLI installed and authenticated
  • All products created in Stripe Dashboard
  • All prices have correct lookup keys
  • Environment variables set in .env.local
  • Webhook forwarding running (development) or configured (production)
  • Backend running on port 3010
  • Frontend running on port 3000
  • Test purchase completes successfully

Next Steps​

Once setup is complete:

  1. Test purchasing each credit pack type
  2. Test subscription management (cancel/reactivate)
  3. Verify webhooks are being received
  4. Check billing history displays correctly

Support​

Note: This guide uses Stripe test mode. For production, repeat the setup with live API keys and live mode in the Stripe Dashboard.