Devices & POS Terminals

MVS Pay keeps an inventory of card-present POS terminals. This survived the Hyperswitch pivot as a first-class MVS concern — Hyperswitch does not model POS hardware, so the Device table lives in the dedicated mvs-pay database and is owned entirely by us.

The single most important thing to understand before you touch this code: the device surface is largely read/inventory + reconcile today. You can list, read, register/upsert, edit metadata, sync from a connector, and delete device rows. You cannot drive the terminal hardware — the lifecycle commands a payfac normally exposes (activate, action, idle-image) are honest 501 stubs left over from the decommissioned Finix integration. They are wired up, authenticated, and documented as not-yet-implemented, deliberately, so callers get a clear 501 instead of a silent call to a dead gateway.

Where the code lives

Devices span the two main surfaces. The truth is the extensions service; the Next.js app is a thin, scope-checked proxy in front of it.

The mounting is plain Hono — api.route("/devices", deviceRoutes) in apps/mvs-pay-extensions/src/app.ts, advertised as devices: "/v1/devices" in the service’s route index. See Extensions Service for the surrounding middleware and the SDK page for the client.

The Device model

model Device in packages/mvs-pay/prisma/schema.prisma (mapped to the device table). Every row is org-scoped, optionally bound to a MerchantExtension, and references the underlying terminal by an opaque connectorDeviceId. MVS application code never holds connector credentials.

Constraints worth knowing:

• connectorDeviceId is @unique globally (across all orgs), and there is also a composite @@unique([organizationId, connectorDeviceId]).
• Indexed on organizationId and tenantLocationId.

Routes — what is real

These are the routes the extensions service actually mounts under /v1/devices (apps/mvs-pay-extensions/src/routes/devices.ts). All are tenant-scoped: every handler reads tenant.organizationId, returns 400 tenant_required if absent, and obtains a per-org client via getMvsPayDb(organizationId).

The @mvs/mvs-pay-sdk DevicesNamespace exposes exactly this surface and nothing more — create, sync, list, get, update, delete. There is no devices.activate, devices.action, or devices.idleImage method. That absence is the contract.

1
// packages/mvs-pay-sdk/src/namespaces/devices.ts — the whole surface
2
client.devices.create(input, meta);   // POST   /v1/devices
3
client.devices.sync(input, meta);     // POST   /v1/devices/sync
4
client.devices.list(query, meta);     // GET    /v1/devices
5
client.devices.get(deviceId, meta);   // GET    /v1/devices/:id
6
client.devices.update(id, in, meta);  // PATCH  /v1/devices/:id
7
client.devices.delete(deviceId, meta);// DELETE /v1/devices/:id

Listing the inventory

1
const { data } = await mvsPay.devices.list({
2
  merchant_id: "mer_xxxxxxxx",  // → hyperswitchMerchantId, optional
3
  location_id: "LOC456",         // → tenantLocationId, optional
4
  status: "ONLINE",              // optional, free-form match
5
});

listDevices (packages/mvs-pay/src/queries/devices.ts) defaults to take: 100, skip: 0, orderBy: { createdAt: "desc" }. The query helper also supports merchantExtensionId, enabled, limit, and offset filters that the HTTP route does not currently expose — if you need them, plumb them through the route, don’t reach around it.

Registering a device

POST /v1/devices is an upsert keyed on connectorDeviceId, not a strict create. Calling it twice with the same connectorDeviceId updates the existing row (this is upsertDevice under the hood). New rows default to status: "INACTIVE" and enabled: false.

1
const device = await mvsPay.devices.create({
2
  connector_device_id: "dev_xxxxxxxx",  // issued by the connector
3
  hyperswitch_merchant_id: "mer_xxxxxxxx",
4
  tenant_location_id: "LOC456",          // optional MVS location link
5
  name: "front-desk",
6
  display_name: "Front Desk Terminal",
7
  model: "PAX_A920PRO",
8
  serial_number: "1850000000",
9
});

See apps/mvs-pay/docs/DEVICE_SETUP.md for the supported model codes (PAX_A920PRO, PAX_A920, PAX_A800, D135, BBPOS_WISEPOS_E), the dashboard registration form, and the physical pairing steps on the terminal itself.

Device sync & health

POST /v1/devices/sync is the reconciliation entry point a terminal connector / POS agent calls to push device state into MVS Pay. It has two modes, decided by whether the body carries a non-empty devices array:

What “health” means here

There is no active health-probe or heartbeat job. Device health is entirely connector-reported and pull/push-reconciled, not measured by MVS Pay:

• connection / connectionStatus reflect the last state the connector told us via sync. MVS Pay never pings a terminal.
• lastConnectedAt is only advanced on a CONNECTED sync; it is the closest thing to a liveness signal, and it is as fresh as the last sync call.
• status is free-form and follows whatever the connector reports. The DEVICE_SETUP.md guide describes a REGISTERED → ONLINE ⇄ OFFLINE mental model, but the column is a plain string — nothing in this codebase enforces or transitions those values. Don’t write code that assumes a fixed enum.

Terminal sales

A POS sale is not a device command. Post-pivot there is no /v1/devices/:id/sale endpoint on the extensions service. The Next.js route POST /api/devices/[id]/sale (apps/mvs-pay/app/api/devices/[id]/sale/route.ts) is real, but it just creates an ordinary payment intent via payments.create, carrying the originating device in metadata for downstream reconciliation:

1
// metadata attached to the payment intent
2
{
3
  device_id: id,
4
  merchant_id: finixMerchantId,
5
  source: "terminal",
6
  entry_mode: "TERMINAL",
7
  receipt_options: body.receiptOptions,
8
}

It requires devices:write and a resolved merchant (requireMerchant: true) and validates amount > 0 (integer cents). The extensions service resolves connector routing for the org’s merchant. For the full payment-intent lifecycle see Payments & Refunds and Payment Lifecycle.

The 501 stubs — device lifecycle is not implemented

These routes exist in apps/mvs-pay/app/api/devices/ purely to return an honest 501 with a clear message. They authenticate (devices:write), await params, and then return not-implemented. They are not wired to the extensions service, the SDK exposes no method for them, and /v1/devices mounts no corresponding surface.

Example payload they return:

1
{ "error": "not implemented: device action commands are not yet available on mvs-pay-extensions" }

Authentication & tenancy

Both the Next.js proxies and the extensions routes are tenant-scoped end to end:

• Next.js routes call authenticateRequest(request, { requiredScope: ... }) — devices:read for GET, devices:write for POST / PUT / sync / sale and the 501 stubs. They support both session auth (dashboard) and API-key auth (HealthOS / mvs-c2 integrations).
• The extensions handlers derive the per-org Prisma client from tenant.organizationId via getMvsPayDb(...) and scope every query/mutation by organizationId. There is no cross-org read path; even GET /:id filters on the org.
• The cross-tenant connectorDeviceId collision guard in sync (above) is the one place where global uniqueness meets tenancy — get familiar with it.

See Authentication & Tenancy for the scope model and how API keys resolve to an org and merchant.

Gaps & gotchas for the new owner

• Read-mostly surface. Inventory + reconcile + metadata edits + delete. No hardware control. Don’t promise terminal activation/reboot/branding from MVS Pay until a connector command surface exists.
• Config columns are inert. idleMessage, signature prompts/thresholds, standalone-sale flags, and version columns are stored but never pushed to hardware.
• status is a free-form string. The REGISTERED/ONLINE/OFFLINE model in DEVICE_SETUP.md is documentation, not an enforced enum. Validate before relying on specific values.
• Health is only as fresh as the last sync. No heartbeat, no staleness sweep, no TTL. lastConnectedAt is your best liveness signal.
• Upsert, not create. POST /v1/devices will quietly update an existing row on a connectorDeviceId match.
• finixMerchantId naming in the sale handler is legacy — it’s the resolved Hyperswitch merchant.
• Two filter sets. listDevices supports more filters than the HTTP route exposes; extend the route rather than bypassing it.

Related pages