Credit Purchase (Stripe Checkout → Webhook → Credit Lot)

Admin buys a credit pack via Stripe; webhook grants an expiring lot idempotently.

Sequence

sequenceDiagram
  autonumber
  participant Admin as Admin browser
  participant API as Hono API
  participant StripeSvc as stripe.service
  participant Stripe as Stripe Checkout
  participant WH as stripe webhook route
  participant Credits as credit.service
  participant Mongo as MongoDB

  Admin->>API: POST /v1/credits/checkout (admin)
  StripeSvc->>Stripe: checkout.sessions.create
  StripeSvc-->>Admin: redirect url
  Admin->>Stripe: pay

  Stripe->>WH: POST /v1/webhooks/stripe
  WH->>StripeSvc: handleStripeEvent (verify signature)
  StripeSvc->>Credits: grantPurchase
  Credits->>Mongo: lot + ledger + org balance
  WH-->>Stripe: 200 received

Steps

1. Admin starts checkout for a catalog pack; API returns Stripe Hosted Checkout URL.
2. Customer pays on Stripe; webhook hits the API with signed raw body.
3. Paid session metadata identifies organization and pack; credits are granted in a transaction.
4. Purchase ledger row is keyed by payment session id so replayed webhooks are no-ops.
5. Available balance increases for interview reservations.