Environment Variables | MVS Developer Docs

This page is the reference for the environment variables that matter across the three MVS Pay runtime surfaces. It is grounded in the actual code that reads process.env, the ExternalSecret manifests under deploy/, and the .env.example contracts — not in aspiration. Where a variable is optional, defaulted, deferred, or only consumed in a non-obvious place, that is called out explicitly.

URLs and domains are not environment variables in this platform. Per packages/config/urls.ts, the rule is: env is for secrets, database DSNs, and third-party credentials only — public hostnames are hardcoded and derived from the environment suffix. The handful of NEXT_PUBLIC_* domain overrides below exist for local development and CORS, not for production routing. See Domain & DNS.

The three surfaces

There are three places code reads configuration, and they do not share a single .env. Each surface has its own delivery mechanism.

Surface	Code	Where env is set	How it loads
UI	`apps/mvs-pay` (Next.js)	Vercel project env vars (`mvs-pay-app`)	`process.env` at build time (for `NEXT_PUBLIC_*` and Prisma generate) and at request time
Extensions	`apps/mvs-pay-extensions` (Hono)	Infisical `/apps/mvs-pay/mvs-pay-extensions/*` → ESO → K8s Secret	`getConfig()` in `apps/mvs-pay-extensions/src/config/index.ts`; also `@mvs/secrets` injects at boot
Worker	`pay-crons-worker` (`packages/temporal-workflows`)	Infisical `/apps/mvs-pay/pay-crons-worker/*` → ESO → K8s Secret	`process.env`, with `@mvs/secrets` bootstrap (see `src/worker/start.ts`)

The extensions service and the worker share the same Infisical scope name (mvs-pay) inside @mvs/secrets (SECRETS_SCOPE = "mvs-pay" in packages/temporal-workflows/src/worker/start.ts), but they pull from different Infisical folder paths (mvs-pay-extensions/ vs pay-crons-worker/). Several keys are duplicated across both folders on purpose — there is no single source row for, e.g., MVS_PAY_DATABASE_URL. Rotating it means updating it in every folder it appears.

How loading works per surface

UI (Vercel)

Next.js inlines NEXT_PUBLIC_* at build time, so changing one requires a redeploy. Server-only vars (MVS_PAY_DATABASE_URL, MVS_PAY_EXTENSIONS_INTERNAL_SECRET, RESEND_API_KEY, APPLE_PAY_*) are read at request time. MVS_PAY_DATABASE_URL is also needed at build for Prisma client generation (packages/mvs-pay/prisma.config.ts).

Extensions (Hono on EKS)

createHonoApp() calls injectSecretsToEnv() from @mvs/secrets when isInfisicalConfigured() is true, then getConfig() validates everything through a Zod schema. Missing optional values fall back to defaults; a malformed value (e.g. a non-URL HYPERSWITCH_API_BASE_URL) throws at boot.

Worker (Temporal on EKS)

pay-crons-worker calls loadAppSecretsForRuntime() then reads process.env directly. Temporal connection vars have safe localhost defaults so the worker can run in dev without Infisical.

UI — `apps/mvs-pay` (Vercel)

The merchant/operator UI. Server-only secrets and a small set of build-time-inlined public keys.

Variable	Purpose	Where set	Required
`MVS_PAY_DATABASE_URL`	DSN for the dedicated mvs-pay extensions Postgres (Neon). Read by `@mvs/mvs-pay`’s Prisma client (`packages/mvs-pay/src/client.ts`) and required at build for `prisma generate`.	Vercel + Infisical	Required
`MVS_PAY_EXTENSIONS_INTERNAL_SECRET`	Shared service-to-service secret sent as the `x-internal-secret` header to the extensions service. Read in `instrumentation.ts` and `app/api/debug/secrets/route.ts`.	Vercel + Infisical	Required
`MVS_PAY_EXTENSIONS_URL`	Base URL of the extensions service the SDK client points at. (`MVS_PAY_EXTENSIONS_BASE_URL` is accepted as a fallback in `app/api/debug/secrets/route.ts`.)	Vercel	Required
`NEXT_PUBLIC_HYPERSWITCH_PUBLISHABLE_KEY`	Per-merchant Hyperswitch publishable key surfaced to the browser SDK via `@mvs/mvs-pay-ui`. Read in `components/payment-flow.tsx`. Inlined at build time.	Vercel	Required for live checkout
`RESEND_API_KEY`	Resend credential used by `@mvs/mail` to send payment-link emails. When unset, `POST /api/payment-links/[id]/send` returns an honest 503 (“Email is not configured”) rather than faking delivery.	Vercel + Infisical	Optional (feature-gated)
`RESEND_FROM_EMAIL`	From-address for `@mvs/mail` (env, with optional DB-config override).	Vercel + Infisical	Optional
`APPLE_PAY_DOMAIN_ASSOCIATION_PROD`	Apple Pay domain-association token served at `/.well-known/apple-developer-merchantid-domain-association` in production. See below.	Vercel + Infisical	Optional (wallets)
`APPLE_PAY_DOMAIN_ASSOCIATION_DEV`	Same token for non-production.	Vercel + Infisical	Optional (wallets)
`APPLE_PAY_DOMAIN_ASSOCIATION_<SLUG>`	Per-domain override for embed-host deployments. `<SLUG>` = host uppercased, non-alphanumerics → `_` (e.g. `partner.example.com` → `PARTNER_EXAMPLE_COM`).	Vercel + Infisical	Optional
`NEXT_PUBLIC_BASE_DOMAIN`	Overrides the platform base domain (`mvscloud.com`) for local dev. Also feeds `getValidBaseDomains()` for CORS origin validation.	Vercel (dev/preview)	Optional
`NEXT_PUBLIC_ROOT_DOMAIN`	Read in `proxy.ts` for host/subdomain routing. Note this is distinct from `NEXT_PUBLIC_BASE_DOMAIN` — `urls.ts` does not read it.	Vercel	Optional
`CONTROL_PLANE_DATABASE_URL`	Control-plane Postgres DSN. Used by `instrumentation.ts` boot checks and required by the Playwright auth fixtures.	Vercel + Infisical	Required where control-plane access is needed
`BETTER_AUTH_SECRET` / `MVSPAY_SESSION_SECRET`	Session-signing secret (`lib/session-secret.ts` prefers `MVSPAY_SESSION_SECRET`, falls back to `BETTER_AUTH_SECRET`).	Vercel + Infisical	Required for sessions
`INFISICAL_ENV`	Selects `dev` / `staging` / `prod`. Drives `getUrlEnvironment()` in `urls.ts`, cookie domain, and the Apple Pay prod/dev token selection.	Vercel	Required for correct env routing
`NEXT_PUBLIC_PAYMENTS_ENVIRONMENT`	`"live"` toggles the virtual-terminal live banner (`app/(dashboard)/virtual-terminal/page.tsx`).	Vercel	Optional
`NEXT_PUBLIC_MVS_PAY_INTERCOM_APP_ID` / `NEXT_PUBLIC_INTERCOM_APP_ID` / `NEXT_PUBLIC_INTERCOM_ENABLED`	Intercom widget config (`app/providers.tsx`). Set `NEXT_PUBLIC_INTERCOM_ENABLED=false` to disable.	Vercel	Optional
`VERCEL_ENV` / `VERCEL_URL` / `VERCEL_BRANCH_URL`	Set automatically by Vercel. Used for env detection and to add preview deploy URLs to trusted origins.	Vercel (auto)	Auto
`VERCEL_PREVIEW_ORIGINS_ALLOWED`	When `"true"`, accepts `.vercel.app` / `.vercel.sh` as trusted origins. Pulumi sets this on dev/preview only — must stay unset in production.	Vercel (dev/preview)	Optional

/api/debug/secrets only returns data when NODE_ENV/VERCEL_ENV is development and VERCEL_ENV is neither production nor preview (app/api/debug/secrets/route.ts). It still must never be relied on as a production diagnostic — treat it as a local-only convenience.

Apple Pay token lookup

The /.well-known/... route picks the env key at request time. Default key is prod/dev based on NODE_ENV / INFISICAL_ENV / VERCEL_ENV; a ?domain= query triggers a per-domain override lookup that falls back to the default.

A 404 is intentional when no token is configured — Apple’s verifier treats it as a clean “not set up” signal. See the Wallet Validation runbook and Wallets & Click to Pay.

Extensions — `apps/mvs-pay-extensions` (Hono on EKS)

Every variable here is read through getConfig() in apps/mvs-pay-extensions/src/config/index.ts (Zod-validated) unless noted. Defaults below are the schema defaults.

Variable	Purpose	Where set	Required
`HYPERSWITCH_API_BASE_URL`	Hyperswitch router REST base URL. Defaults to `https://hyperswitch.payments.internal`. Must be a valid URL or boot fails.	Infisical	Optional (defaulted)
`HYPERSWITCH_ADMIN_API_KEY`	Privileged admin key for `merchant_account`, `merchant_connector_account`, and routing operations. `isHyperswitchConfigured()` gates behaviour on its presence. Only this service and the worker hold it.	Infisical	Required for live ops
`HYPERSWITCH_WEBHOOK_SECRET`	Verifies inbound Hyperswitch webhook signatures.	Infisical	Required for webhooks
`HYPERSWITCH_DASHBOARD_URL`	Dashboard deep-link base for cost-observability links (`src/routes/cost-observability.ts`, has a built-in default).	Infisical	Optional
`MVS_PAY_EXTENSIONS_INTERNAL_SECRET`	Expected value of the `x-internal-secret` header. Constant-time compared in `src/middleware/auth.ts`. If unset, every authed request 401s.	Infisical	Required
`MVS_PAY_EXTENSIONS_PLATFORM_ADMIN_SECRET`	Elevated secret for platform-admin-only routes (`config.platformAdminSecret`).	Infisical	Required for platform-admin routes
`MVS_PAY_EXTENSIONS_CORS_ORIGINS`	Comma-separated allowlist of production CORS origins. In `development`, CORS is ``; otherwise defaults to `pay/healthos/c2.mvscloud.com`. Including `` in non-dev throws at boot (`src/app.ts`).	Infisical / env	Optional (defaulted)
`CONTROL_PLANE_DATABASE_URL`	Control-plane Postgres DSN (tenant + API-key lookup).	Infisical	Required where used
`MVS_PAY_DATABASE_URL`	Dedicated mvs-pay extensions Postgres DSN (Neon).	Infisical	Required
`REDIS_URL`	Redis for the API-key cache and distributed rate limiting.	Infisical	Required in prod
`INFISICAL_CLIENT_ID` / `INFISICAL_CLIENT_SECRET` / `INFISICAL_PROJECT_ID`	Machine-identity credentials. All three present ⇒ `isInfisicalConfigured()` true ⇒ secrets are injected at boot.	Infisical / K8s	Required for in-cluster bootstrap
`INFISICAL_ENV`	`dev` / `staging` / `prod`; also flips Plaid webhook prod handling (`src/routes/webhooks-plaid.ts`).	Infisical	Required
`PLAID_CLIENT_ID`	Plaid client id (non-secret).	Infisical	Required for Plaid
`PLAID_SECRET`	Plaid per-environment secret. `isPlaidConfigured()` needs both id + secret.	Infisical	Required for Plaid
`PLAID_ENV`	`sandbox` (default) / `development` / `production`.	Infisical	Optional (defaulted)
`PLAID_WEBHOOK_URL`	Absolute URL Plaid posts back to; must terminate at `/webhooks/plaid` in this service.	Infisical	Optional
`PLAID_WEBHOOK_SECRET`	Optional Plaid verification key.	Infisical	Optional
`PORT`	HTTP listen port. Default `3004`.	env	Optional (defaulted)
`NODE_ENV`	`development` / `staging` / `production`. Default `development`.	env	Optional (defaulted)
`API_KEY_CACHE_TTL_SECONDS`	API-key cache TTL. Default `300`.	env	Optional (defaulted)
`TENANT_DB_POOL_SIZE`	Per-tenant DB pool size. Default `5`.	env	Optional (defaulted)
`DEFAULT_RATE_LIMIT` / `RATE_LIMIT_WINDOW_SECONDS`	Legacy/global rate-limit knobs. Defaults `100` / `60`.	env	Optional (defaulted)
`MVS_PAY_RATE_LIMIT_<ROUTE>_MAX` / `..._WINDOW_SEC`	Per-route rate limits (`payments`, `refunds`, `payouts`, `disputes`, `webhooks`) read in `src/middleware/rate-limit.ts`. Each has its own default (e.g. payments 600/60s, webhooks 200/1s).	env	Optional (defaulted)
`DD_API_KEY` / `DD_SERVICE` / `DD_ENV`	Datadog APM/log/metric. `DD_API_KEY` is delivered via the ExternalSecret; service/env have defaults in `.env.example`.	Infisical	Optional

The single shared x-internal-secret model — not per-user JWTs — is a deliberate, documented decision. Per-user identity is not propagated to PHI audit trails yet (phiAudit.logAccess() logs userId: null). See ADR-010 and Authentication. The secret is rotated on a cadence — see Secrets Rotation.

Worker — `pay-crons-worker` (Temporal on EKS)

Entrypoint packages/temporal-workflows/src/worker/start.ts. Registers the mvs-pay workflows + activities on the pay-crons task queue. See the Temporal Worker surface.

Variable	Purpose	Where set	Required
`TEMPORAL_ADDRESS`	Temporal frontend address. Default `localhost:7233`.	Infisical	Required in prod
`TEMPORAL_NAMESPACE`	Temporal namespace. Default `default`.	Infisical	Required in prod
`TEMPORAL_TLS_CERT_PEM`	Client cert PEM for namespace mTLS. Optional locally; required against the prod Temporal cluster.	Infisical	Optional / prod-required
`TEMPORAL_TLS_KEY_PEM`	Client key PEM matching the cert.	Infisical	Optional / prod-required
`PAY_CRONS_TASK_QUEUE`	Task queue name. Default `pay-crons`.	env	Optional (defaulted)
`HYPERSWITCH_API_BASE_URL`	Consumed by worker activities (same meaning as extensions).	Infisical	Required for activities
`HYPERSWITCH_ADMIN_API_KEY`	Consumed by worker activities.	Infisical	Required for activities
`MVS_PAY_DATABASE_URL`	Consumed by `@mvs/mvs-pay` inside activities.	Infisical	Required
`MVS_PAY_EXTENSIONS_BASE_URL`	Base URL the success-rate reconcile activity calls back into the extensions service (`src/activities/success-rate-reconcile.ts`).	Infisical / env	Required for that activity
`INFISICAL_CLIENT_ID` / `INFISICAL_CLIENT_SECRET` / `INFISICAL_PROJECT_ID` / `INFISICAL_ENV`	Optional Infisical bootstrap via `loadAppSecretsForRuntime()`.	Infisical / K8s	Optional bootstrap
`DD_API_KEY`	Datadog. Delivered via the worker ExternalSecret.	Infisical	Optional

The TEMPORAL_TLS_CERT_PEM / TEMPORAL_TLS_KEY_PEM pair is optional in the worker code (it falls back to a plaintext connection), but the Temporal cluster is provisioned with TLS (see step 11 of External Provisioning), so in any real environment both are required.

Infisical layout

Production secrets live in the Infisical project mvs-pay, environment prod (and dev / staging). The folder paths the ExternalSecrets and runbook reference:

/apps/mvs-pay/mvs-pay-extensions/   # HYPERSWITCH_*, MVS_PAY_DATABASE_URL,
                                    # CONTROL_PLANE_DATABASE_URL, REDIS_URL,
                                    # MVS_PAY_EXTENSIONS_INTERNAL_SECRET,
                                    # MVS_PAY_EXTENSIONS_PLATFORM_ADMIN_SECRET,
                                    # INFISICAL_*, DD_API_KEY
/apps/mvs-pay/pay-crons-worker/     # TEMPORAL_*, HYPERSWITCH_*,
                                    # MVS_PAY_DATABASE_URL, INFISICAL_*, DD_API_KEY
/apps/mvs-pay/hyperswitch/          # HYPERSWITCH_DB_*, HYPERSWITCH_REDIS_*,
                                    # HYPERSWITCH_*KEYS, HYPERSWITCH_ADMIN_API_KEY,
                                    # HYPERSWITCH_WEBHOOK_SECRET
/apps/mvs-pay/legal/baa-status/*    # signed:YYYY-MM-DD | pending | not-required
/apps/mvs-pay/wallets/{org}/apple_domain_association
/apps/mvs-pay/connectors/{org}/taxjar/

The ExternalSecret manifests are the authoritative mapping from Infisical keys to in-cluster env vars:

1 # deploy/mvs-pay-extensions/base/externalsecret.yaml (excerpt)
2 spec:
3   secretStoreRef:
4     name: infisical-payments
5     kind: ClusterSecretStore
6   data:
7     - secretKey: MVS_PAY_EXTENSIONS_INTERNAL_SECRET
8       remoteRef:
9         key: /apps/mvs-pay/mvs-pay-extensions/MVS_PAY_EXTENSIONS_INTERNAL_SECRET
10     - secretKey: MVS_PAY_DATABASE_URL
11       remoteRef:
12         key: /apps/mvs-pay/mvs-pay-extensions/MVS_PAY_DATABASE_URL
13     # ...refreshInterval: 1h, deletionPolicy: Retain

Secrets Management

How Infisical, ESO, and Vercel fit together across the platform.

Secrets Rotation

The cadence and steps for rotating the internal secret and provider keys.

External Provisioning

What must exist outside the repo before any of this resolves.

Local Development

Running each surface with .env.local and no Infisical.

Required vs optional at a glance

The minimum each surface needs to boot meaningfully (not just survive Zod):

UI minimum

MVS_PAY_DATABASE_URL (build + runtime)
MVS_PAY_EXTENSIONS_URL + MVS_PAY_EXTENSIONS_INTERNAL_SECRET
INFISICAL_ENV (correct env routing / cookies)
Session secret (MVSPAY_SESSION_SECRET or BETTER_AUTH_SECRET)
NEXT_PUBLIC_HYPERSWITCH_PUBLISHABLE_KEY for live checkout
Email (RESEND_API_KEY) and wallets (APPLE_PAY_*) are feature-gated and degrade honestly when absent.

Extensions minimum

MVS_PAY_DATABASE_URL, CONTROL_PLANE_DATABASE_URL, REDIS_URL
MVS_PAY_EXTENSIONS_INTERNAL_SECRET (auth fails closed without it)
HYPERSWITCH_ADMIN_API_KEY (+ HYPERSWITCH_WEBHOOK_SECRET for webhooks)
INFISICAL_* for in-cluster secret bootstrap
Plaid (PLAID_CLIENT_ID + PLAID_SECRET) only if instant payouts are enabled.

Worker minimum

TEMPORAL_ADDRESS, TEMPORAL_NAMESPACE, TEMPORAL_TLS_CERT_PEM, TEMPORAL_TLS_KEY_PEM
MVS_PAY_DATABASE_URL
HYPERSWITCH_API_BASE_URL + HYPERSWITCH_ADMIN_API_KEY for activities
MVS_PAY_EXTENSIONS_BASE_URL for the success-rate reconcile activity.

Known gaps and caveats

No central registry. There is no single typed schema covering all three surfaces. Extensions has a Zod schema (config/index.ts); the UI and worker read process.env ad hoc. Adding a var means touching code, the relevant .env.example, and the relevant ExternalSecret.
Duplicate DSNs. MVS_PAY_DATABASE_URL, the HYPERSWITCH_*, and INFISICAL_* keys are stored in both Infisical folders. Rotation must hit every copy.
NEXT_PUBLIC_ROOT_DOMAIN vs NEXT_PUBLIC_BASE_DOMAIN. These are two different variables read by two different files (proxy.ts vs urls.ts). Don’t assume one feeds the other.
Vercel ⇄ Infisical sync is not codified in this repo. The UI’s secrets are listed in Infisical’s provisioning runbook, but the mechanism that lands them in the Vercel project env is operator-side and not represented by an ExternalSecret. Confirm the actual sync path with the platform owner.
infrastructure/secrets-management page. It is registered in docs.yml navigation but the source .mdx may not yet be present on disk — the cross-link above will 404 until that page is authored.