# Stripe Setup Guide (Development)

This guide provides step-by-step instructions for setting up a Stripe test account and configuring payments for Kaboot in your local development environment.

## Overview

Kaboot uses Stripe to manage subscriptions for "AI Pro" access. Users get 250 AI quiz generations per month with a paid subscription, while free users are limited to 5.

## Prerequisites

1.  A [Stripe Account](https://dashboard.stripe.com/register).
2.  [Stripe CLI](https://stripe.com/docs/stripe-cli) installed on your machine.
3.  Kaboot local development environment running (see [README.md](../README.md)).

---

## 1. Stripe Dashboard Configuration

### Step 1: Enable Test Mode
Log in to your Stripe Dashboard and ensure the **Test Mode** toggle (usually in the top right) is turned **ON**.

### Step 2: Create a Product
1.  Navigate to **Products** > **Add Product**.
2.  **Name**: `Kaboot AI Pro`
3.  **Description**: `250 AI quiz generations per month`
4.  **Pricing**:
    *   **Price 1**: $5.00 USD, Recurring, Monthly.
    *   **Price 2**: $50.00 USD, Recurring, Yearly.
5.  Click **Save Product**.

### Step 3: Get Price IDs
After saving, copy the **API IDs** for both prices. They look like `price_1P...`. You will need these for your environment variables.

---

## 2. Environment Configuration

Add the following variables to your `.env` file in the project root:

```env
# Stripe API Keys (Test Mode)
# Found at: https://dashboard.stripe.com/test/apikeys
STRIPE_SECRET_KEY=sk_test_51P...

# Stripe Price IDs (from Step 3 above)
STRIPE_PRICE_ID_MONTHLY=price_...
STRIPE_PRICE_ID_YEARLY=price_...

# Stripe Webhook Secret (Leave empty initially, see Section 3)
STRIPE_WEBHOOK_SECRET=whsec_...
```

> **Note**: In development, `STRIPE_SECRET_KEY` should always start with `sk_test_`.

---

## 3. Webhook Setup (Local Development)

Stripe needs to send events (like successful payments) to your local server. Since Stripe cannot access `localhost` directly, you must use the Stripe CLI to forward events.

### Step 1: Login to Stripe CLI
```bash
stripe login
```

### Step 2: Start Forwarding
Run the following command in a new terminal window:

```bash
stripe listen --forward-to localhost:3001/api/payments/webhook
```

### Step 3: Get Webhook Secret
The command above will output a **webhook signing secret** (e.g., `whsec_abc123...`). 
1.  Copy this secret.
2.  Paste it into your `.env` file as `STRIPE_WEBHOOK_SECRET`.
3.  **Restart your backend server** to apply the changes.

---

## 4. Testing the Flow

### Test Credit Card
Use Stripe's [test card numbers](https://stripe.com/docs/testing#cards). The most common is:
*   **Card Number**: `4242 4242 4242 4242`
*   **Expiry**: Any future date
*   **CVC**: Any 3 digits
*   **Zip**: Any 5 digits

### Webhook Events to Monitor
When testing, watch your `stripe listen` terminal. You should see:
- `checkout.session.completed`: When a user finishes the payment.
- `customer.subscription.updated`: When status changes.
- `invoice.paid`: When the monthly/yearly bill is settled (resets generation counts).

---

## 5. Troubleshooting

### Webhook Signature Mismatch
**Error**: `Webhook signature verification failed`
- **Solution**: Ensure `STRIPE_WEBHOOK_SECRET` in `.env` matches the secret shown in your `stripe listen` output. Each time you run `stripe listen`, a new secret might be generated if not configured as a permanent endpoint.

### Missing Keys
**Error**: `Stripe API Key not found`
- **Solution**: Verify `STRIPE_SECRET_KEY` is set in the `.env` file that the **backend** (server) is reading.

### Checkout Session Fails
**Error**: `No such price: price_...`
- **Solution**: Ensure your `STRIPE_PRICE_ID_MONTHLY` and `STRIPE_PRICE_ID_YEARLY` variables match the Price IDs in your Stripe **Test Mode** dashboard.

---

## Technical Details

- **Webhook Endpoint**: `POST /api/payments/webhook`
- **Checkout Initiation**: `POST /api/payments/checkout`
- **Billing Portal**: `POST /api/payments/portal` (Allows users to manage/cancel subscriptions)
- **Database Fields**: User subscription status is stored in the `users` table (`subscription_status`, `generation_count`, etc.).