Rebooting Terminal

Terminals can be rebooted remotely using
POST v1/pos/terminals/smart/{terminalId}/reboot

This endpoint requires no request body and upon success will return 204 No Content. Note that for this endpoint to work, the terminal does need to be successfully connected currently.

Getting Terminal Connection Status

The connection status of a terminal can be retrieved using
GET /v1/pos/terminals/smart/{terminalId}/status

Successful response (connected)

A successful create returns:

200 OK

Response body

{
  "connected": true,
  "disconnectReason": null,
  "lastActiveAt": "2024-06-15T14:30:00Z",
  "lastTransaction": {
    "reference": "sl_abcd1234efgh5678",
    "status": "Successful",
    "updatedAt": "2024-06-15T14:30:00Z"
  }
}

Successful response (not connected)

200 OK

Response body

{
  "connected": false,
  "disconnectReason": "CONNECTION_LOST",
  "lastActiveAt": "2024-06-15T14:30:00Z",
  "lastTransaction": {
    "reference": "sl_abcd1234efgh5678",
    "status": "Successful",
    "updatedAt": "2024-06-15T14:30:00Z"
  }
}

The disconnect reason can be one of the following values

Reason
CUSTOMAUTH_TTL_EXPIRATION
WEBSOCKET_TTL_EXPIRATION
THROTTLED
API_INITIATED_DISCONNECT
SERVER_INITIATED_DISCONNECT
SERVER_ERROR
MQTT_KEEP_ALIVE_TIMEOUT
FORBIDDEN_ACCESS
DUPLICATE_CLIENTID
CONNECTION_LOST
CLIENT_ERROR
CLIENT_INITIATED_DISCONNECT
AUTH_ERROR

Updating MDM Settings

Because MDM (Mobile Device Management) related updates are more sensitive than regular Terminal updates, and are also meant for a different audience, these MDM updates are exposed in separate endpoints and also require a different scope: the terminal:manage scope. MDM Settings are updated using the PATCH /v1/pos/terminals/smart/{terminalId}/mdm endpoint.

Example request

{
  "appSettings": {
    "singleAppModeEnabled": true
  },
  "mdmSettings": {
    "directLaunchEnabled": true,
    "statusBarEnabled": true,
    "navigationBarEnabled": true,
    "deviceOwnerGranted": true,
    "singleAppModeEnabled": true,
    "defaultLauncherEnabled": true,
    "ntpServer": "string",
    "staticIpConfig": {
      "ipAddress": "string",
      "prefixLength": 0,
      "gateway": "string",
      "dnsServers": [
        "string"
      ]
    }
  }
}

Successful response

A successful create returns:

200 OK

Response body

{
  "terminalId": "t_abcd1234efgh5678",
  "mdmSettings": {
    "directLaunchEnabled": true,
    "statusBarEnabled": true,
    "navigationBarEnabled": true,
    "deviceOwnerGranted": true,
    "singleAppModeEnabled": true,
    "defaultLauncherEnabled": true,
    "ntpServer": "string",
    "staticIpConfig": {
      "ipAddress": "string",
      "prefixLength": 0,
      "gateway": "string",
      "dnsServers": [
        "string"
      ]
    }
  },
  "appSettings": {
    "singleAppModeEnabled": true
  },
  "_links": {
    "self": {
      "href": "/v1/pos/terminals/smart/t_abcd1234efgh5678",
      "method": "Get",
      "type": "application/hal+json"
    }
  }
}

Common error responses

400 Bad Request
401 Unauthorized
404 Not Found

Example problem response:

{
  "title": "Bad Request",
  "status": 400,
  "detail": "The request is invalid."
}

Request field explanations

Setting	Explanation
Single App Mode Enabled	This setting is available in two places: the App Settings and the MDM Settings. Setting both to true locks the device into single-app mode (kiosk mode), preventing access to other apps.
Direct Launch Enabled	When false, the Android lock screen is shown on device wake-up. When true, the app launches directly.
Status Bar Enabled	Whether or not to allow showing the notification and quick settings panel.
Navigation Bar Enabled	Whether or not to allow showing the system navigation buttons (Back, Home, Recent Apps).
Device Owner Granted	Grants the app full device administration rights, required to enforce most MDM restrictions.
Default Launcher Enabled	Sets this app as the primary home screen launcher when multiple launchers are installed on the device.
NTP Server	Link a custom time server. The default is google's NTP server.
Static IP Config	Set up a static IP Configuration for the terminal.

Swapping terminals

If there is a problem with a device, it can be swapped out with a new device. To allow preserving all of the settings, profiles and other relevant data the POST /v1/pos/terminals/smart/{terminalId}/swap endpoint can be used to switch two terminal configurations between the indicated devices.

The configuration of the terminal indicated by the terminal ID in the route is swapped with the configuration of the terminal device indicated by the serial number in the request body. This endpoint requires the terminal:manage scope for both of the terminals involved, and the terminals have to belong to the same merchant account.

Example request

{
  "serialNumber": "N6SMW555555"
}

Successful response

A successful create returns:

204 No Content

Common error responses

400 Bad Request
401 Unauthorized
404 Not Found

Example problem response:

{
  "title": "Bad Request",
  "status": 400,
  "detail": "The request is invalid."
}