Devices API
Query and monitor terminal devices connected to your account
Before initiating a payment, discover which terminal devices are available and online.
List Devices
Retrieve all terminal devices registered to your account.
const devices = await revkeen.terminalDevices.list();
for (const device of devices.data) {
console.log(`${device.device_name}: ${device.status}`);
console.log(` Serial: ${device.terminal_serial}`);
console.log(` Last heartbeat: ${device.last_heartbeat_at}`);
}devices = client.terminal_devices.list()
for device in devices.data:
print(f"{device.device_name}: {device.status}")
print(f" Serial: {device.terminal_serial}")curl -X GET "https://api.revkeen.com/v2/terminal-devices" \
-H "x-api-key: rk_live_your_api_key"Response:
{
"data": [
{
"id": "d1e2f3a4-b5c6-7890-abcd-ef1234567890",
"device_name": "Front Desk Terminal",
"terminal_serial": "21032100001",
"terminal_ip": "192.168.1.50",
"platform": "windows",
"status": "online",
"terminal_paired": true,
"terminal_reachable": true,
"app_version": "0.1.0",
"last_heartbeat_at": "2026-03-11T10:00:00Z"
}
],
"meta": { "count": 1 }
}The terminal_ip field is the LAN IP address of the terminal as seen by the connector on the merchant's local network. This is not a publicly reachable address -- all commands flow through RevKeen Cloud.
Get Device
Retrieve a single device by ID.
const device = await revkeen.terminalDevices.retrieve(
'd1e2f3a4-b5c6-7890-abcd-ef1234567890'
);
console.log(device.data.status);
console.log(device.data.terminal_serial);curl -X GET "https://api.revkeen.com/v2/terminal-devices/d1e2f3a4-b5c6-7890-abcd-ef1234567890" \
-H "x-api-key: rk_live_your_api_key"Device Status
| Status | Meaning |
|---|---|
online | Connector is connected and terminal is reachable. Last heartbeat within 5 minutes. |
offline | Connector has not sent a heartbeat within 5 minutes, or is disconnected. |
pairing | Connector is registered but terminal is not yet paired. |
A device must be online and terminal_paired: true to accept payments.
Device Properties
| Field | Type | Description |
|---|---|---|
id | UUID | Unique device identifier |
device_name | string | Human-readable device name |
terminal_serial | string | PAX terminal hardware serial number |
terminal_ip | string | Terminal's LAN IP address |
platform | string | Connector's OS: windows or macos |
status | string | online, offline, or pairing |
terminal_paired | boolean | Whether a PAX terminal is paired to this connector |
terminal_reachable | boolean | Whether the connector can currently reach the terminal on the LAN |
app_version | string | Connector application version (semver) |
last_heartbeat_at | ISO 8601 | Timestamp of the last heartbeat from the connector |
Related
- Payments API -- Initiate payments on a device
- Best Practices -- Monitor device health before sending payments