Device Commands

Overview

As outlined in the Introduction, the BluePOS REST API allows the ISV to control PAX devices in Semi-integrated Mode. This section provides a list of all commands supported for managing the state of a PAX device. Note that the transaction processing is also considered a device command as it tells the device the type of transaction it should trigger.

In this section, we provide some sample requests for device commands. For the comprehensive reference on all the body parameters, refer to API Reference.

📘

Note

It only takes two parameters necessary for making a REST API request against the device where:

• {accountId} value in the path is the PayConex™ account ID number.
• {serial} value in the path is the serial number of the device, which can be found on the back of the device.

Status

GET /api/v4/accounts/{accountId}/poi/{serial}/status

*Required Scopes: pcx:poi:*, pcx:poi:status

This retrieves the BluePOS app status along with key data fields about the device. This endpoint is also useful for testing the connection, ensuring a successful response from the device.

Response

{
  "appName": "com.bluefin.bluepos",
  "appVersion": "1003004",
  "charsPerLine": 80,
  "ipAddress": "192.168.0.12",
  "linesPerScreen": 24,
  "macAddress": "54:81:2D:E1:ED:37",
  "modelName": "A77",
  "osVersion": "27",
  "serial": "1760039186",
  "timestamp": "2025-07-25T13:48:15.679Z"
}

Reboot

If the device becomes unresponsive or its configuration gets updated by the Bluefin team, it is possible to reboot it via the REST API.

Instant rebooting is allowed but this command also comes with other options such as

Request

POST /api/v4/accounts/{accountId}/poi/{serial}/reboot

{
  "allowOverride": true,
  "delayInSeconds": 30
}

*Required Scopes: pcx:poi:*, pcx:poi:reboot

Successful reboot

{
  "outcome": "REBOOTING"
}

Reboot canceled

{
  "outcome": "CANCELLED"
}

Cancel Command

As a better alternative to the reboot command in cases where we don't want to entirely reboot the device, we can cancel an ongoing command with the following request.

POST /api/v4/accounts/{accountId}/poi/{serial}/cancel

*Required Scopes: pcx:poi:*, pcx:poi:cancel

{
  "timeout": 120
}

Response

{
  "status": "ok"
}

Sale Response: Ongoing command

If we cancel an ongoing sale transaction, the following is returned to that (ongoing) API request.

{
  "errorCode": 103,
  "message": "payment reset",
  "value": "FAILED"
}

Show Dialog

POST /api/v4/accounts/{accountId}/poi/{serial}/show-dialog

{
  "timeout": 120,
  "title": "Select Transaction",
  "button1": "Sale",
  "button2": "Authorization",
  "button3": "Force",
  "button4": "Credit"
}

*Required Scopes: pcx:poi:*, pcx:poi:show_dialog

In the BluePOS Application, we can send a command to the device to spawn a dialog with up to 4 options that the customer can choose from.

Upon selection, we receive what the customer has picked as 1-based indexing.

{
  "selected": 1
}

By the request above, this means the customer has selected "Sale".

Some other use cases include:

• Payment Method Selection: Present the customer with options to choose between different payment methods (e.g., "Card", "Cash", "Gift Card", etc.).

• Transaction Confirmation: Ask the customer to confirm their transaction type or review order details before processing the payment.

• Additional Actions: Allow the customer to choose between options like "Print Receipt", "Send Email Receipt", or "No Receipt" after a transaction is completed.

• Tip Selection: Present a dialog for selecting a tip amount (e.g., "No Tip", "10%", "15%", "20%", or a custom amount).

Custom Receipt

To print a custom receipt, the PAX device has to support it as one of the hardware features. For example, check out the hardware features of PAX A80.

POST /api/v4/accounts/{accountId}/poi/{serial}/custom-receipt

{
  "timeout": 120,
  "content": "\\3\\CSALE RECEIPT\n\n\\CSuper Store\n\n\n\n\\$Date\n\n\\Client : John Doe\n\n\\Receptionist : Joe Bloggs M\n\n\n\n\\LSale Product\\$25.00\n\n\\LSUBTOTAL\\$25.00\n\n\\LTax\\$0.00\n\n\n\n\\LTOTAL\\$25.00\n\n\n\n\\$Trailer\\$Disclaimer"
}

*Required Scopes: pcx:poi:*, pcx:poi:custom_print

The raw string for printing includes some control characters:

• \n: Inserts a newline.
• \\L: Aligns text to the left.
• \\C: Centers the text.
• \\$: Inserts a placeholder for dynamic content, like date or disclaimers.

These placeholders allow the receipt content to be dynamically generated and formatted based on the transaction details.