Payments & Razorpay OAuth

This page documents Zelly's server-side payment architecture in backend-api-fastify-nova ("Nova"): how a merchant connects Razorpay, how a payment is created / verified / captured, how payment webhooks are processed, and how a paid-but-unconfirmed ("browser-drop") order is recovered without ever double-charging or losing an order. The customer-facing UI side is documented separately in Zelly Checkout.

Gateway model

Payment gateways are configured per store. Nova resolves the active gateway config for a shop on every payment through one funnel (resolveGatewayConfigForShop → getPaymentGatewayConfig in shopifyCheckout.service.js), which reads two places:

Nova supports several gateways (Razorpay, PayU, PhonePe, Cashfree), but Razorpay is the one being taken live first, and it is the only gateway on the OAuth path — everything below is Razorpay-specific.

Razorpay Partner OAuth

Historically, merchants pasted their Razorpay key_id + key_secret into the seller panel, Nova stored them per store, and authenticated to Razorpay with HTTP Basic. Razorpay approved Zelly as a Technology Partner (OAuth), so merchants now click "Connect with Razorpay", log into their own Razorpay account, and authorize — no key sharing. Nova receives a per-merchant access_token / refresh_token / public_token and calls Razorpay with Bearer auth on the merchant's behalf.

Endpoints & config

Config lives in src/config/razorpay.js — dual test/live client pairs, active pair selected by RAZORPAY_OAUTH_MODE. All values come from the zelly/fastify-nova/env Secrets Manager secret, injected as env vars:

Connect flow (routes)

Four routes drive the connect lifecycle. Start/status/disconnect are JWT-protected (seller panel calls them for the logged-in store); the callback and webhook are public.

Seller panel (Atlas) "Connect with Razorpay"
        │  GET /checkout/razorpay/oauth/start  (store JWT)
        ▼
Nova signs a JWT state → 302 to auth.razorpay.com/authorize
        │
        ▼
Merchant Owner logs into their Razorpay account & authorizes
        │  302 back to RAZORPAY_OAUTH_REDIRECT_URI?code&state
        ▼
GET /checkout/razorpay/oauth/callback  (public)
   verify state JWT → POST auth.razorpay.com/token (grant=authorization_code, mode)
   → seal access/refresh tokens → write checkouts_credentials + checkout_settings
   → upsert razorpay_oauth_accounts (account_id → store_id)
        │  302
        ▼
Seller panel settings ?razorpay=connected  → status shows "Connected · acc_xxx · test"

Token lifecycle & storage

Tokens are stored per store in checkouts_credentials. The access & refresh tokens are sealed with secret-box.js (AES-256-GCM, key from ID_ENCRYPTION_KEY) — never stored in plaintext, never in a task definition.

Refresh & 401 handling

• Proactive refresh. Before a payment call, if the access token expires within 24h, Nova refreshes it (grant_type=refresh_token against the issuing client pair — that's why client_id/mode are stored) and persists the new tokens.
• Reactive refresh. A 401 from Razorpay triggers a single refresh-then-retry before giving up.

Payment path — Basic → Bearer

Every Razorpay call switches from Basic to Bearer when auth_mode === 'oauth' (via a small razorpayAuthConfig(cfg) helper that returns either a Basic auth block or a Bearer Authorization header). The key behavioural differences from the legacy key path:

Payment webhooks (Partner)

Handled in razorpayWebhookHandler.service.js via POST /checkout/razorpay/webhook. Every event is written to an audit table first, then acted on. The handler never re-charges.

Browser-drop recovery (paid-but-unconfirmed)

Placing a paid order is a two-step flow: POST /checkout/initiate creates a pending_payment stub and locks the amount; the browser charges the card; POST /place-order verifies and confirms. If the browser is lost after the charge but before /place-order, the money is captured but no order exists. Recovery places that order server-side.

Design: persist a lossless payload, don't reconstruct

POST /checkout/initiate  (prepaid)
   → create pending_payment stub  (store orders table)
   → saveRecoveryPayload() → checkout_recovery_payloads (lossless payload, status=pending)
   → payment_transactions link row  (gateway_order_id ⇄ local_order_id = stub)
        │
        ▼  browser charges card … then drops (never calls /place-order)
        │
        ▼  Razorpay captured the payment
   ┌────────────────────────┬─────────────────────────────────┐
   │ Reconciler (primary)   │ Partner webhook (fast path)      │
   │ 5-min sweep, 4-min     │ payment.captured → resolve stub  │
   │ grace, polls Razorpay  │ via payment_transactions link    │
   └───────────┬────────────┴──────────────┬──────────────────┘
               ▼                            ▼
          placeOrderFromStub()  →  enqueue place-order-post worker
               │
               ▼   worker places the Shopify order, attaching the captured payment

Every guard (payments must not fail)

placeOrderFromStub (in stubPlacement.service.js) applies these checks before enqueuing; any failing check skips placement (never throws into the payment path):

1. Lossless payload exists. No persisted payload → skip no_recovery_payload (flagged for manual review; never guesses).
2. Stub still pending_payment. Already confirmed / cancelled / expired → skip.
3. Amount matches. Captured amount must equal the stub's locked total (± ₹1) or it will not place.
4. Not already refunded. Checked against the ledger.
5. Idempotency claim on the Razorpay payment id. The exactly-once linchpin — see below.
6. Fix A stub-row lock in mirrorCheckoutOrderToStoreDb is the final guard inside the worker.

Failure handling: if the enqueue itself fails, the idempotency claim is released so the next tick retries. If shopifyPlaceOrder fails for a captured (prepaid) payment, the worker records a refund request and marks the stub shopify_failed — money is never silently kept, and it never retries forever.

Enabling & flags

Two non-secret env vars (wired as Terraform variables on the fastify_nova module, shared by the reconciler and the webhook fast-path):

Staging has both set to "1" in terraform/environments/staging/main.tf; production keeps them off until validated on staging.

# Flip a single env var on the running staging service without a code deploy:
aws ecs describe-task-definition --task-definition zelly-staging-fastify-nova:<N> \
  --region ap-southeast-1 --query taskDefinition > td.json
# edit RECONCILE_ALLOW_PLACEMENT → "1", strip read-only fields, then:
aws ecs register-task-definition --region ap-southeast-1 --cli-input-json file://td.json
aws ecs update-service --cluster zelly-staging --service fastify-nova \
  --task-definition zelly-staging-fastify-nova:<N+1> --region ap-southeast-1

Go-live checklist (production cutover)

1. Set RAZORPAY_OAUTH_MODE=live + the live client pair in the production zelly/fastify-nova/env secret. Force-redeploy (ECS does not hot-reload secrets).
2. Register the production redirect URI and the webhook URL on the prod partner app (dev & prod allowlists are separate).
3. Reconnect existing merchants. OAuth-only means key-based prod merchants' checkout breaks at cutover unless they reconnect — needs merchant comms + a reconnect window.
4. Rotate any client secrets that were pasted into reference configs / chats during development.
5. Apply the two SQL tables to the production astro_primary.
6. Validate a real ₹1 live payment end-to-end (order → checkout with public_token → verify → capture-if-authorized), confirm exactly one order, then refund it.
7. Only after the staging dry run + live ₹1 test pass, set production RECONCILE_JOB_ENABLED=1 and (once confident) RECONCILE_ALLOW_PLACEMENT=1.