Story-2194: Razorpay egress moves to the Next.js BFF

Story-2192 wired the Razorpay Checkout modal, but the actual order-create hung and returned 500. Root cause (verified 2026-07-09): the pramaan-app-api Lambda sits in the default VPC with no NAT, so it cannot reach api.razorpay.com — Razorpay order-create was the first outbound HTTP the backend ever tried. Founder decision: do not add NAT/egress; keep the backend internet-free. Next.js (which has internet) places the Razorpay order.

The split

What landed

• Codegen re-synced — the OpenAPI mirror (openapi/app-api.json + permission-map.json) was synced from functions main and src/gen regenerated. RazorpayTopupOrderResponse → RazorpayTopupQuoteResponse + RazorpayTopupNotes; the operation renamed appCreate… → appQuoteRazorpayTopupOrder.
• Gateway — creditsGateway.quoteRazorpayTopupWithResponseHeaders (src/lib/credits/gateway.ts) POSTs the amount and contract-asserts the RazorpayTopupQuoteResponse (HR-21).
• Egress (new) — src/lib/credits/razorpay-order.ts (server-only) places the order at https://api.razorpay.com/v1/orders via basic auth from RAZORPAY_KEY_ID/RAZORPAY_KEY_SECRET.
• Route — POST /api/internal/credits/razorpay/order now: parse → backend quote → Razorpay egress → return { orderId, razorpayKeyId, amountPaise, currency, credits, basePaise, gstPaise, gstPct }. 502 on egress failure, 500 when keys are unset.
• BFF contract — src/lib/credits/topup-order.ts holds the browser-order Zod schema/type (BFF-owned, not a backend DTO — HR-22 permits a local browser-only schema). The page consumes it via the hand-written useCreateTopupOrder hook (the generated hook now mirrors the quote, not the order).

Money-integrity invariant — the note that would have broken minting

The S8 mint webhook (unchanged) reads Razorpay order notes by snake_case keys (firm_id, credits, …) and treats every value as a string. But the app-api quote emits notes in camelCase (firmId, paiseCharged, …). Forwarding them verbatim would drop firm_id and the webhook would silently refuse to mint. So the BFF remaps to the exact shape the webhook reads, mirroring the retired backend build_order_params:

notes = {
  firm_id:       String(notes.firmId),
  credits:       String(notes.credits),
  paise_charged: String(notes.paiseCharged),
  base_paise:    String(notes.basePaise),
  gst_paise:     String(notes.gstPaise),
  gst_pct:       String(notes.gstPct),
  ai_markup:     String(notes.aiMarkup),
  fx_usd_to_inr: String(notes.fxUsdToInr),
}

Amount, GST and notes are all computed by the backend under RLS — the browser/BFF never set the price. The Razorpay secret lives in Next server env only (never NEXT_PUBLIC, never logged). The webhook stays the only credit-minting path.

Verification

• pnpm typecheck, pnpm lint, pnpm build — green.
• Unit tests green: backend-quote gateway contract, the Next egress with Razorpay fetch mocked (asserts snake_case stringified notes, amount, basic auth), the route (quote → egress → Checkout shape, plus 422/500/502 paths), and the credits page.
• Env: RAZORPAY_KEY_ID/RAZORPAY_KEY_SECRET added to local .env.local (rzp_test, from pramaan/razorpay/staging). They must also be set as Vercel server env vars for staging.