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

Configure individual terminal security restrictions independently. Each restriction is a separate boolean flag; omitting a field leaves that restriction unchanged, so you can update a single setting without affecting the rest.

Requires Handpoint Payments App 4.14.1 or later.

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

{
  "hideTabBar": true,
  "blockSystemUI": false
}

Field	Type	Required	Description
hideTabBar	boolean	No	true hides the app's bottom tab bar, making History, Analytics, and Settings unreachable while leaving Android system menus (Wi-Fi, notifications) accessible. false restores it.
blockSystemUI	boolean	No	true locks the Android status and navigation bars, preventing access to system menus. false restores them.
brightness	boolean	No	true dims the screen to minimum when the terminal is idle and restores brightness when a transaction starts. false disables automatic dimming.
passwordToExit	boolean	No	true requires a PIN before any active restrictions can be lifted. false removes the PIN requirement.

Returns 202 Accepted. Changes take effect immediately and survive app restarts and device reboots. When the command is received, the app automatically navigates to the payment screen.

Partial updates

Send only the fields you want to change. An empty body {} is accepted and changes nothing.

Relationship to other commands

set-security-policy provides finer-grained control than set-unattended-mode, which always enables hideTabBar and blockSystemUI together. Both commands continue to work — set-security-policy is the recommended approach for new integrations.

---

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.

note

set-security-policy (App 4.14.1+) provides the same control as set-unattended-mode but with each restriction configurable independently.

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