Stripe Setup

LightningAddon wires Stripe for checkout and customer portal sessions. This guide covers webhooks, price IDs, and test vs live keys.

Overview

• Extension: Uses VITE_STRIPE_PUBLISHABLE_KEY (pk_test_xxx or pk_live_xxx)
• Backend: Uses STRIPE_API_KEY (sk_test_xxx or sk_live_xxx), price IDs, and webhook signing secret
• Billing flows run in the background service worker; the backend creates checkout/portal sessions and returns URLs

See Billing Architecture and your backend guide (Supabase or Firebase) for the flow.

1. Stripe Dashboard

1. Create a Stripe account
2. Use Test mode (toggle in Dashboard) for development
3. Get your Publishable key and Secret key from API keys

2. Price IDs

Create products and prices in Stripe Products:

1. Create a product (e.g. "Pro Monthly", "Pro Yearly")
2. Add a price to each (recurring monthly or yearly)
3. Copy the Price ID (e.g. price_1ABC...)

Set in env:

• VITE_STRIPE_PRICE_ID_MONTHLY / VITE_STRIPE_PRICE_ID_YEARLY (extension)
• STRIPE_PRICE_ID_MONTHLY / STRIPE_PRICE_ID_YEARLY (backend)

3. Webhook

The backend needs a webhook to handle checkout.session.completed and subscription lifecycle events.

1. In Webhooks, add endpoint
2. URL: https://your-api.com/handle-stripe-webhook (or your Supabase/Firebase function URL)
3. Select events: checkout.session.completed, customer.subscription.updated, customer.subscription.deleted, invoice.paid, etc.
4. Copy the Signing secret (wh_sec_...)
5. Set STRIPE_WEBHOOK_SIGNING_SECRET in your backend env

For local testing, use Stripe CLI to forward webhooks:

stripe listen --forward-to localhost:54321/functions/v1/handle-stripe-webhook

4. Env Summary

Key	Where	Purpose
VITE_STRIPE_PUBLISHABLE_KEY	envs/.env.development	Extension; load Stripe.js
VITE_STRIPE_PRICE_ID_MONTHLY	envs/.env.development	Optional; fallback for checkout
VITE_STRIPE_PRICE_ID_YEARLY	envs/.env.development	Optional
STRIPE_API_KEY	Backend env	Server-side Stripe calls
STRIPE_PRICE_ID_MONTHLY	Backend env	Checkout session
STRIPE_PRICE_ID_YEARLY	Backend env	Checkout session
STRIPE_WEBHOOK_SIGNING_SECRET	Backend env	Verify webhook signatures

5. Test vs Live

• Test keys (pk_test_, sk_test_): Use in development; no real charges
• Live keys (pk_live_, sk_live_): Use in production env files only
• Never commit secret keys; use .env.local or your hosting secrets