Device Control Commands

Use these endpoints to remotely configure and control PAX terminals via the Cloud API. Commands are delivered over the existing Cloud message channel — no cardholder interaction or client-side SDK is required to issue them.

Cloud API + connected terminal required

Device commands are not back-office/no-reader operations. They are instructions delivered to a physical PAX device and require the terminal to be online and enrolled in Cloud (integrated) mode via Handpoint TMS. Unlike transaction feed or TMS API calls, these commands cannot be used without a connected reader.

• Handpoint Payments App 4.6.0+ (Android SDK 7.1006.0+) must be installed on the terminal.
• Integrated mode must be active — if it is not, the command will not execute even though the API returns 202 Accepted.

All endpoints share the same structure:

POST https://cloud.handpoint.com/devices/{terminal_type}/{serial_number}/{command}
ApiKeyCloud: YOUR_MERCHANT_API_KEY
Content-Type: application/json

All endpoints return 202 Accepted immediately. Command delivery to the device is asynchronous.

---

set-unattended-mode

Enable or disable unattended (kiosk) mode on the terminal. When enabled, the bottom navigation bar (Home, Back, Recents) is hidden and the payment screen is always in the foreground. History, Analytics, and Settings tabs become inaccessible.

POST https://cloud.handpoint.com/devices/PAXA920/082104578/set-unattended-mode
ApiKeyCloud: YOUR_MERCHANT_API_KEY
Content-Type: application/json

{
  "status": true
}

Field	Type	Required	Description
status	boolean	Yes	true to enable unattended mode, false to disable

---

set-locale

Change the terminal display language.

POST https://cloud.handpoint.com/devices/PAXA920/082104578/set-locale
ApiKeyCloud: YOUR_MERCHANT_API_KEY
Content-Type: application/json

{
  "locale": "en_US"
}

Field	Type	Required	Description
locale	string	Yes	IETF BCP 47 language tag, e.g. "en_US", "en_CA", "fr_FR", "es_ES"

---

set-password-protected

Enable or disable password protection on the terminal configuration screen. When enabled, accessing the configuration requires a PIN.

POST https://cloud.handpoint.com/devices/PAXA920/082104578/set-password-protected
ApiKeyCloud: YOUR_MERCHANT_API_KEY
Content-Type: application/json

{
  "status": true
}

Field	Type	Required	Description
status	boolean	Yes	true to enable password protection, false to disable

---

reboot

Reboot the terminal remotely.

POST https://cloud.handpoint.com/devices/PAXA920/082104578/reboot
ApiKeyCloud: YOUR_MERCHANT_API_KEY
Content-Type: application/json

{
  "force": false
}

Field	Type	Required	Description
force	boolean	Yes	false to check whether a transaction is in progress before rebooting (recommended). true to reboot immediately regardless of transaction state — this can interrupt an active transaction.

---

set-screen-brightness

Set the minimum and maximum screen brightness range for the terminal display.

POST https://cloud.handpoint.com/devices/PAXA920/082104578/set-screen-brightness
ApiKeyCloud: YOUR_MERCHANT_API_KEY
Content-Type: application/json

{
  "minimumBrightnessLevel": 20,
  "maximumBrightnessLevel": 100
}

Field	Type	Required	Constraints	Description
minimumBrightnessLevel	integer	Yes	0–100	Minimum brightness level (0 = off, 100 = maximum)
maximumBrightnessLevel	integer	Yes	0–100	Maximum brightness level

Returns 400 Bad Request if either value is outside 0–100.

---

set-reboot-time

Schedule a daily automatic reboot at a specific hour. The actual reboot occurs at a random minute within the specified hour (e.g. 22 → reboots between 22:01–22:59) to avoid all devices rebooting simultaneously.

Production devices only

This feature is enabled for production devices only. It has no effect on development or staging devices.

POST https://cloud.handpoint.com/devices/PAXA920/082104578/set-reboot-time
ApiKeyCloud: YOUR_MERCHANT_API_KEY
Content-Type: application/json

{
  "hour": 2
}

Field	Type	Required	Constraints	Description
hour	integer	Yes	0–23	Hour of day (24h clock) for the scheduled reboot

Returns 400 Bad Request if hour is outside 0–23.

---

URL path parameters

Parameter	Description	Example
{terminal_type}	Terminal model identifier — same value as terminal_type in POST /transactions	PAXA920, PAXA8900, PAXA3700
{serial_number}	Terminal serial number printed on the device label	082104578