Wallet system: top-ups, coupons, credits, AI usage and admin controls (14 Oct 2026) Diagram

Top-up flow

Who: ACTIVE or TRIALING subscriptions only (TOPUP_STATUSES); every other status gets 403. The wallet page is visible in PENDING_SETUP, PAST_DUE, PENDING_REAUTH, CANCELLED and ENDED with the button disabled (can_top_up false); hidden for UNPAID, PAYMENT_FAILED, EXPIRED. IAM: siem:wallet:read to view, siem:wallet:manage to buy.
Amount is entered in USD. Credits = USD amount × credits_per_dollar (wallet_credit_settings). Stripe charges USD; Razorpay charges USD × the daily USD→INR rate (open.er-api.com, stored in wallet_credit_settings). The customer picks the gateway for each top-up; the subscription's country rule does not apply.
Stripe: Checkout Session mode payment; metadata purposeType wallet_topup, walletPurchaseId, subscriptionId (also on the PaymentIntent). Completed by checkout.session.completed; declines arrive as payment_intent.payment_failed.
Razorpay: order whose notes carry the same keys. Browser verify-payment checks the stored order ID and signature and returns 202 pending until captured; payment.captured completes it. Browser payment notes are never trusted.
Completion (once, conditional update): pending, failed, expired or cancelled → completed; balance and totalAdded raised under a CAS version check; wallet_transactions credit row; low-balance threshold reset to last credit × alert %; invoiceNumber WLT<YYMMDD><nnn> and paidAt set; confirmation email queued (job wallet-purchase-<id>) with an in-app notification. Receipt PDF: GET /wallet/purchases/:id/invoice (admin: /admin/wallet/purchases/:id/invoice).
A decline (handleTopupFailed) marks the purchase failed unless it is already completed; the customer can retry in the same checkout. Net paid 0 (100% coupon): no checkout, completed at once with externalId free_coupon_<id>.

Wallet coupons (separate from subscription coupons)

Fields: code, percentage or fixed_amount, discount value (USD) and optional INR value, max discount, min purchase (USD), max global uses, max uses per user, valid from/until, active flag.
Checks: active, inside dates, purchase ≥ min, redemptions + reserved below the global limit, the user's active-or-redeemed uses below the per-user limit.
Discount: percentage of the USD amount (capped by max discount); fixed on Stripe = USD value capped at the amount; fixed on Razorpay = INR value, or USD value × rate. Credits are always for the full USD amount.
Slot lifecycle: reserved when the purchase is created (one transaction with the per-user check); finalized as a redemption on completion; released on cancel, on checkout-creation failure, or by wallet-coupon-expiry (pending or failed coupon purchases older than 15 minutes). A purchase completed after its slot was released only adds the redemption.

Using credits and admin controls

The AI chat service posts token usage to POST /wallet/metering/ai-logs (internal auth). Cost = provider rates × multiplier (+ web search) from ai_provider_rates; credits = cost × credits_per_dollar; debited under the CAS version check; ai_token_logs keeps rate snapshots. 402 when the balance is below the cost; requireActiveWalletWithBalance returns 402 when the balance is 0 or less.
Low balance email 'Alert: Low Wallet Credit Balance' when a debit crosses below the wallet threshold (last credit added × alert %). The summary shows balance, totals, and the calendar month's spend (UTC).
Admin wallet settings: credits_per_dollar, alert % (re-applied to every wallet), usd_to_inr_rate (overwritten by the next daily live fetch). Admin wallet coupons: list, create, edit, toggle, delete.
Admin adjust balance: positive credit or negative debit with a required reason (zero refused), reference admin_adjustment. AI provider rates: create, edit, delete per provider and model.

Gaps found in the code

POST /wallet/check-balance has its auth commented out: anyone who knows a subscription ID can read its balance, and the call creates a wallet row for it.
Razorpay + percentage coupon: the discount is computed in USD and subtracted from the INR amount (20% off $100 charges about ₹8,480 instead of about ₹6,784).
Only purchases with a coupon expire; a pending purchase without a coupon stays pending.
No minimum or maximum amount on the server (Stripe needs $0.50, Razorpay ₹1). Credits left on an EXPIRED subscription are hidden and cannot be used or refunded. The confirmation email carries no receipt PDF.
Live card rules limit the gateway choice: Stripe India cannot charge Indian cards in USD; Razorpay with International Payments off refuses foreign cards.