61 lines
1.9 KiB
Markdown
61 lines
1.9 KiB
Markdown
# Stripe Billing
|
|
|
|
`accounts.svc.plus` is the server-side owner of Stripe billing.
|
|
|
|
It now provides:
|
|
|
|
- `POST /api/auth/stripe/checkout`
|
|
- `POST /api/auth/stripe/portal`
|
|
- `POST /api/billing/stripe/webhook`
|
|
|
|
## Required Environment Variables
|
|
|
|
Set these before starting the service:
|
|
|
|
```bash
|
|
STRIPE_SECRET_KEY=sk_test_xxx
|
|
STRIPE_WEBHOOK_SECRET=whsec_xxx
|
|
STRIPE_ALLOWED_PRICE_IDS=price_xstream_paygo,price_xstream_subscription
|
|
```
|
|
|
|
`STRIPE_ALLOWED_PRICE_IDS` is optional but recommended. When set, the checkout endpoint rejects any `price_id` that is not explicitly allowed.
|
|
|
|
## Local Test Mode Runbook
|
|
|
|
1. Start the account service with Stripe test-mode credentials.
|
|
2. Expose the service so Stripe webhooks can reach it, or use the Stripe CLI:
|
|
|
|
```bash
|
|
stripe listen --forward-to http://127.0.0.1:8080/api/billing/stripe/webhook
|
|
```
|
|
|
|
3. Copy the webhook secret printed by Stripe CLI into `STRIPE_WEBHOOK_SECRET`.
|
|
4. Restart `accounts.svc.plus`.
|
|
5. Start `console.svc.plus` with matching public `NEXT_PUBLIC_STRIPE_PRICE_*` values.
|
|
6. Sign in through the console and start a checkout flow.
|
|
7. Complete the payment with Stripe test card data.
|
|
8. Verify:
|
|
- checkout redirects back to the console
|
|
- webhook delivery succeeds
|
|
- `GET /api/auth/subscriptions` contains a `provider = stripe` record
|
|
- Stripe portal opens for the same user
|
|
|
|
## Webhook Notes
|
|
|
|
The webhook currently handles these events:
|
|
|
|
- `checkout.session.completed`
|
|
- `customer.subscription.created`
|
|
- `customer.subscription.updated`
|
|
- `customer.subscription.deleted`
|
|
- `invoice.paid`
|
|
- `invoice.payment_failed`
|
|
|
|
The webhook is the authoritative source for Stripe subscription status in the local `subscriptions` store.
|
|
|
|
## Operational Notes
|
|
|
|
- Keep Stripe secret values server-side only.
|
|
- Use test mode until the complete flow is verified end to end.
|
|
- If checkout succeeds but no subscription record appears, inspect webhook delivery first.
|