🛠️ Stripe CLI for Development

The Stripe CLI allows you to simulate payments and test webhooks locally.
For installation instructions, see: Stripe CLI Install Guide 

1. Log In to Stripe CLI

After installing the CLI, authenticate:

stripe login

• Opens a browser window to log in.
• Once logged in, your CLI can access your Stripe Test/Sandbox account.

2. Create a Webhook for Development

1. Go to Developers → Webhooks in the Stripe dashboard.
2. Click + Add endpoint.
3. Set the Endpoint URL to your local dev server:

http://localhost:3000/api/stripe/webhook

4. Select the events to listen to:

• checkout.session.completed

5. Copy the Signing Secret from the Stripe dashboard and add it to your .env:

STRIPE_WEBHOOK_SECRET="whsec_XXXXXXXXXXXXXXXXXXXX"

3. Forward Events Locally

Run this command to forward Stripe events to your local webhook endpoint:

stripe listen --forward-to http://localhost:3000/api/stripe/webhook

• The CLI will display a local signing secret.
• Copy this secret and set it in your .env as STRIPE_WEBHOOK_SECRET.

✅ Now your app can receive Stripe events locally for testing.

4. Create One-Time Payment Products

Your app’s credit packs are defined in:

root/types/credits.ts

Here’s the structure you need to match:

export const CreditsPack: CreditsPack[] = [
  {
    id: PackId.ESSENTIAL,
    name: 'Essential Pack',
    priceId: process.env.STRIPE_ESSENTIAL_PACK_PRICE_ID!,
    ...
  },
  {
    id: PackId.ADVANCED,
    name: 'Advanced Pack',
    priceId: process.env.STRIPE_ADVANCED_PACK_PRICE_ID!,
    ...
  },
  {
    id: PackId.ELITE,
    name: 'Elite Pack',
    priceId: process.env.STRIPE_ELITE_PACK_PRICE_ID!,
    ...
  }
];

Steps to create products in Stripe:

1. Go to Product catalogue → Add product in your Stripe dashboard.
2. Create a product for each credit pack: Essential, Advanced, Elite.
3. Select one-off pricing and the correct currency.

   The price must match the amount in credits.ts (in cents).

4. Make sure that both the packs in the file and in Stripe are matched.
5. Click on the created product, open the pricing menu (three dots), and copy the Price ID (not the Product ID).
6. Add each Price ID to your .env:

STRIPE_ESSENTIAL_PACK_PRICE_ID="price_XXXXXXXXXXXX"
STRIPE_ADVANCED_PACK_PRICE_ID="price_XXXXXXXXXXXX"
STRIPE_ELITE_PACK_PRICE_ID="price_XXXXXXXXXXXX"

⚠️ The IDs in Stripe must exactly match the environment variables referenced in credits.ts.

5. Test Credit Purchases

1. Start your dev server:

pnpm dev

2. Use the frontend to purchase a credit pack.
3. The backend verifies the payment via the webhook and updates the user’s credit balance.
4. Ensure the correct Price ID is used for each pack.

✅ Success: Stripe payments are fully integrated with your app’s credit system.