Skip to main content
Version: 4.0

Push to Terminal Integration Guide

Integration with the Halo backend to manage devices for Push to Terminal.

1. Overview​

Push to Terminal allows a merchant system to register devices and push payment requests to them via Firebase push notification. The device management API provides CRUD operations for managing devices. Push payment is initiated via POST /consumer/push.

2. Device Management API​

2.1 List Devices​

Retrieve all devices registered by the authenticated user.

GET https://kernelserver.{env}.haloplus.io/devices

Path Parameters

NameTypeDescription
env*StringThe backend environment [dev, qa, prod]

Headers

NameTypeDescription
x-api-key*StringThe API Key retrieved from the Merchant Portal (JWT can be used instead)
Authorization*StringThe JWT retrieved from logging in. (API Key can be used instead)
[
  {
    "id": "07b6cbe3-c4c3-4214-b279-ccb516c26573",
    "deviceInstallationId": "AA1A109DF2C4208F3ABBC062A343464C",
    "friendlyName": "Front Counter",
    "hasFirebaseToken": true,
    "createdAt": "2026-07-02T12:41:59.344Z"
  }
]

2.2 Register Device​

Register a device with its Firebase token and friendly name. If the device already exists (same deviceInstallationId + user), it will be updated.

POST https://kernelserver.{env}.haloplus.io/devices

Path Parameters

NameTypeDescription
env*StringThe backend environment [dev, qa, prod]

Headers

NameTypeDescription
Content-Type*StringContent Type of the Request: application/json
x-api-key*StringThe API Key retrieved from the Merchant Portal (JWT can be used instead)
Authorization*StringThe JWT retrieved from logging in. (API Key can be used instead)

Request Body

NameTypeDescription
deviceInstallationId*StringThe device installation ID from the Halo.Go app
firebaseToken*StringFirebase Cloud Messaging token for push notifications
friendlyName*StringHuman-readable name for the device (max 32 characters)
{
  "id": "07b6cbe3-c4c3-4214-b279-ccb516c26573",
  "deviceInstallationId": "AA1A109DF2C4208F3ABBC062A343464C",
  "friendlyName": "Front Counter"
}

2.3 Update Device Friendly Name​

Update the friendly name of a registered device.

PUT https://kernelserver.{env}.haloplus.io/devices/:deviceId

Path Parameters

NameTypeDescription
env*StringThe backend environment [dev, qa, prod]
deviceId*StringThe device ID (UUID from GET /devices)

Headers

NameTypeDescription
Content-Type*StringContent Type of the Request: application/json
x-api-key*StringThe API Key retrieved from the Merchant Portal (JWT can be used instead)
Authorization*StringThe JWT retrieved from logging in. (API Key can be used instead)

Request Body

NameTypeDescription
friendlyName*StringName for the device (1-32 characters)
{
  "id": "07b6cbe3-c4c3-4214-b279-ccb516c26573",
  "friendlyName": "Back Office"
}

2.4 Remove Device​

Remove a device from the user's list. This is a permanent deletion.

DELETE https://kernelserver.{env}.haloplus.io/devices/:deviceId

Path Parameters

NameTypeDescription
env*StringThe backend environment [dev, qa, prod]
deviceId*StringThe device ID (UUID from GET /devices)

Headers

NameTypeDescription
x-api-key*StringThe API Key retrieved from the Merchant Portal (JWT can be used instead)
Authorization*StringThe JWT retrieved from logging in. (API Key can be used instead)
{
  "id": "07b6cbe3-c4c3-4214-b279-ccb516c26573"
}

3. Push Payment API​

3.1 Push Payment to Device​

Push a payment request to a registered device via Firebase push notification.

POST https://kernelserver.{env}.haloplus.io/consumer/push

Path Parameters

NameTypeDescription
env*StringThe backend environment [dev, qa, prod]

Headers

NameTypeDescription
Content-Type*StringContent Type of the Request: application/json
x-api-key*StringThe API Key retrieved from the Merchant Portal (JWT can be used instead)
Authorization*StringThe JWT retrieved from logging in. (API Key can be used instead)

Request Body

NameTypeDescription
deviceId*StringThe device ID (UUID from GET /devices)
amount*NumberPayment amount (minimum 0.01)
currency*String3-letter ISO currency code (e.g. ZAR, USD)
merchantReference*StringUnique reference for this payment
{
  "reference": "cef48d2a-c634-4edc-b891-48cd1d52249f",
  "status": "sent"
}

4. Integration Example​

const axios = require('axios');

const BASE_URL = 'https://kernelserver.prod.haloplus.io';
const API_KEY = 'your-api-key';
const headers = { 'x-api-key': API_KEY, 'Content-Type': 'application/json' };

// Step 1: Register a device
await axios.post(`${BASE_URL}/devices`, {
  deviceInstallationId: 'AA1A109DF2C4208F3ABBC062A343464C',
  firebaseToken: 'fcm-token-from-device',
  friendlyName: 'Front Counter'
}, { headers });

// Step 2: List devices
const devices = await axios.get(`${BASE_URL}/devices`, {
  headers: { 'x-api-key': API_KEY }
});

// Step 3: Update device friendly name
const device = devices.data[0];
await axios.put(`${BASE_URL}/devices/${device.id}`, {
  friendlyName: 'Back Office'
}, { headers });

// Step 4: Push payment to device
const push = await axios.post(`${BASE_URL}/consumer/push`, {
  deviceId: device.id,
  amount: 25.00,
  currency: 'ZAR',
  merchantReference: 'ORDER-001'
}, { headers });
console.log('Push reference:', push.data.reference);

// Step 5: Remove a device
await axios.delete(`${BASE_URL}/devices/${device.id}`, {
  headers: { 'x-api-key': API_KEY }
});