jobtrackingapp/docs/infrastructure/stripe-activation.md

Stripe activation

Billing code is present, but production activation is an operator gate. Configure and test one recurring monthly Pro price in Stripe test mode before creating live-mode values. Test and live mode use different keys, price IDs, webhook endpoints, signing secrets, and customer data.

Required configuration

1. Create one recurring monthly Pro price and enable the customer portal.

2. Register <APP_PUBLIC_BASE_URL>/api/billing/webhook for customer.subscription.created, customer.subscription.updated, and customer.subscription.deleted.

3. Supply these deployment-only values through the server environment:

   STRIPE_SECRET_KEY=<test-or-live-secret-key>
   STRIPE_PRICE_PREMIUM=<recurring-price-id>
   STRIPE_WEBHOOK_SECRET=<endpoint-signing-secret>
   

Never put these values in Git, chat, screenshots, issue text, or CI logs. The webhook must receive the raw request body for signature verification.

Acceptance check

Use a disposable authenticated account: Upgrade opens hosted Checkout for the configured price; completion returns to the billing-success route; the signed webhook stores the subscription and grants the expected entitlement; Manage billing opens the customer portal; cancellation removes the entitlement when the subscription is no longer active or trialing; and replaying an event remains idempotent.

For live mode, repeat the product, portal, endpoint, and secret setup as one coordinated change. If activation must be stopped, removing the three values disables new Checkout/portal sessions without deleting billing history; repair webhook delivery and replay the authoritative event instead of manually changing roles.