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.

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": "1006009",
  "charsPerLine": 80,
  "ipAddress": "192.168.0.17",
  "linesPerScreen": 24,
  "macAddress": "54:81:2D:E1:ED:37",
  "modelName": "A77",
  "osVersion": "27",
  "serial": "1760039186",
  "timestamp": "2026-07-13T17:48:49.656Z"
}

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

Capturing Signature

While signature capture is one of the Card Present Authorization Methods, its use cases extend well beyond payment authorization.

It serves as a flexible way to record a merchant-customer agreement outside of the main transaction flow.

Common examples include:

• CIT-MIT agreements. Also see Customer and Merchant Initiated Transactions
• Back-office or ticketing processes
• Refunds (given that authorization methods are not enabled for BluePOS Refunds by default)
• Any other scenario requiring formal customer consent or acknowledgment

On top of that, a signature can be captured during the Show Dialog window to document specific merchant-customer agreements or terms.

Request

GET /api/v4/accounts/{accountId}/poi/{serial}/capture-signature?timeoutSeconds=60

*Required Scopes: pcx:poi:*, pcx:poi:capture_signature

Response

{
  "signature": "0,65535^0,65535^0,65535^313,613^316,609^320,605^323,602^327,599^330,595^334,592^338,588^0,65535^340,587^343,583^347,579^350,576^354,572^357,569^361,566^365,562^368,559^372,556^376,552^379,549^383,545^386, ..."
}

In response, the merchant receives the captured customer signature to work with - in a stroke-based vector format.

For more information, refer to Signature Format.

Show Dialog

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

{
  "timeout": 120,
  "title": "Select Transaction",
  "button1": "Sale",
  "button2": "Authorization",
  "button3": "Force",
  "button4": "Credit",
  "body": "Line0\nLine1\n\nLine3\nLine4\n\nLine6",
  "signatureCapture": "omit",
  "fullscreen": true,
  "style": {
    "backgroundColor": "#FFAA00",
    "textColor": "light",
    "textSize": "small"
  }
}

*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).

Request Body Parameters

Style Object Properties

Receipt Reprint

Integrators can request receipt reprints directly on BluePOS terminals using the POI Receipt Print endpoint.

This allows you to print a customer or merchant copy of a previous PayConex transaction without requiring manual intervention on the device. In other words, the device physically prints the receipt when this API request is made.

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

{
  "transactionId": "000000100066",
  "copy": "customer",
  "transType": "sale",
  "additionalInfo": "Optional additional receipt content"
}

*Required Scopes: pcx:poi:*, pcx:poi:reprint

Successful Reprint Response

{
  "outcome": "success"
}

Request Fields

Custom Receipt

To print a custom receipt or receipts in general, 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.