RevKeen Docs

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
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
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

StatusMeaning
onlineConnector is connected and terminal is reachable. Last heartbeat within 5 minutes.
offlineConnector has not sent a heartbeat within 5 minutes, or is disconnected.
pairingConnector is registered but terminal is not yet paired.

A device must be online and terminal_paired: true to accept payments.

Device Properties

FieldTypeDescription
idUUIDUnique device identifier
device_namestringHuman-readable device name
terminal_serialstringPAX terminal hardware serial number
terminal_ipstringTerminal's LAN IP address
platformstringConnector's OS: windows or macos
statusstringonline, offline, or pairing
terminal_pairedbooleanWhether a PAX terminal is paired to this connector
terminal_reachablebooleanWhether the connector can currently reach the terminal on the LAN
app_versionstringConnector application version (semver)
last_heartbeat_atISO 8601Timestamp of the last heartbeat from the connector

On this page