Terminals
Manage VINR payment terminals — activate, assign, configure, and monitor your hardware fleet.
Terminals represent physical payment hardware in your fleet. Use this API to activate new devices, assign them to locations, push configuration changes, and trigger remote actions such as reboots or software updates. Each terminal reports its connectivity status and last-seen timestamp so you can monitor fleet health programmatically.
Illustrative content. Hand-authored to demonstrate the Standard/Advanced pattern; the production page will be generated from the VINR OpenAPI spec (roadmap item #1). Field names are representative.
The terminal objectAsk
idstringUnique identifier for the terminal, e.g. term_3Nx8.
modelstringHardware model identifier, e.g. nexgo_n92.
serialNumberstringManufacturer serial number printed on the device.
statusenumOne of online, offline, needs_attention, or deactivated.
locationIdstringThe identifier of the location the terminal is assigned to,
e.g. loc_7Yz4.
softwareVersionstringFirmware and application version string currently running on the device, e.g. 3.14.2.
lastSeenintegerUnix timestamp of the most recent successful connection to the VINR cloud.
batteryLevelinteger | nullBattery charge percentage from 0 to 100. null for mains-powered devices that do not
report battery state.
createdAtintegerUnix timestamp when the terminal was first activated.
Activate a terminalAsk
Pair a new device to your account using the activation code displayed on the terminal's setup screen.
Optionally assign it to a location at activation time. On success the terminal is returned with
status: "online".
Retrieve a terminalAsk
Fetch a single terminal by its ID.
Update a terminalAsk
Reassign a terminal to a different location or set a human-readable display name. Only the fields you include are changed.
List terminalsAsk
Returns a paginated list of terminals, newest first. Filter by location or status to scope results.
| Parameter | Type | Description |
|---|---|---|
locationId | string | Return only terminals assigned to this location. |
status | enum | Filter by online, offline, needs_attention, or deactivated. |
limit | integer | Number of results to return. Default 10, max 100. |
starting_after | string | Cursor for forward pagination — the id of the last item from the previous page. |
Configure a terminalAsk
Push a configuration payload to a specific terminal. The device applies changes on its next sync cycle (typically within 30 seconds while online).
The config body accepts the following top-level keys:
tipobjectTipping settings for this terminal.
receiptobjectReceipt delivery settings.
displayobjectScreen content settings.
offlineModeobjectControls behavior when the device loses connectivity.
Send a remote actionAsk
Dispatch an action to a terminal. VINR enqueues the command and delivers it the next time the device
checks in. The response is a terminalAction object, not the terminal itself.
The terminalAction object fields:
idstringUnique identifier for the action, e.g. tact_8Wq1.
terminalIdstringThe terminal this action targets.
actionenumOne of reboot (restart the device), update (trigger a software update check), or lock
(prevent new transactions until unlocked via the Dashboard or API).
statusenumLifecycle state: queued → processing → completed or failed.
createdAtintegerUnix timestamp when the action was created.
