01 · Signup & checkout (createAndInitiatePayment → gateway → success page, 14 Oct 2026) Diagram

What actually runs

Step 2 collects company registration country beside Organization Name. IN → Razorpay INR; other supported countries → Stripe USD. Checkout stores it on Subscription, including free trials and $0 signups. No gateway selector.
Paid: POST /api/v1/subscription/setup; free: POST /create-checkout-session; both go to SubscriptionService.createAndInitiatePayment
Refusals: org name missing/taken, a PAST_DUE renewal exists (EXISTING_FAILED_SUBSCRIPTION: message only, no redirect), asset range, free plan already claimed, PRICE_CHANGED (409: confirm the new price), previous Razorpay payment still in progress
Starting over: a new checkout closes the customer's unfinished signup checkouts (UNPAID/PAYMENT_FAILED, cycle 0); the selected coupon's slot stays with the selection. There is no failed-order card and no manual retry of a first payment.
Free plan: PENDING_SETUP, isTrialActive false; trialEnd = claim + freeTrialDays. Admin TRIALING preserves that deadline. Unused trials also reach ENDED, then EXPIRED after 7 days.
$0 first charge: PENDING_SETUP, internal invoice + payment, org + IAM, 3 onboarding emails; no gateway. A paid signup's confirmation email carries the invoice PDF (a free claim has none).
Free plan card in the calculator shows ₹ or $ from the chosen company country, like the paid card.
Existing subscriptions: seed:subscription-countries sets the missing company registration country from the owner's User.country (a missing country defaults to IN) and writes the matching gateway, currency and Razorpay mandate headroom with it; an owner country that is not a valid code is listed and left null. Stripe customers are moved by scripts/stripe-cutover.ts (not yet run). New checkout still requires a country.

Gateway legs

Stripe: Checkout mode 'setup' saves a card, no money; success_url /onboarding/success?subscriptionId={id}&session_id={CHECKOUT_SESSION_ID}; setup_intent.succeeded → TOKEN_SAVED → cycle-0 billing job charges off-session. A setup that carries a plan change (trial, upgrade, reactivation) instead schedules that change's own charge job.
Razorpay always uses the recurring popup with a 30-minute timeout; retries happen inside the open popup. Stripe Checkout expires after 30 minutes. First charge and mandate ceiling are server-computed. Verified payment.captured binds the confirmed token to the customer; browser verification is supplemental.
Success page polls GET /status/:id (owner only): UNPAID 'Confirming your payment…'; PENDING_SETUP/ACTIVE/TRIALING 'Success!' (+ 'Payment received.' only after a gateway charge); PAYMENT_FAILED 'Payment failed' + 'Start again'; closed or not found 'This checkout expired' + 'Start again'
Start again goes to /onboarding?step=2 for paymentPending users, else /portal/buy-new-subscription

Money locked at signup

lockedPriceAmount = stored per-asset monthly rate × assets × months (rate already includes interval discount and tax)
First charge = max(locked − discount, 0); no tax is added (prices are tax-inclusive); checkout shows the Total with 'inclusive of all taxes*'
Razorpay ceiling = locked + surge (1000/3000/5000, default 3000); the checkout 'Mandate limit' line shows the same number
The server derives gateway and currency from company registration country; client amounts and gateway choices are rejected.
Fixed coupons reject a currency mismatch; fixed promotions in another currency are excluded. Quote-created fixed coupons keep the quote currency.

Fixed defects

D11: the customer selects one discount; a coupon code reserves its slot at apply time under the coupon lock; the price is re-checked at checkout and a changed price needs confirmation. D48: a quote is accepted only after settlement; the public accept-without-payment route is deleted.
D49 resolved: the Stripe cancel URL points to an existing route
D47, D58, D60 resolved: an unusable quote discount is not offered, the plan stays purchasable, and the calculator prices from the server selection
A quote already sent stays valid until it expires even if its plan is deactivated afterwards; new quotes on a deactivated plan are refused
D90 resolved: the Free plan card no longer shows a hard-coded dollar sign