jobtrackingapp/docs/operations/stripe-activation.md

Stripe activation

The application code is complete. Activate it in Stripe test mode first; test and live mode have different API keys, price ids, webhook endpoints/signing secrets, and customer data.

Official references:

• https://docs.stripe.com/subscriptions
• https://docs.stripe.com/customer-management/integrate-customer-portal
• https://docs.stripe.com/webhooks?lang=dotnet

Test-mode setup

1. Create one recurring monthly Premium product/price.

2. Enable the customer portal for subscription management and cancellation.

3. Register https://jobs.cesnimda.uk/api/billing/webhook as an HTTPS webhook endpoint for:

   • customer.subscription.created
   • customer.subscription.updated
   • customer.subscription.deleted

4. Add the test-mode values to /opt/job-tracker/shared/.env:

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

5. Restart/redeploy the backend without printing those values.

Never put the values in Git, chat, screenshots, issue text, or CI logs. Stripe requires the raw request body for signature verification; the implemented endpoint reads it before constructing the signed event.

Acceptance check

Use a disposable, authenticated Jobbjakt account:

1. Account settings reports billing enabled and offers Upgrade.
2. Upgrade opens Stripe-hosted Checkout for the configured monthly price.
3. Completing a Stripe test subscription returns to /settings?billing=success.
4. The signed subscription webhook stores the Stripe customer/subscription/status and grants the Premium role.
5. /api/auth/me exposes Premium entitlements and the UI unlocks Premium capabilities.
6. Manage billing opens the Stripe customer portal.
7. Cancel in the portal and confirm an updated/deleted subscription webhook removes Premium when the subscription is no longer active or trialing.
8. Replay one event from Stripe Workbench and confirm role/state remain idempotent.

Live-mode cutover

Repeat the product/price, portal, and webhook setup in live mode. Replace all three environment values as one change; never mix a test price or endpoint secret with a live API key. Complete one real low-risk subscription and cancellation, confirm the webhook delivery log is green, then remove the disposable account if it is no longer needed.

Rollback

Removing all three environment values disables new Checkout/portal sessions without deleting billing history. Do not manually remove Premium roles while Stripe still reports an active subscription; fix webhook delivery and replay the authoritative subscription event instead.