> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aspfox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Stripe Setup

> Configure Stripe for local development with the CLI and for production with live keys and webhook endpoints.

## Local development

### Get test mode API keys

1. Log in to [dashboard.stripe.com](https://dashboard.stripe.com)
2. Make sure **Test mode** is toggled on (top right, shows "Test mode" label)
3. Go to **Developers → API keys**
4. Copy the **Secret key** (starts with `sk_test_`)
5. Add to `.env`: `STRIPE_SECRET_KEY=sk_test_51…`

### Set up local webhook forwarding

The Stripe CLI forwards webhook events from Stripe to your local API server. Without it, Stripe cannot deliver events to `localhost`.

Install the Stripe CLI:

* **macOS:** `brew install stripe/stripe-cli/stripe`
* **Windows:** `scoop install stripe` or download from [stripe.com/docs/stripe-cli](https://stripe.com/docs/stripe-cli)
* **Linux:** Follow [stripe.com/docs/stripe-cli](https://stripe.com/docs/stripe-cli)

Log in:

```bash theme={null}
stripe login
```

Start forwarding (keep this running while developing):

```bash theme={null}
stripe listen --forward-to http://localhost:5000/api/v1/webhooks/stripe
```

The CLI prints a webhook signing secret starting with `whsec_`. Copy it to `.env`:

```bash theme={null}
STRIPE_WEBHOOK_SECRET=whsec_abc123…
```

### Create test products and prices

1. Stripe Dashboard → **Products** → **Add product**
2. Create the Pro plan:
   * Name: `Pro`
   * Pricing: Recurring, \$29/month
   * Copy the Price ID (starts with `price_`) → add to `.env` as `STRIPE_PRO_PRICE_ID`
3. Create the Business plan:
   * Name: `Business`
   * Pricing: Recurring, \$79/month
   * Copy the Price ID → add to `.env` as `STRIPE_BUSINESS_PRICE_ID`

### Test the checkout flow locally

With `stripe listen` running and your API started, go to the Billing page in the frontend and click **Upgrade**. You should be redirected to Stripe's hosted checkout. Use test card `4242 4242 4242 4242` with any future expiry and any CVC.

Watch the `stripe listen` terminal — you should see the `checkout.session.completed` event forwarded and a `200` response from your API.

## Production

### Switch to live keys

1. In Stripe Dashboard, toggle **Live mode** on
2. Go to **Developers → API keys**
3. Copy the **Secret key** (starts with `sk_live_`)
4. Update your production environment: `STRIPE_SECRET_KEY=sk_live_51…`

<Warning>
  Price IDs are environment-specific. A price ID created in test mode only works with test mode API keys. You need to create separate Pro and Business prices in live mode and use their Price IDs in production.
</Warning>

### Register the webhook endpoint

1. Stripe Dashboard → **Developers → Webhooks** → **Add endpoint**
2. Endpoint URL: `https://api.yourdomain.com/api/v1/webhooks/stripe`
3. Select events to listen for:
   * `checkout.session.completed`
   * `customer.subscription.updated`
   * `customer.subscription.deleted`
   * `invoice.payment_failed`
   * `invoice.payment_succeeded`
4. Click **Add endpoint**
5. On the endpoint detail page, click **Reveal** next to **Signing secret**
6. Copy the signing secret (starts with `whsec_`) → add to production env as `STRIPE_WEBHOOK_SECRET`

### Verify the webhook is working

After deploying, trigger a test event from the Stripe Dashboard:

1. **Developers → Webhooks** → click your endpoint
2. **Send test webhook** → select `checkout.session.completed`
3. Check your API logs for the receipt and the `200` response

<Note>
  Each registered webhook endpoint has its own signing secret. The secret from the Stripe CLI (`stripe listen`) is different from the secret from a registered production endpoint. Make sure you are using the correct one for each environment.
</Note>