Introduction

The PayConex™ V4 API comes with the BluePOS set of endpoints for controlling P2PE PAX devices. These devices, among with many other manufacturers, employ the PCI-Validated P2PE Decryptx Solution. For all PAX models and their specifications, refer to P2PE PAX Devices.

BluePOS is a payment application that builds the bridge to our PayConex™ WebSocket Gateway. BluePOS functions in semi-integrated mode, enabling you to trigger transactions from external ECRs running from any location. This reduces the potential complexities of a local network configuration. Once the BluePOS App is launched, the device goes into listen mode with the WebSocket protocol awaiting request commands that initially come from the V4 REST API. The WebSocket Protocol ensures persistent and stable connection, and instant interactions with the device.

In summary, the REST API sends trigger commands to the device via HTTP. The command is forwarded to the WebSocket Gateway, which then delivers it to the device. This process is managed through both REST HTTP and WebSocket protocols.

During transaction processing, the customer is then prompted to interact with the card reader. Once the card is read and encrypted on hardware-level using SRED at the POS, a message is sent back through the WebSocket to the gateway, which communicates with the PayConex™ Services to process the transaction and send it over to the Payment Processor for authorization. At this point, Decryptx® Card Present Transaction workflow takes place. The response is returned, in real-time, to the ECR App that initiated the request over HTTP.

This is illustrated in the following diagram.

Semi-Integrated Mode

📘

Note

* WiFi/4G connection on the device is required.

The integration is taken care of by the Bluefin operations team so you are all set to make your first transaction - whether you want your device to be in the staging, certification, or production environment. According to your needs, the Bluefin team oversees the integration of the BluePOS Application, ensuring the process remains streamlined and efficient.

Other than triggering transactions, the V4 API offers some other commands for controlling the device including:

• Status
• List Transactions
• Reboot
• Cancel Command
• Show Dialog
• Custom Receipt

User Manual

Before using the BluePOS application, it is worthwhile checking out its user manual with the device transaction screenshots and examples.

🚧

Note

Note that the examples from the user manual are not intended for Semi-Integrated Mode but Direct POI (Point Of Interaction) Device Integration Mode with manual card entries.

BluePOS User Manual

• Getting Started
• Processing Card Transactions
• Receipts
• Reports
• Business Settings
• Help

Key Advantages

• Quick Integration

• Device Lock-In

  • Once the BluePOS Application is launched either on startup by default or by the merchant, the device is forced into the lock-in mode restricting the interaction with the device interface outside of the BluePOS Application. This prevents any malicious interactions with the device if stolen.

• Reduces the potential complexities of a local network setup

• Pre-configured Setup

  • The BluePOS Application is configured and integrated by the Bluefin operations team

• Various Card Reading Methods

  • Depending on a device, PAX devices support various card reading methods such as

    • Magnetic Swipe
    • Chip Insert
    • Contactless Tap
    • Manual Card Entry (Virtual Keyboard on the device)

    See the full list here: P2PE PAX Devices.

  BluePOS provides functionality to authorize CP transactions that are processed using the card reading methods above. As mentioned before, this is done on hardware-level using SRED at the POS.

• Real-Time Communication over the WebSocket Protocol and HTTP

Supported Transactions

BluePOS supports some common transaction types suitable for medium to large retail businesses.

• Sale
• Sale and tip (gratuity)
• Sale and cashback
• Force (Enabled depending on the Payment Processor)
• Authorization
• Refunds and Partial Refunds
• Credit (not supported by default for security reasons)

📘

Note

To see these in action, check out the Transaction Processing section.

Supported Features

• PAXSTORE app.
• Connect from anywhere using the REST API, which provides flexibility and ease of access.

Common Concerns

One major common concert would be the connection loss once the card is read and the decrypted payload is off to the PayConex™ Gateway to process the transaction. This is the case where either the ECR or the device loses connection to the internet or similar and is unable to properly handle the transaction workflow. For this reason, the PayConex™ V4 API supports pre-fetching the transaction id by Initializing a Transaction. The merchant is sure there is a transaction entry stored in the system and in case something erroneous or unexpected happens, the transaction entry either populates the error as transaction metadata or the status remains INITIALIZED so that the merchant can retry processing the same transaction.

📘

Note

We recommend initializing a transaction prior to processing any type of transaction. To see how to do this in the BluePOS API, see Initializing a Transaction.

Possible Uses

BluePOS semi-integrated mode works in scenarios with one or more ISV systems controlling at least one POS terminal with access to the BluePOS application via the REST API. But there must be one ISV controlling one device at a time, ensuring the device stability. For instance, in scenarios where two or more ECRs are trying to connect to the same device with the device running the current command, the WebSocket gateway effectively rejects any intervening requests to the device.

{
  "errorCode": 1013,
  "message": "Error. Pending process. Try again later."
}

Common Errors

These are some common errors that can happen when you are running the REST API calls.

Device Not Connected

In order to connect to the WebSocket Gateway and listen for messages, the BluePOS App has to be opened and running. Otherwise, you will see this message.

{
  "message": "Device not connected to Websocket Gateway",
  "errorCode": "40017",
  "errorType": "WEBSOCKET_GATEWAY_ERROR",
  "source": null,
  "value": null,
  "traceId": "346b8b0c-c4f1-4de6-96a0-b1d72c15a7b0",
  "details": []
}

🚧

Note

This is also the case while you are in the Admin page in the BluePOS.

* WebSocket Connection options is required to be turned on.

If you are still seeing this message, please contact Bluefin support team.

Unauthenticated/Unauthorized

🚧

API Key Setup

There are two API keys - one the device uses to communicate with the websocket and the PayConex Gateway (this API key is set up and maintained by the Bluefin Integration Team) and the other that you use to trigger commands onto the device.

For the distinction between Unauthorized and Unauthenticated error for the V4 API, see API Key Management | Common Errors.

In order to run commands on the device, make sure to have the right scope definitions for BluePOS in the API Key.

Here is a table of BluePOS scope definitions.

📘

Also See

For more on API keys, check out the API Key Management.