Stripe Configuration

Stripe handles all billing. Provisioning is triggered automatically by the invoice.paid webhook.

1. Create products and prices

In the Stripe Dashboard:

  1. Create three products: WhatsApp Agent, Web Lead Agent, Brain Agent.
  2. For each product, add a recurring monthly price in your target currency.
  3. Copy each Price ID (format: price_...) into your .env:
STRIPE_PRICE_WHATSAPP=price_xxx
STRIPE_PRICE_WEB=price_yyy
STRIPE_PRICE_BRAIN=price_zzz

2. Register the webhook

In the Stripe Dashboard → Developers → Webhooks → Add endpoint:

  • Endpoint URL: https://agents.megabyteisland.com/webhooks/stripe
  • Events to listen to: invoice.paid

After saving, click Reveal signing secret and copy the whsec_... value into your .env:

STRIPE_WEBHOOK_SECRET=whsec_...

For local development, use the Stripe CLI:

stripe listen --forward-to localhost:3001/webhooks/stripe

Copy the webhook signing secret printed by the CLI.

3. Subscription metadata

When a checkout session is created, the following metadata is attached to the subscription. The provisioning engine reads this metadata on invoice.paid:

Metadata key Value Required
agent_type whatsapp | web | brain Yes
agent_name Human-readable agent name Yes
system_prompt_override Custom system prompt No
kb_documents Comma-separated DO document IDs Conditional (Brain)

4. Stripe Customer Portal (optional)

To allow users to manage their own subscriptions (cancel, update payment method):

  1. Stripe Dashboard → Settings → Billing → Customer Portal → Activate
  2. Add a link to the portal in the Dashboard UI (future feature).

5. Test mode

All development should be done in Stripe test mode. Use test card 4242 4242 4242 4242 with any future expiry and CVC.

Switch to live mode only when deploying to production.