Documentation
WebsiteHelp

Commands

Suggest Edits

What is a Command?

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

📘

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

{
    "serialNumber": "PF5544544664",
    "merchantID": "770000000000123",
    "posID": "POS-STORE123-TERM01",
    "html": "<html content>",
    "css": "<css content>",
    "width": <printer width>
}

import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;
public class PostExample {
    public static void main(String[] args) {
        String urlString = "https://posbuddy-cloud/v/1/terminal/PRINT_HTML";
        String jsonData = """
            {
                "serialNumber": "PF5544544664",
                "merchantID": "770000000000123",
                "posID": "POS-STORE123-TERM01",
                "html": "<html content>",
                "css": "<css content>",
                "width": 80
            }
            """;
        try {
            URL url = new URL(urlString);
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            conn.setRequestMethod("POST");
            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("Content-Type", "application/json; utf-8");
            conn.setDoOutput(true);
            try (OutputStream os = conn.getOutputStream()) {
                byte[] input = jsonData.getBytes(StandardCharsets.UTF_8);
                os.write(input, 0, input.length);
            }
            int responseCode = conn.getResponseCode();
            System.out.println("Response Code: " + responseCode);
            // You can add code here to read the response body if needed
            conn.disconnect();
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

curl --request POST\
  --url 'https://posbuddy-cloud/v/1/terminal/PRINT_HTML' \
  --header 'Accept: application/json'\
  --data '{
    "serialNumber": "PF5544544664",
    "merchantID": "770000000000123",
    "posID": "POS-STORE123-TERM01",
    "html": "<html content>",
    "css": "<css content>",
    "width": 80
}'

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

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

import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;

public class PostExample {
    public static void main(String[] args) {
        String urlString = "https://posbuddy-cloud/v/1/terminal/SETTINGS";
        String jsonData = """
            {
                "serialNumber": "PF5544544664",
                "merchantID": "770000000000123",
                "posID": "POS-STORE123-TERM01",
                "autoStart": "false",
                "runInBackground": "false"
            }
            """;

        try {
            URL url = new URL(urlString);
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestMethod("POST");
            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("Content-Type", "application/json; utf-8");
            conn.setDoOutput(true);

            try (OutputStream os = conn.getOutputStream()) {
                byte[] input = jsonData.getBytes(StandardCharsets.UTF_8);
                os.write(input, 0, input.length);
            }

            int responseCode = conn.getResponseCode();
            System.out.println("Response Code: " + responseCode);

            // You can add code here to read the response body if needed

            conn.disconnect();
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

curl --request POST\
  --url 'https://posbuddy-cloud/v/1/terminal/SETTINGS' \
  --header 'Accept: application/json'\
  --data '{
    "serialNumber": "PF5544544664",
    "merchantID": "770000000000123",
    "posID": "POS-STORE123-TERM01",
    "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

{
    "serialNumber": "PF5544544664",
    "merchantID": "770000000000123",
    "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"
}

import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;
public class PostExample {
    public static void main(String[] args) {
        String urlString = "https://posbuddy-cloud/v/1/terminal/DISPLAY_ITEMS";
        String jsonData = """
            {
                "serialNumber": "PF5544544664",
                "merchantID": "770000000000123",
                "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"
            }
            """;
        try {
            URL url = new URL(urlString);
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            conn.setRequestMethod("POST");
            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("Content-Type", "application/json; utf-8");
            conn.setDoOutput(true);
            try (OutputStream os = conn.getOutputStream()) {
                byte[] input = jsonData.getBytes(StandardCharsets.UTF_8);
                os.write(input, 0, input.length);
            }
            int responseCode = conn.getResponseCode();
            System.out.println("Response Code: " + responseCode);
            // You can add code here to read the response body if needed
            conn.disconnect();
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

curl --request POST\
  --url 'https://posbuddy-cloud/v/1/terminal/DISPLAY_ITEMS' \
  --header 'Accept: application/json'\
  --data '{
    "serialNumber": "PF5544544664",
    "merchantID": "770000000000123",
    "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

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

import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;
public class PostExample {
    public static void main(String[] args) {
        String urlString = "https://posbuddy-cloud/v/1/terminal/CLEAR_DISPLAY";
        String jsonData = """
            {
                "serialNumber": "PF5544544664",
                "merchantID": "770000000000123",
                "posID": "POS-STORE123-TERM01",
            }
            """;
        try {
            URL url = new URL(urlString);
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            conn.setRequestMethod("POST");
            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("Content-Type", "application/json; utf-8");
            conn.setDoOutput(true);
            try (OutputStream os = conn.getOutputStream()) {
                byte[] input = jsonData.getBytes(StandardCharsets.UTF_8);
                os.write(input, 0, input.length);
            }
            int responseCode = conn.getResponseCode();
            System.out.println("Response Code: " + responseCode);
            // You can add code here to read the response body if needed
            conn.disconnect();
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

curl --request POST\
  --url 'https://posbuddy-cloud/v/1/terminal/CLEAR_DISPLAY' \
  --header 'Accept: application/json'\
  --data '{
    "serialNumber": "PF5544544664",
    "merchantID": "770000000000123",
    "posID": "POS-STORE123-TERM01",
}'

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

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

import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;

public class PostExample {
    public static void main(String[] args) {
        String urlString = "https://posbuddy-cloud/v/1/terminal/PING";
        String jsonData = """
            {
                "serialNumber": "PF5544544664",
                "merchantID": "770000000000123",
                "posID": "POS-STORE123-TERM01",
            }
            """;

        try {
            URL url = new URL(urlString);
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();

            conn.setRequestMethod("POST");
            conn.setRequestProperty("Accept", "application/json");
            conn.setRequestProperty("Content-Type", "application/json; utf-8");
            conn.setDoOutput(true);

            try (OutputStream os = conn.getOutputStream()) {
                byte[] input = jsonData.getBytes(StandardCharsets.UTF_8);
                os.write(input, 0, input.length);
            }

            int responseCode = conn.getResponseCode();
            System.out.println("Response Code: " + responseCode);

            // You can add code here to read the response body if needed

            conn.disconnect();
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

curl --request POST\
  --url 'https://posbuddy-cloud/v/1/terminal/PING' \
  --header 'Accept: application/json'\
  --data '{
    "serialNumber": "PF5544544664",
    "merchantID": "770000000000123",
    "posID": "POS-STORE123-TERM01",
}'

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"
      }
    ]
  }

Updated 13 days ago