What is a POSBuddy Cloud Command Request?

A command request is a message sent from the POS to POSBuddy Cloud, that instructs the POSBuddy Cloud to perform a specific action that is not directly payment related.

📘
Note:
Every command request needs to include Authentication

Print HTML Request

Send a print HTML command to POSBuddy Cloud, in order to invoke a printing action on the terminal.

POST

posbuddy-cloud/v/1/terminal/PRINT_HTML

Example: Print HTML

BODY

The following is an example of a Print HTML request body

{
    "merchantID": "merchantID",
    "posID": "posId",
    "serialNumber": "serialNumber",
    "html": "<html content>",
    "css": "<css content>"
}

String apiUrl = "https://paymentuat.test.thumbzup.com/posbuddy-cloud/v/1/";

JSONObject requestBody = new JSONObject();
requestBody.put("merchantID", merchantID);
requestBody.put("posId", posId);
requestBody.put("serialNumber", serialNumber);
requestBody.put("html", "<h5>Hello World</h5>");
requestBody.put("css", "* {text-align: center; margin-top:8px; margin-bottom:8px} h5,h5 {font-size:24px; line-height:36px}");

System.out.println("Sending request: " + requestBody + "...\n");

// See Authentication for details of the generateHeaders function
Map<String, String> headers = generateHeaders(secretKey, accessKey, userAgent, serialNumber, posId);
RequestBodyEntity request = Unirest.post(apiUrl + "terminal/PRINT_HTML")
        .headers(headers)
        .body(requestBody.toString());

HttpResponse<JsonNode> response = request.asJson();

System.out.println("Received response: " + response.getBody());

# See Authentication page for details of the variables
RESPONSE=$(curl --request POST \
  --url "$API_URL/terminal/PRINT_HTML" \
  --header "X-pos-id: POS-STORE123-TERM01" \
  --header "X-tu-authorization: protocol:TU1,accesskey:$ACCESS_KEY,signedheaders:User-Agent;X-tu-date;X-tu-random,signature:$SIGNATURE" \
  --header "X-tu-random: $RANDOM_VAL" \
  --header "X-tu-serial: $SERIAL_NUMBER" \
  --header "X-tu-date: $TU_DATE" \
  --header "User-Agent: $USER_AGENT" \
  --header "Content-Type: application/json" \
  --data "{
    \"merchantID\": \"$MERCHANT_ID\",
    \"posId\": \"POS-STORE123-TERM01\",
    \"serialNumber\": \"$SERIAL_NUMBER\",
    \"html\": \"<h5>Hello World</h5>\",
    \"css\": \"* {text-align: center; margin-top:8px; margin-bottom:8px} h5,h5 {font-size:24px; line-height:36px}\"
  }" \
 )

Print HTML Response

BODY

The following is an example of a Print HTML response body the POS Application will receive.

{
    "result":"SUCCESS"
}

{
    "result":"ERROR: Printer error"
}

Settings Request

Send a settings command to POSBuddy Cloud, in order to set, or update the following settings on a terminal:

autoStart: Flag to set POSBuddy App to start automatically on terminal boot.
runInBackground : Flag to minimize POSBuddy App after a transaction.

POST

posbuddy-cloud/v/1/terminal/SETTINGS

Example: Settings

BODY

The following is an example of a Settings request body

{ 
    "merchantID": "770000000000123",
    "posId": "POS-STORE123-TERM01",
    "serialNumber": "PF5544544664",
    "autoStart": "false",
    "runInBackground": "false"
}

String apiUrl = "https://paymentuat.test.thumbzup.com/posbuddy-cloud/v/1/";

JSONObject requestBody = new JSONObject();
requestBody.put("merchantID", merchantID);
requestBody.put("posId", posId);
requestBody.put("serialNumber", serialNumber);
requestBody.put("autoStart", "false");
requestBody.put("runInBackground", "false");

System.out.println("Sending request: " + requestBody + "...\n");

// See Authentication for details of the generateHeaders function
Map<String, String> headers = generateHeaders(secretKey, accessKey, userAgent, serialNumber, posId);
RequestBodyEntity request = Unirest.post(apiUrl + "terminal/SETTINGS")
        .headers(headers)
        .body(requestBody.toString());

HttpResponse<JsonNode> response = request.asJson();

System.out.println("Received response: " + response.getBody());

# See Authentication page for details of the variables
RESPONSE=$(curl --request POST \
  --url "$API_URL/terminal/SETTINGS" \
  --header "X-pos-id: POS-STORE123-TERM01" \
  --header "X-tu-authorization: protocol:TU1,accesskey:$ACCESS_KEY,signedheaders:User-Agent;X-tu-date;X-tu-random,signature:$SIGNATURE" \
  --header "X-tu-random: $RANDOM_VAL" \
  --header "X-tu-serial: $SERIAL_NUMBER" \
  --header "X-tu-date: $TU_DATE" \
  --header "User-Agent: $USER_AGENT" \
  --header "Content-Type: application/json" \
  --data "{
    \"merchantID\": \"$MERCHANT_ID\",
    \"posId\": \"POS-STORE123-TERM01\",
    \"serialNumber\": \"$SERIAL_NUMBER\",
    \"autoStart\": \"false\",
    \"runInBackground\": \"false\"
  }" \
 )

Settings Response

BODY

The following is an example of a Settings response body the POS Application will receive.

{
    "result":"SUCCESS",
    "autoStart": "false",
    "runInBackground": "false"
}

Display Items Request

Send a display items command to POSBuddy Cloud, in order to display items and their details on the terminal:

quantity: Number of items.
cost: Cost per item.
description: Description of item.
total: Total cost of all items.

POST

posbuddy-cloud/v/1/terminal/DISPLAY_ITEMS

Example: Display Items

BODY

The following is an example of a Display Items request body

{
    "merchantID": "merchantID",
    "posId": "posId",
    "serialNumber": "serialNumber",
    "items": [
      {
        "quantity": "1",
        "cost": "R 110.00",
        "description": "Pizza"
      },
      {
        "quantity": "1",
        "cost": "R 85.00",
        "description": "Hamburger & Chips"
      },
      {
        "quantity": "1",
        "cost": "R 130.00",
        "description": "Salmon with Salad"
      },
      {
        "quantity": "1",
        "cost": "R 65.00",
        "description": "Pancakes"
      }
    ],
    "total": "R 390.00"
}

String apiUrl = "https://paymentuat.test.thumbzup.com/posbuddy-cloud/v/1/";

JSONObject requestBody = new JSONObject();
requestBody.put("merchantID", merchantID);
requestBody.put("posId", posId);
requestBody.put("serialNumber", serialNumber);

// Build the items array
JSONArray items = new JSONArray();

items.put(new JSONObject()
        .put("quantity", "1")
        .put("cost", "R 110.00")
        .put("description", "Pizza"));

items.put(new JSONObject()
        .put("quantity", "1")
        .put("cost", "R 85.00")
        .put("description", "Hamburger & Chips"));

items.put(new JSONObject()
        .put("quantity", "1")
        .put("cost", "R 130.00")
        .put("description", "Salmon with Salad"));

items.put(new JSONObject()
        .put("quantity", "1")
        .put("cost", "R 65.00")
        .put("description", "Pancakes"));

requestBody.put("items", items);
requestBody.put("total", "R 390.00");

System.out.println("Sending request: " + requestBody + "...\n");

// See Authentication for details of the generateHeaders function
Map<String, String> headers = generateHeaders(secretKey, accessKey, userAgent, serialNumber, posId);
RequestBodyEntity request = Unirest.post(apiUrl + "terminal/DISPLAY_ITEMS")
        .headers(headers)
        .body(requestBody.toString());

HttpResponse<JsonNode> response = request.asJson();

System.out.println("Received response: " + response.getBody());

# See Authentication page for details of the variables
RESPONSE=$(curl --request POST \
  --url "$API_URL/terminal/DISPLAY_ITEMS" \
  --header "X-pos-id: POS-STORE123-TERM01" \
  --header "X-tu-authorization: protocol:TU1,accesskey:$ACCESS_KEY,signedheaders:User-Agent;X-tu-date;X-tu-random,signature:$SIGNATURE" \
  --header "X-tu-random: $RANDOM_VAL" \
  --header "X-tu-serial: $SERIAL_NUMBER" \
  --header "X-tu-date: $TU_DATE" \
  --header "User-Agent: $USER_AGENT" \
  --header "Content-Type: application/json" \
  --data "{
    \"serialNumber\": \"$SERIAL_NUMBER\",
    \"merchantID\": \"$MERCHANT_ID\",
    \"posID\": \"POS-STORE123-TERM01\",
    \"items\": [
      {
        \"quantity\": \"1\",
        \"cost\": \"R 110.00\",
        \"description\": \"Pizza\"
      },
      {
        \"quantity\": \"1\",
        \"cost\": \"R 85.00\",
        \"description\": \"Hamburger & Chips\"
      },
      {
        \"quantity\": \"1\",
        \"cost\": \"R 130.00\",
        \"description\": \"Salmon with Salad\"
      },
      {
        \"quantity\": \"1\",
        \"cost\": \"R 65.00\",
        \"description\": \"Pancakes\"
      }
    ],
    \"total\": \"R 390.00\"
  }" \
)

Display Items Response

BODY

The following is an example of a Display Items response body the POS Application will receive.

{
    "result":"SUCCESS"
}

Clear Display Request

Sends a clear display command to POSBuddy Cloud, in order to clear the displayed items on the terminal.

POST

posbuddy-cloud/v/1/terminal/CLEAR_DISPLAY

Example: Clear Display

BODY

The following is an example of a Clear Display request body

{
    "merchantID": "770000000000123",
    "posId": "POS-STORE123-TERM01",
    "serialNumber": "PF5544544664"
}

String apiUrl = "https://paymentuat.test.thumbzup.com/posbuddy-cloud/v/1/";

JSONObject requestBody = new JSONObject();
requestBody.put("merchantID", merchantID);
requestBody.put("posId", posId);
requestBody.put("serialNumber", serialNumber);

System.out.println("Sending request: " + requestBody + "...\n");

// See Authentication for details of the generateHeaders function
Map<String, String> headers = generateHeaders(secretKey, accessKey, userAgent, serialNumber, posId);
RequestBodyEntity request = Unirest.post(apiUrl + "terminal/CLEAR_DISPLAY")
        .headers(headers)
        .body(requestBody.toString());

HttpResponse<JsonNode> response = request.asJson();

System.out.println("Received response: " + response.getBody());

# See Authentication page for details of the variables
RESPONSE=$(curl --request POST \
  --url "$API_URL/terminal/CLEAR_DISPLAY" \
  --header "X-pos-id: POS-STORE123-TERM01" \
  --header "X-tu-authorization: protocol:TU1,accesskey:$ACCESS_KEY,signedheaders:User-Agent;X-tu-date;X-tu-random,signature:$SIGNATURE" \
  --header "X-tu-random: $RANDOM_VAL" \
  --header "X-tu-serial: $SERIAL_NUMBER" \
  --header "X-tu-date: $TU_DATE" \
  --header "User-Agent: $USER_AGENT" \
  --header "Content-Type: application/json" \
  --data "{
    \"merchantID\": \"$MERCHANT_ID\",
    \"posId\": \"POS-STORE123-TERM01\",
    \"serialNumber\": \"$SERIAL_NUMBER\"
  }" \
 )

Clear Display Response

BODY

The following is an example of a Clear Display response body the POS Application will receive.

{
    "result":"SUCCESS"
}

PING Request

Sends a PING request to POSBuddy Cloud, in order to verify the terminal WebSocket connection is live.

POST

posbuddy-cloud/v/1/terminal/PING

Example: PING

BODY

The following is an example of a PING request body

{
    "merchantID": "770000000000123",
    "posId": "POS-STORE123-TERM01",
    "serialNumber": "PF5544544664"
}

String apiUrl = "https://paymentuat.test.thumbzup.com/posbuddy-cloud/v/1/";

JSONObject requestBody = new JSONObject();
requestBody.put("merchantID", merchantID);
requestBody.put("posId", posId);
requestBody.put("serialNumber", serialNumber);

System.out.println("Sending request: " + requestBody + "...\n");

// See Authentication for details of the generateHeaders function
Map<String, String> headers = generateHeaders(secretKey, accessKey, userAgent, serialNumber, posId);
RequestBodyEntity request = Unirest.post(apiUrl + "terminal/PING")
        .headers(headers)
        .body(requestBody.toString());

HttpResponse<JsonNode> response = request.asJson();

System.out.println("Received response: " + response.getBody());

# See Authentication page for details of the variables
RESPONSE=$(curl --request POST \
  --url "$API_URL/terminal/PING" \
  --header "X-pos-id: POS-STORE123-TERM01" \
  --header "X-tu-authorization: protocol:TU1,accesskey:$ACCESS_KEY,signedheaders:User-Agent;X-tu-date;X-tu-random,signature:$SIGNATURE" \
  --header "X-tu-random: $RANDOM_VAL" \
  --header "X-tu-serial: $SERIAL_NUMBER" \
  --header "X-tu-date: $TU_DATE" \
  --header "User-Agent: $USER_AGENT" \
  --header "Content-Type: application/json" \
  --data "{
    \"merchantID\": \"$MERCHANT_ID\",
    \"posId\": \"POS-STORE123-TERM01\",
    \"serialNumber\": \"$SERIAL_NUMBER\"
  }" \
 )

PING Response

BODY

The following is an example of a PING response body the POS Application will receive.

{
    "result": "SUCCESS"
    "device": "P3_MIX_STD",
    "serial": "PF01P38S20015",
    "availableServices": [
      {
        "label": "Fallback Payment",
        "packageName": "com.ecentric.fallbackpayment"
      },
      {
        "label": "Tipping",
        "packageName": "com.ecentric.tipping"
      }
    ]
  }