Payouts & Instant Payouts

This page covers how money leaves the platform: Hyperswitch-native payouts, their MVS settlement sidecar and approval workflow, payout methods (push-to-card debit cards and Plaid-linked ACH bank accounts), the Plaid Link → exchange flow, instant payouts against a linked method, and the async settlement reconciliation that the Temporal pay-crons worker performs.

The two architectural rules to internalize before reading further:

1. Hyperswitch is the source of truth for the money movement. Every payout is a Hyperswitch payout object. MVS only stores sidecar rows (SettlementExtension, InstantPayoutRequest, PayoutMethod, PlaidItem) for things Hyperswitch does not model — an approval gate, funding-attempt history, ACH bank linking, and operator visibility. See Hyperswitch pivot.
2. There are two services. The Next.js dashboard app (apps/mvs-pay) is the customer/operator-facing API; it proxies to the extensions service (apps/mvs-pay-extensions, a Hono app) which owns the sidecar tables, the Plaid integration, and the tenant-scoped Prisma client. See Extensions service.

Vocabulary

These models are also documented in Data model.

Plain payouts (Hyperswitch-native)

The dashboard’s payout surface is a thin pass-through to Hyperswitch with a settlement sidecar attached on create.

Extensions service routes

apps/mvs-pay-extensions/src/routes/payouts.ts is a near-verbatim proxy to the Hyperswitch payouts API — no sidecar logic, no tenant table writes:

Errors are mapped through mapErr: a HyperswitchApiError is re-emitted as { error: <responseBody> } with the upstream status (via asContentfulStatus); anything else re-throws. The idempotency-key header is forwarded to Hyperswitch on create.

See the API Reference tab for request/response shapes.

Dashboard app: payout + sidecar

apps/mvs-pay/app/api/payouts/route.ts is where the settlement sidecar is created. On POST /api/payouts:

1. Authenticate with the settlements:write scope.
2. Create the Hyperswitch payout via the SDK (mvsPayClient(...).payouts.create). An idempotency-key header is honored; otherwise one is synthesized as mvspay_<orgId>_<uuid>.
3. If the response has no payout_id, fail 502 — we refuse to persist a sidecar we cannot key.
4. Upsert a SettlementExtension keyed on hyperswitchPayoutId with approvalStatus: "PENDING".

GET /api/payouts lists Hyperswitch payouts (scope settlements:read) and joins each with its org-scoped settlementExtension. Note the explicit tenant guard: even after a findUnique on the globally-unique hyperswitchPayoutId, the row is discarded unless ext.organizationId === organizationId.

Settlements & the approval gate

SettlementExtension (schema.prisma, model SettlementExtension) is the MVS-only workflow layer over a Hyperswitch payout. Selected fields:

1
model SettlementExtension {
2
  id                    String   @id @default(cuid())
3
  organizationId        String
4
  merchantExtensionId   String?
5
  hyperswitchPayoutId   String   @unique
6
  hyperswitchMerchantId String?
7
8
  // Platform approval workflow — MVS-specific gate before payout funds.
9
  approvalStatus  String    @default("PENDING") // PENDING, APPROVED, REJECTED
10
  approvedAt      DateTime?
11
  approvedBy      String?
12
  rejectedAt      DateTime?
13
  rejectedBy      String?
14
  rejectionReason String?
15
  reviewDeadline  DateTime?
16
  platformNotes   String?
17
18
  instantPayoutRequests InstantPayoutRequest[]
19
}

The relationship that matters operationally: one SettlementExtension has many InstantPayoutRequest rows — each one a funding attempt. Hyperswitch has no per-settlement funding-attempt API, so this history lives entirely in MVS tables.

Funding-attempt history

apps/mvs-pay-extensions/src/routes/settlements.ts exposes one read endpoint:

GET /v1/settlements/:id/funding-attempts

:id may be the SettlementExtension cuid or its globally-unique hyperswitchPayoutId — it resolves with an OR filter that is always tenant-scoped by organizationId (the isolation boundary). It then returns the InstantPayoutRequest rows for that settlement, newest-first.

The dashboard surfaces this at GET /api/settlements/[id]/funding-attempts (apps/mvs-pay/app/api/settlements/[id]/funding-attempts/route.ts, scope settlements:read), proxying through mvsPayClient.settlements.fundingAttempts.

Payout methods

A PayoutMethod is a payout destination. Two flavors share the table:

The synthetic id for bank accounts is deliberate: there is no Hyperswitch payment-method id for an ACH account, so the Plaid Item id is used as a stable, unique handle to satisfy the @unique constraint on hyperswitchPaymentMethodId.

Routes

apps/mvs-pay-extensions/src/routes/payout-methods.ts. All routes require tenant.organizationId (else 400 tenant_required) and are Prisma-scoped to that org.

Verify logic

POST /v1/payout-methods/:id/verify branches on how the method was created:

The PayoutMethod model carries several push-to-card eligibility columns (pushToCardEligible, domesticPushToCard, crossBorderPushToCard) that are present in the schema but not populated by any route in this directory today — treat them as reserved for a future eligibility-probe step.

Plaid ACH linking

The end-to-end goal: let an org link a real bank account via Plaid Auth and use it as an instant-payout destination, without ever storing a raw Plaid access token in the database in plaintext.

Configuration & gating

Plaid config lives in apps/mvs-pay-extensions/src/config/index.ts under config.plaid:

isPlaidConfigured() returns true only when both clientId and secret are set. The Plaid client (apps/mvs-pay-extensions/src/services/plaid-client.ts) is a lazily-constructed PlaidApi singleton; it throws if instantiated while unconfigured. Both Plaid routes short-circuit to 503 plaid_not_configured before the client is ever built, so that throw only fires on local-dev misconfiguration.

Token & secret storage

There are two stores in play, and the comments in the schema and code do not fully agree — worth knowing:

• PayoutMethod.accessTokenEnc and PlaidItem.accessTokenEnc hold the AES-256-GCM ciphertext of the Plaid access token, produced by encryptForOrg(organizationId, accessToken) from @mvs/secrets/encryption. Wire format is v1:<iv-base64>:<tag-base64>:<ciphertext-base64>, and the org id is mixed into the GCM AAD (org:<id>) so a ciphertext leaked from one org cannot be decrypted under another. The key comes from MVS_PAY_KMS_KEY (production refuses to start without it; non-prod falls back to a deterministic scrypt-derived dev key).
• PlaidItem.accessTokenSecretName stores a reference string (PLAID_ACCESS_TOKEN_<itemId>). The model comment describes access tokens living in Infisical under /tenants/{slug}/PLAID_ACCESS_TOKEN_{itemId}, with only the name reference in the DB. In current code (/v1/plaid/exchange) the encrypted token is written directly to accessTokenEnc; accessTokenSecretName is set but the Infisical-stored-token path is the legacy/older-row story. New rows resolve via accessTokenEnc.

Link flow

apps/mvs-pay-extensions/src/routes/plaid.ts exposes two endpoints. Both emit a phiAudit.logAccess entry attributing the action to the org.

POST /v1/plaid/link-token mints a short-lived link_token for the browser-side usePlaidLink hook / <MvsPayInstantPayoutPicker> component:

1
const request: LinkTokenCreateRequest = {
2
  user: { client_user_id: tenant.organizationId },
3
  client_name: "MVS Pay",
4
  products: [Products.Auth],
5
  country_codes: [CountryCode.Us],
6
  language: "en",
7
  ...(config.plaid.webhookUrl ? { webhook: config.plaid.webhookUrl } : {}),
8
};

POST /v1/plaid/exchange trades the single-use public_token for a long-lived access token and persists the linked account. Body: { public_token, account_id }. Steps:

1. 400 missing_fields if either field is absent.
2. itemPublicTokenExchange({ public_token }) → access_token + item_id.
3. accountsGet({ access_token }) → accounts + institution id.
4. Find the chosen account_id in the item; 404 account_not_found_in_item if missing.
5. encryptForOrg(orgId, accessToken) → ciphertext.
6. Upsert a PlaidItem on the (organizationId, itemId) compound unique. Re-link resets lastErrorCode/lastErrorMessage/loginRequiredAt to null and sets verificationStatus: "verified".
7. Create a PayoutMethod (type: "BANK_ACCOUNT", synthetic plaid:<plaidItemId> handle, verified: true, plaidVerifiedAt: now, hyperswitchMerchantId: "").
8. Return { payoutMethodId } for the caller to hand to the instant-payout picker.

Tenant scoping & error mapping

Every Prisma query in these routes filters by tenant.organizationId, and the org id is bound into the ciphertext AAD so a leaked column value cannot be replayed cross-org. Plaid errors are funneled through describePlaidError:

Sanitized Plaid logging

plaid.ts enforces this with a dedicated plaidErrorLogFields(err) helper that extracts only three safe fields — the Plaid error_code, error_message, and HTTP status — and that is the only shape ever passed to logger.warn:

1
logger.warn(
2
  {
3
    plaidError: plaidErrorLogFields(err), // { code, message, status } only
4
    organizationId: tenant.organizationId,
5
  },
6
  "[plaid/exchange] Plaid call failed",
7
);

If you add new Plaid call sites, reuse plaidErrorLogFields — do not spread the error object into a log line.

Plaid webhooks

apps/mvs-pay-extensions/src/routes/webhooks-plaid.ts ingests Plaid’s single configured webhook URL (/webhooks/plaid). Behavior:

• Signature: in production an unset PLAID_WEBHOOK_SECRET fails closed (503 not_configured) — this state-mutating, internet-facing endpoint never silently skips verification in prod. If a secret is configured, the Plaid-Verification header must match an HMAC-SHA256 of the raw body (timingSafeEqual), else 401 signature_invalid. Outside production an unset secret is tolerated for sandbox/pre-rotation testing.
• Lookup: findPlaidItemByItemId finds the row by item_id (globally unique via the (organizationId, itemId) index), then re-acquires a tenant-scoped client with the resolved organizationId for the update. Unknown items are ack’d as { ok: true, ignored: true }.

Handled events:

The webhook signature scheme here is the simple HMAC fallback; the runbook flags that production should rotate to Plaid’s JWT-based verification.

Instant payouts

An instant payout pushes funds to a previously-linked, verified PayoutMethod and tracks the attempt in InstantPayoutRequest.

Model

1
model InstantPayoutRequest {
2
  id                    String   @id @default(cuid())
3
  organizationId        String
4
  hyperswitchMerchantId String
5
  hyperswitchPayoutId   String?  // set once the Hyperswitch payout is created
6
  settlementExtensionId String?  // links this attempt to a settlement
7
  payoutMethodId        String
8
  amount                Int
9
  currency              String   @default("USD")
10
  status                String   @default("PENDING") // PENDING, REQUESTED, COMPLETED, FAILED
11
  fundingTransferId     String?
12
  failureCode           String?
13
  failureMessage        String?
14
  rail                  String   @default("INSTANT")
15
  requestedAt           DateTime @default(now())
16
  requestedBy           String?
17
  completedAt           DateTime?
18
  failedAt              DateTime?
19
}

payoutMethod is onDelete: Restrict — you cannot delete a PayoutMethod that has attempts pointing at it.

Status state machine

Create flow

apps/mvs-pay-extensions/src/routes/instant-payouts.ts, POST /v1/instant-payouts. Requires tenant.organizationId. Body: { payout_method_id, amount, currency?, settlement_extension_id?, requested_by?, tenant_patient_id?, metadata? }.

GET /v1/instant-payouts (paginated by ?limit, default 50) and GET /v1/instant-payouts/:id are tenant-scoped reads.

Dashboard entry points

• POST /api/settlements/[id]/instant-payout (apps/mvs-pay/..., scope settlements:write) — request an instant payout for a settlement. It accepts payoutMethodId (or legacy paymentInstrumentId), a positive amount, optional currency, and forwards an idempotency-key. It calls client.instantPayouts.request({ ..., settlement_extension_id: id }), which is how InstantPayoutRequest.settlementExtensionId gets populated and the attempt shows up under that settlement’s funding-attempt history.

Async settlement via the Temporal worker

The create path leaves a successful attempt in REQUESTED — it does not wait for the payout to actually settle. Reconciliation is owned by the pay-crons Temporal worker.

The reconciliation workflow

packages/temporal-workflows/src/workflows/mvs-pay.ts defines instantPayoutSettlementWorkflow, scheduled every 15 minutes (packages/temporal-workflows/src/schedules/pay-crons.ts, schedule id pay-crons.instant-payout.settlement, cron */15 * * * *). Workflow code is deterministic; the side-effecting work is in the activity runInstantPayoutSettlement (packages/temporal-workflows/src/activities/mvs-pay.ts), proxied with a 10-minute start-to-close timeout and the Hyperswitch-API retry policy.

What the activity does (default limit: 100 per run):

1. Load InstantPayoutRequest rows where status === "REQUESTED", oldest-first.
2. Skip any without a hyperswitchPayoutId (nothing to reconcile yet).
3. hyperswitch.payouts.get(payoutId) and read status:
   • succeeded / success / completed → COMPLETED (+ completedAt).
   • failed / cancelled / expired / reversed → FAILED (+ failedAt, failureCode, failureMessage).
   • anything else → leave as REQUESTED, count as processed.
4. Return { processed, errors, details: { completed, failed, scanned } }.

Related pay-crons (context)

The same pay-crons queue runs five other scheduled workflows. They are not payout-settlement but are listed so you know what else touches these tables / Hyperswitch:

(webhookDlqDrainerWorkflow and successRateReconcileWorkflow also run on this queue.)

Known gaps & honesty checklist

Where to go next