# [Service Name] — Stripe Checkout layer

A thin service that takes payments via Stripe Checkout and processes webhooks safely. Stateless except for what you choose to persist.

## Source of truth
Stripe is the source of truth for payment state. Your DB stores a denormalized copy for fast reads. The webhook reconciles after every event.

## Tech stack
Node 22 + TypeScript + Express or Hono (whatever your existing stack uses). Stripe SDK (`stripe` npm package, pinned to a specific API version). Postgres for the local mirror. JWT or session auth on the create-checkout endpoint.

## Deploy
Anywhere a Node server runs. Webhook endpoint must be reachable from the public internet. For local dev use `stripe listen --forward-to localhost:3000/webhooks/stripe`.

## File map
- `src/routes/checkout.ts` POST `/api/checkout` -> creates a Checkout Session, returns the URL
- `src/routes/billing-portal.ts` POST `/api/billing-portal` -> Customer portal URL for subscription management
- `src/routes/webhook.ts` POST `/webhooks/stripe` -> verifies signature, dispatches by event type
- `src/lib/stripe.ts` SDK init, API version pin
- `src/lib/db.ts` Postgres writes for customers, subscriptions, orders
- `src/events/` one handler per Stripe event type (checkout.session.completed, customer.subscription.updated, etc)
- `db/schema.sql` `stripe_customers`, `subscriptions`, `orders` tables

## .env keys
- `STRIPE_SECRET_KEY` `sk_live_...` or `sk_test_...`
- `STRIPE_WEBHOOK_SECRET` `whsec_...`
- `STRIPE_PRICE_IDS_TIER1`, `STRIPE_PRICE_IDS_TIER2` your product price IDs
- `STRIPE_PORTAL_RETURN_URL` where users land after the portal
- `DATABASE_URL`

## Hard rules
- Webhook signature is verified BEFORE parsing the body. Use the raw body, not `JSON.parse()`.
- Webhook handlers must be idempotent. Same event twice = same result. Store the Stripe event ID, refuse duplicates.
- Webhook responds 200 within 2 seconds; do the slow work in a background queue if needed.
- Never store full card numbers, CVCs, or full names on cards. Stripe holds these.
- API version is PINNED in `stripe.ts` (`apiVersion: '2025-06-30.basil'` or whatever your locked version is). Test before bumping.
- Test mode keys for dev, live mode for prod. Use Stripe's CLI `stripe listen` to forward events to localhost.

## Recent significant changes
- 2026-04-26: Scaffolded. Locked: Stripe Checkout (hosted) over custom Elements UI, webhooks over polling, Postgres mirror over Stripe-as-source-only.

## Next session: start here
1. Create Stripe account, get test keys.
2. Create products + prices in Stripe Dashboard, save IDs.
3. `stripe listen --forward-to localhost:3000/webhooks/stripe` and copy the `whsec_` into `.env`.
4. Implement create-checkout endpoint, test with a real test card (`4242 4242 4242 4242`).
5. Verify a successful webhook updates your DB before going live.
6. Activate live mode keys. Test one real payment for $1.