Architecture

MVS Pay is a payment-orchestration monorepo for MVS Cloud. It was pivoted from a Finix-direct architecture onto self-hosted Hyperswitch (Juspay’s open-source orchestration platform, OSS v1.123.1, Apache-2.0). All planned work — Phases 0 through 5, milestones M0–M28 — is built and merged to main, followed by two rounds of gap-audit remediation. The application code is largely complete and the repo is green; what is not done is live infrastructure provisioning, cross-repo consumer cutovers, and a handful of honest 501 surfaces. Those gaps are flagged throughout this page and detailed in Deployment Readiness.

The system is best understood as five layers, top to bottom:

The defining architectural theme is maximum native-Hyperswitch bias (ADR-007): Smart Retries, decision-engine routing, Cost Observability, and Revenue Recovery are all delegated to Hyperswitch. MVS keeps only what Hyperswitch does not model — Plaid instant payouts, POS devices, residuals, custom billing, and subscription state — in ~15 Prisma models plus sidecar extension tables keyed by opaque Hyperswitch IDs.

The system diagram

The same picture as an ASCII sketch, matching the canonical diagram in docs/architecture/hyperswitch-pivot.md:

Consumer apps                               Browser checkout
(healthos, mvs-c2,                          (any consumer's checkout page)
 apps/mvs-pay UI itself)                          │
        │                                         ▼
        │                                  ┌─────────────┐
        ▼                                  │@mvs/mvs-pay │ ◄─ wraps HyperLoader
┌──────────────────┐                       │     -ui     │     + MVS theme
│@mvs/mvs-pay-sdk  │                       └──────┬──────┘
│ (typed Node SDK) │                              │
└─────────┬────────┘                              ▼
          │                              Hyperswitch HyperLoader
          │ HTTPS + internal-secret      (browser-side; tokenises
          ▼                               cards directly to vault)
┌─────────────────────────────────┐                │
│   apps/mvs-pay-extensions       │                │
│   (Hono service in payments ns) │                │
│   - Wraps Hyperswitch API       │                │
│   - Persists MVS extension data │                │
│   - Audit logging               │                │
└──┬─────────────────┬────────────┘                │
   │                 │                              │
   ▼                 ▼                              ▼
┌────────────┐  ┌─────────────────────────────────────┐
│ MVS Neon   │  │      Hyperswitch (self-hosted)      │
│ (extensions│  │  router (8080) · producer · consumer │
│  schema)   │  │  drainer · control-center · vault    │
│            │  │  ── Postgres (hyperswitch-prod)      │
│ PayoutMethod  │  ── Redis                            │
│ PlaidItem  │  │  Connectors: stripe, adyen,          │
│ Device …   │  │  cybersource, braintree, finix       │
└────────────┘  └─────────────────────────────────────┘

Layer 1 — Consumer apps and @mvs/mvs-pay-sdk

Other MVS apps consume payments as a package, never by talking to Hyperswitch directly. The published, typed Node SDK is the single entry point.

• @mvs/mvs-pay-sdk — a server-side MvsPayClient HTTP client. Consumers import it and call namespaced methods (payments, refunds, customers, disputes, mandates, payouts / instantPayouts / payoutMethods, devices, merchants, routing / smartRetries, billableItems, notifications, costObservability, revenueRecovery). It transparently injects the x-internal-secret, x-org-id / x-org-slug, and optional idempotency-key headers, retries 5xx / network errors with exponential backoff (3 retries), and throws every non-2xx as a typed MvsPayApiError.
• It ships a ./legacy shim subpath (a 30-day cutover overlap for consumers still on the old client) and a ./mock subpath for consumer CI. Published as a linked release group with @mvs/mvs-pay-ui to the Buildkite Package Registry (mvs-cloud/pay/npm).

The consumers today:

For the full namespace catalog, error envelope, and rate limits, see The SDK.

Layer 2 — apps/mvs-pay, the Next.js UI / BFF

apps/mvs-pay is a Next.js 16 (App Router, React 19) merchant + operator dashboard plus a public per-tenant checkout portal. It is the UI and backend-for-frontend layer over the pivot. Deployed to Vercel at pay.mvscloud.com today; the planned production host is www.mvspay.io (see Domain & DNS).

How it talks to the rest of the system:

• Server-side route handlers under app/api/* construct an MvsPayClient (via apps/mvs-pay/lib/mvs-pay-client.ts — mvsPayClientFromAuth() builds an org-scoped client, mvsPayApiError() maps SDK errors to an HTTP envelope) and proxy orchestration calls to extensions. Example: the virtual-terminal sale path is apps/mvs-pay/app/api/virtual-terminal/route.ts.
• Direct reads of the dedicated MVS Postgres go through Prisma (apps/mvs-pay/lib/payments-db.ts) for sidecar/extension data — e.g. app/api/transactions/route.ts UNIONs transfer + manual_payment rows, always scoped where: { organizationId }.
• Auth is Better Auth via the central mvs-auth service, with two session paths: a central same-domain cookie and a local JWT cookie minted by a cross-domain token-exchange callback (app/api/auth/callback/route.ts).

The UI’s surface (transactions, payouts, disputes, customers, devices, payment links, billing, connectors, routing, revenue recovery, virtual terminal, onboarding, settings, and the public {slug} checkout portal) is documented in Merchant & Operator UI.

Layer 3 — @mvs/mvs-pay-ui, browser checkout via HyperLoader

@mvs/mvs-pay-ui is a published, web-only (ADR-009) React component library that wraps Hyperswitch’s HyperLoader Web SDK with MVS theming. Exported components include:

• <MvsPayCheckout> — the full embedded checkout
• <MvsPayPaymentMethodForm> — a payment-method capture form
• <MvsPayCheckoutLink> — a hosted-link launcher
• <MvsPayInstantPayoutPicker> — Plaid-backed payout-destination picker
• <MvsPaySavedCardsWidget> — saved payment-method widget

The loader lives in packages/mvs-pay-ui/src/hyper-loader.ts. loadHyperLoader is idempotent and pulls Hyperswitch’s HyperLoader.js (default https://beta.hyperswitch.io/v1/HyperLoader.js) using NEXT_PUBLIC_HYPERSWITCH_PUBLISHABLE_KEY. Apple Pay and Google Pay are handled through HyperLoader; Click to Pay V2 is enabled purely by adding ctp_visa / ctp_mastercard connectors — no separate UI component.

Layer 4 — apps/mvs-pay-extensions, the Hono orchestration service

The internal, service-to-service orchestration layer (Hono 4.12.23, dev port :3005) running on EKS in the payments namespace. It is the only component that calls Hyperswitch.

Responsibilities:

• Wraps Hyperswitch’s REST API. SDK namespaces map onto /v1/* routes: payments, refunds, customers, disputes, mandates, payouts / instant-payouts / payout-methods, devices, merchants, routing / routing-dynamic / smart-retries, revenue-recovery, cost-observability, payment-links, billable-items, notifications, iias-export, payment-method-sessions. Route source lives in apps/mvs-pay-extensions/src/routes/.
• Persists MVS-specific extension data in its own Neon Postgres via Prisma — healthcare line items, surcharges, tips, Level 2/3 data, POS device inventory, Plaid instant payouts, residuals.
• Ingests webhooks at three signature-verified routes (webhooks-hyperswitch, webhooks-plaid, webhooks-revenue-recovery) — see the webhook flow.
• Carries rate-limit, idempotency, and audit-log (phiAudit.logAccess) middleware. Every DB query is tenant-scoped by organizationId.

It holds the MVS_PAY_EXTENSIONS_INTERNAL_SECRET (service auth) and the HYPERSWITCH_WEBHOOK_SECRET / payment_response_hash_key (webhook HMAC verification). It holds no raw card data and no connector credentials.

Why a separate Hono service rather than Next.js API routes (ADR-006): it gives a clean PCI / non-PCI boundary, lets cross-repo consumers call it directly, and unlocks EKS operational features (mTLS, network policies) that Vercel functions lack. Why Hono rather than tRPC (ADR-003): tRPC’s coupled types don’t cross repo boundaries; a stable HTTP contract fronted by the typed SDK gives equivalent safety. Full detail in Extensions Service.

Layer 5 — The payment core and async plane

Hyperswitch (self-hosted)

The payment orchestration platform and the source of truth for payment_intent, payment_attempt, refund, dispute, mandate, customer, payment_method, merchant_account, connector configs, and routing rules. Self-hosted on the mvs-prod EKS cluster, payments namespace, via the hyperswitch-app Helm chart. It comprises:

Backed by its own Neon Postgres (hyperswitch-prod) and Redis. Fronts five connectors via merchant_connector_account: Stripe (HeaderKey), Adyen (SignatureKey), Cybersource (SignatureKey), Braintree (BodyKey), and Finix (BodyKey) — Finix is now one connector among many, no longer the platform. Connectors ship empty and are configured post-deploy via Control Center; raw credentials live only here.

decision-engine

juspay/decision-engine v1.4.16 — Hyperswitch’s multi-armed-bandit (MAB) / Dynamo intelligent routing engine. Deployed on the payments namespace via a custom in-repo Helm chart (deploy/decision-engine/) authored in Phase 4, because no first-party chart exists upstream. It drives per-attempt connector selection. See the decision-engine runbook.

pay-crons Temporal worker

packages/temporal-workflows (@mvs/pay-temporal-workflows) builds the pay-crons worker, deployed on the payments namespace. It runs the async/batch plane and is out of PCI scope. The registered workflows (src/workflows/, scheduled via src/schedules/pay-crons.ts):

• webhookDlqDrainerWorkflow — re-runs failed webhook dispatches
• instantPayoutSettlementWorkflow — settles instant payouts
• residualEstimationWorkflow / residualChecksWorkflow — residual estimation
• disputeSlaMonitorWorkflow — dispute SLA monitoring
• deviceHealthMonitorWorkflow — POS device health
• successRateReconcileWorkflow — success-rate reconciliation
• hyperswitchEventReplayWorkflow — event replay

See Temporal Worker.

Data: packages/mvs-pay

The dedicated Prisma client wrapper + schema for the MVS extensions DB (MVS_PAY_DATABASE_URL, Neon mvs-pay-extensions-prod; generated client @prisma/mvs-pay-client). It holds ~15 MVS-specific models plus sidecar extension tables keyed by opaque Hyperswitch ID strings — no FK across DBs; reads join via the SDK, not SQL.

Why Neon (ADR-004): branchable dev/staging + built-in PITR, two projects (hyperswitch-prod router DB, mvs-pay-extensions-prod MVS data), with PgBouncer pooling required for Vercel cold-start connection storms.

The PCI boundary

Pre-pivot, apps/payfac-gateway was the sole PCI-scoped process, holding raw Finix credentials and brokering every card-data round-trip.

Post-pivot, the boundary collapses to just the Hyperswitch router + card-vault. Everything else — apps/mvs-pay, apps/mvs-pay-extensions, the pay-crons worker, and both published packages — is out of scope, because:

• Card data is captured client-side via HyperLoader straight into the vault.
• MVS code only ever sees Hyperswitch IDs + tokenized references, never raw PANs.
• Raw connector credentials live only in Hyperswitch’s merchant_connector_account config.

This is a major simplification: tainted node pools, restricted egress, weekly secret rotation, and per-process attestations apply only to the Hyperswitch services, not to MVS application code. The PCI DSS L1 SAQ-D attestation and per-connector BAAs are tracked in the security cadence runbook.

End-to-end data flows

The flows below are the load-bearing paths through the system. They are drawn from the verified architecture map and docs/HANDOFF.md §2.

Charge / payment authorization (server-initiated)

consumer ─sdk.payments.create─▶ extensions /v1/payments ─REST─▶ HS router ─▶ connector
                                      │
                                      └─▶ Prisma: transfer_extensions (keyed by intent id)

Browser tokenization (the PCI-isolating flow)

The consumer checkout page renders <MvsPayCheckout>; HyperLoader tokenizes the card directly into the vault using the publishable key; subsequent confirm/capture goes back through the normal SDK → extensions → router path with only IDs and tokenized references.

Webhook ingest (the async state machine)

Hyperswitch delivers payment-outcome webhooks to POST /webhooks/hyperswitch on extensions (src/routes/webhooks-hyperswitch.ts). These are not internal-secret authenticated; the raw body is HMAC-verified (x-webhook-signature-512, with a x-webhook-signature-256 fallback) using the merchant’s payment_response_hash_key.

Two adjacent signature-verified ingress routes exist: POST /webhooks/revenue-recovery and POST /webhooks/plaid. Full event catalog in the Developer Guide / Payments & Refunds.

Instant payout / ACH (Plaid)

apps/mvs-pay / SDK ─▶ extensions /plaid · /instant-payouts · /payout-methods
                            │
                            ├─▶ Plaid (ACH bank-account linking)
                            │     models: PlaidItem · PayoutMethod · InstantPayoutRequest
                            │
                            └─▶ webhooks-plaid (logs sanitized to {code,message,status};
                                  no access_token/public_token leak)
settlement of instant payouts ──▶ pay-crons instantPayoutSettlementWorkflow (async)

The UI / SDK drive Plaid bank-account linking through the extensions /plaid, /instant-payouts, and /payout-methods routes. Plaid webhooks land at webhooks-plaid.ts (error logs are sanitized to {code, message, status} — no token leakage). Actual settlement is performed asynchronously by the pay-crons worker. See Payouts & Instant Payouts and the Plaid Link runbook.

Revenue recovery / dunning (ADR-011, a two-way seam)

Per ADR-011, MVS hands dunning/retry orchestration to Hyperswitch Revenue Recovery (a per-feature instance of the native-bias principle). MVS configures the retry plan and registers a webhook URL via the SDK; Hyperswitch owns retry timing, BIN-aware curves, and per-attempt connector selection. Outcomes return to webhooks-revenue-recovery.ts (HMAC-verified) and single-writer update BillingSubscription recovery fields; the subscription state machine (ACTIVE → PAST_DUE → UNPAID) stays MVS-side. The whole feature is behind a flag so it can be rolled back while keeping the SDK contract. See Revenue Recovery and ADR-011.

Where to go next

For the orchestrated REST contract itself, see the API Reference tab.