kaboot/docs/STRIPE_SETUP.md

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.
2. Stripe CLI installed on your machine.
3. Kaboot local development environment running (see 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:

# 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

stripe login

Step 2: Start Forwarding

Run the following command in a new terminal window:

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. 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.).