Glossary
A quick-reference for the domain terms, product names, and acronyms a new owner will hit while reading the MVS Pay codebase and these docs. Each entry is 1–2 sentences plus a pointer to the real code path or the page that goes deeper.
This page is deliberately honest: where a term names something that is a 501
stub, deferred per an ADR, or assumed-but-not-yet-provisioned, the entry says so
in line. If a definition here disagrees with the source file it cites, trust the
source file and fix this page.
The single most important mental model: Hyperswitch is the source of truth for the payment; MVS code only ever holds opaque Hyperswitch IDs and tokenized references. Almost every term below is either part of Hyperswitch, part of the thin MVS extension layer wrapped around it, or part of the infrastructure that runs them. If you only read one other page, read The Hyperswitch Pivot.
How the pieces fit together
This diagram orients the rest of the glossary — most terms are a node, an edge, or a label on this picture.
Core platform terms
Hyperswitch
Juspay’s open-source (Apache-2.0) payment-orchestration platform, self-hosted at
pinned version v1.123.1 on the mvs-prod EKS payments namespace
(ADR-001). It is the source of
truth for payment_intent, payment_attempt, refund, dispute, mandate,
customer, merchant_account, connector configs, and routing rules. Comprises a
router, producer/consumer schedulers, a Redis→DB drainer, a Control Center admin
UI (v1.38.4), and a card-vault (v0.7.0). See
The Hyperswitch Pivot.
HyperLoader
Hyperswitch’s browser-side JavaScript Web SDK, wrapped with MVS theming by
@mvs/mvs-pay-ui. It tokenizes card data directly from the browser into the
Hyperswitch card-vault, which is exactly why raw PANs never transit MVS
application code. Configured with NEXT_PUBLIC_HYPERSWITCH_PUBLISHABLE_KEY; see
Checkout UI Components.
payment_intent
The Hyperswitch primitive representing a single intended payment (one or more
payment_attempts hang off it). MVS extension data (surcharges, tips, healthcare
line items, Level 2/3 data) is persisted in the extensions DB keyed by the
opaque payment_intent ID — there is no foreign key across the two
databases. See Payment Lifecycle.
merchant_connector_account (MCA)
The Hyperswitch record that binds a merchant to one configured connector and
holds that connector’s raw API credentials. Because the secrets live only
here, the MCA is part of the PCI surface and is configured post-deploy in the
Control Center, never in MVS code or the Helm chart. MVS keeps an indexable
sidecar (MerchantConnectorExtension, keyed by hyperswitch_merchant_connector_id)
alongside it — see ADR-008
and Connector Configuration.
Connector
A downstream payment processor that Hyperswitch routes to via an MCA. Five are in
scope: Stripe (HeaderKey auth), Adyen (SignatureKey), Cybersource
(SignatureKey), Braintree (BodyKey), and Finix (BodyKey), plus
ctp_visa / ctp_mastercard for Click to Pay V2. Post-pivot, Finix is just
one connector among five — see the Finix entry below.
decision-engine
Juspay’s standalone multi-armed-bandit routing engine (image v1.4.16), deployed on EKS via a custom in-repo Helm chart authored in Phase 4 (no first-party chart exists upstream). It drives Hyperswitch’s per-attempt connector selection — see MAB below and Decision Engine runbook.
MAB (Multi-Armed Bandit) / Dynamo
The intelligent-routing strategy implemented by the decision-engine: it treats each connector as a “bandit arm” and learns which connector maximizes success rate per cohort, rather than using static priority rules. “Dynamo” is Hyperswitch’s name for this routing layer. See Routing & Smart Retries.
GSM (gateway_status_map)
A Hyperswitch table that maps each connector’s raw decline/status codes to a normalized outcome and a retry decision. MVS seeds per-connector decline-code rules into the GSM so that Smart Retries know which failures are worth retrying. See Smart Retries runbook.
Smart Retries
Hyperswitch-native decline recovery: when an attempt fails, the router can
auto-retry against another connector based on the GSM rules, gated per profile by
is_auto_retries_enabled and max_auto_retries_enabled. It runs entirely
inside Hyperswitch (self-serve OSS, no Juspay handshake); MVS only exposes a
config surface and surfaces the retry chain in the UI. See
Routing & Smart Retries.
Revenue Recovery / dunning
Hyperswitch’s subscription-recovery feature, handed the retry-orchestration
responsibility per ADR-011. Hyperswitch
owns retry timing, BIN-aware curves, and per-attempt connector selection; MVS
keeps subscription state (the ACTIVE → PAST_DUE → UNPAID machine), billing
line items, invoice generation, and the /revenue-recovery UI. “Dunning” is the
industry term for this dunning/retry cycle on failed recurring charges. Outcomes
arrive via apps/mvs-pay-extensions/src/routes/webhooks-revenue-recovery.ts
(HMAC-verified). Lives behind a feature flag so it can be rolled back. See
Revenue Recovery.
MoR (Merchant of Record)
The legal entity that appears as the seller and bears liability/tax for a transaction. MVS uses a hybrid model per ADR-002: per-tenant MoR by default, with an opt-in Platform Organization tier.
MoR is only partially built. Phase 1 ships only the toggle
(MerchantExtension.isPlatformOrgMember); the full Hyperswitch Platform-Org
sub-merchant KYC integration is deferred. app/api/merchants/[id]/mor/route.ts
only writes the local flag with no upstream Hyperswitch call, and
app/api/onboarding/{remediation,resubmit}/route.ts return 501. There is no
real KYC gate today — lib/auth-server.ts infers “approved” from any ENABLED
connector. See ADR-002.
Healthcare & compliance terms
IIAS (Inventory Information Approval System)
The card-network framework (with IRS Pub 502) that lets an HSA/FSA card
auto-substantiate a payment when at least 90% of the dollar amount is for
qualified medical categories; below that threshold the merchant must supply manual
substantiation. The rule’s math is framework-free in
packages/mvs-pay-sdk/src/lib/iias.ts so it runs identically in the SDK,
extensions, and the UI. Export lives at
apps/mvs-pay-extensions/src/routes/iias-export.ts; see the
IIAS Substantiation runbook.
The IIAS receipt PDF (apps/mvs-pay-extensions/src/services/receipt-pdf.ts)
is flagged as not fully wired — treat receipt generation as a triage item, not a
guaranteed working path.
PCI scope
The set of components that touch raw cardholder data and therefore fall under PCI
DSS obligations. The defining win of the pivot is that this ring collapsed to
just two Hyperswitch containers — the router and the card-vault. Everything MVS
owns (apps/mvs-pay, apps/mvs-pay-extensions, the pay-crons worker, both SDKs)
is out of PCI scope because cards are captured client-side by HyperLoader and
MVS only ever sees IDs and tokens. See
The Hyperswitch Pivot.
Architecture & data terms
Sidecar extension table
The MVS data pattern (ADR-008):
MVS-specific fields that decorate a Hyperswitch entity live in their own Prisma
table keyed by the entity’s opaque hyperswitch_*_id string, with no
cross-database FK. Reads join via the SDK, not SQL. Examples:
MerchantConnectorExtension, transfer_extensions. The schema squashed to one
authoritative baseline migration (20260101000000_squashed_baseline, 30 tables);
migrations are forward-only. See Data Model.
Finix
The payment processor MVS was built on before the pivot. It is now just one
of five connectors plugged into Hyperswitch via an MCA. The name lingers as a
drift trap: lib/api-client.ts is still a Finix error-code map, and field
names like finixMerchantId / finixEnabled now carry Hyperswitch IDs. New code
should not add Finix vocabulary. See The Hyperswitch Pivot.
MVS_PAY_EXTENSIONS_INTERNAL_SECRET (internal secret)
The single shared secret (x-internal-secret header) that authenticates every
SDK→extensions call (ADR-010).
This is the one real flagged security gap. Per-user mvs-auth JWT validation
is deferred, so phiAudit.logAccess records organizationId but a null
userId, and an upstream compromise has full payments blast radius. Mitigated
by rate-limiting, WAF, and quarterly rotation; the plan is to add JWT validation
alongside the secret and decommission it over a 90-day overlap. See
Secrets Rotation runbook.
Infrastructure terms
mTLS (mutual TLS)
Both sides of a connection present and verify certificates. In MVS Pay it is
provided by Istio inside the EKS payments namespace so service-to-service
traffic (e.g. extensions ↔ Hyperswitch router) is mutually authenticated and
encrypted. See GitOps & Kubernetes.
ESO (External Secrets Operator)
The Kubernetes operator that syncs secrets from Infisical into the cluster via
the infisical-payments ClusterSecretStore. The extensions ExternalSecret
expects 13 keys under /apps/mvs-pay/mvs-pay-extensions/; pay-crons expects 12 —
they must be populated or pods will not start (e.g. decision-engine needs
REDIS_URL). See Secrets Management.
ArgoCD (Argo CD)
The GitOps reconciler (v3.4.2, chosen over Flux per
ADR-005) that syncs the payments
namespace from deploy/. Uses the multi-source Application pattern (upstream
chart + in-repo reviewable values). See GitOps & Kubernetes.
Blocker as committed: all five deploy/argo/*-application.yaml use
repoURL: https://github.com/abzholdings/mvs-pay.git. If the real org is
MVS-CLOUD, Argo CD reconciles nothing. The Kustomize bases/overlays also
carry literal REPLACE_ME_REGISTRY / REPLACE_ME_IMAGE_SHA / AWS_ACCOUNT_ID
placeholders. See Deployment Readiness.
Temporal / pay-crons
Temporal is the durable workflow engine; pay-crons is the MVS worker on
its pay-crons task queue (package @mvs/pay-temporal-workflows, image
mvs-cloud/pay-crons-worker:<sha>), running async/batch jobs: webhook DLQ
drainer, instant-payout settlement, residual estimation, dispute SLA, device
health, and success-rate reconcile. Its Argo PreSync Job registers schedules and
fails without a live Temporal endpoint (TEMPORAL_ADDRESS / _NAMESPACE /
TLS PEM keys must be in Infisical first). Out of PCI scope. See
Temporal Worker.
Plaid / instant payout
Plaid links a merchant’s bank account for ACH; instant payout is the
resulting fast-settlement flow (models PlaidItem, PayoutMethod,
InstantPayoutRequest). Routes live under
apps/mvs-pay-extensions/src/routes/{plaid,instant-payouts}; settlement is
handled async by the pay-crons worker. Returns honest 503 until
PLAID_CLIENT_ID / PLAID_SECRET / PLAID_WEBHOOK_SECRET are provisioned;
PENDING_EXPIRATION currently only logs. See
Payouts & Instant Payouts and the
Plaid Link runbook.
Quick-reference table
Related reference
The secrets and config flags referenced above, with their Infisical paths.
The one-page mental model that grounds every term here.
ADR-001 through ADR-011 — the “why” behind these choices.
The known blockers (repoURL, placeholders, 501 surfaces) in one place.