Integration - Concert

To begin with, Concert is the name of a communication protocol defined by “Association du Paiement” between a cash register and a POS.

It lists all the communication interfaces it supports (ex: WIFI, Bluetooth), it describe data content and data exchange workflow.

Summary

Concert in PayXpress

A part of this protocol has been implemented in PayXpress in order to support it. In our application architecture, we call it “Concert Service”. We will use this name to refer to the implementation of Concert protocol in the following documentation.

Today, Concert Service supports these communication interfaces:

Concert supported connections

There are two different ways a cash register can establish physical communication with the POS terminal:

• a USB cable connected to the PC, or

• via IP/Ethernet (RJ45) connected to a router or through Wifi

Here is an overview of the differences between these two types of connections:

IP/Ethernet and WIFI connection specifications

Both connection specifications are the same. Cash register and POS device will be connected to the same network in order to be able to communicate with each other.

Cash register is always the first to start a communication with the POS, so it implies that cash register knows the POS IP address and port to use before doing any calls.

For POS port, it is possible to configure it in PayXpress application in “Burger menu” > “Settings” > “Concert configuration” > “Port”.

User can still check the Concert service configuration on the main page of PayXpress, there is a small description of the running configuration at the bottom of the page.

Regarding security aspects, there is no SSL, no data ciphering. All the data are transferred through a socket between the cash register and the POS. A whitelist mechanism is implemented in PayXpress to filter IP addresses, in “Burger menu” > “Settings” > “Concert configuration” > “Whitelist”.

Developer implementation notes

Use a socket for sending data to the POS and keep it alive until POS replies but make sure a new socket is opened each time a new query/answer is done. A timeout can be set but do not set it below 1~2 minutes for transaction query if you are running it synchronously, some transactions could take some time because there are some user input pages such as cardholder insert card page or ticket dematerialisation page so shutting down socket would make cash register to lose transaction result (such cases can be prevented, it will be covered in next sections).

WIFI communication is not constraint to single thread, so you can call as much as you want POS device with a new socket, you will get a reply for each call. Keep in mind that only one transaction can be processed in the mean time, so any other transaction queries would be declined if there is already one in running.

USB/RS232 connections specifications

RS232 specifications are more complex than any other, it implies a strict data structure and data exchange workflow. This section will only talk about technical specifications regarding RS232, the concert data structure will be fully explained in other section.

So USB/RS232 means cash register and POS will be linked thanks to a cable, USB or RS232. The type of cable does not matter, the communication will work the same way in Concert. Unlike WIFI, USB/RS232 is half-duplex, it means cash register and POS cannot emit and receive messages simultaneously.

This is the list of speeds (baud or symbols/s) that PayXpress supports:

Each frame is composed of max 512 data bytes.

A data byte will be composed of 7 bits of data and a bit of parity.

The parity used in concert specifications is EVEN. It means the number of raised bits (1 bit) is always even in a data byte. If the 7 bits of data contain a even raised bits number, parity bit is 0, if it is odd, parity bit is 1.

This is a security control to prevent any tampering of the data. Regarding the 7 bits of data, they are ASCII-7 and the range of supported characters begins to 0x20 (hex) SPACE until 0x7F (hex) DEL. You can find the list of supported characters in this table.

In a frame, the first data byte is a command that defines the meaning of the frame. All the commands are described in the table below:

The specifications define the order of commands when cash register and POS communicate. Like in Ethernet/WIFI, the POS is in a waiting state and it is up to the cash register to initiate the communication.

• ENQ is always the first command to be sent, it opens a new session receiver side

• ACK is sent by the receiver to confirm that it successfully received the sender message

• NAK in the other hand is sent by the receiver to confirm that it did not receive the sender message or data controls failed

• STX and ETX are always sent together like this “STX<message>ETXlrc”. Sometimes, the word “message” in Concert specifications is used to refer to the entire frame

 This exchange data flow is fully explained below with diagram and tables.

Constant/variables names

Listening procedure for cash register & POS

Emitting procedure for cash register

Developer implementation notes

Unlike Ethernet/WIFI, USB/RS232 connection does not allow any multithreading processus. Do not start any new request if there is already one in running, it will lead to errors for both of them.

Parity and LRC controls on STX<message>ETXlrc receipt can be performed both in the same time because they only concern one frame and the same data. As a reminder, parity control is only done on ASCII-7 data bytes (no command byte) and LRC is computed from all ASCII-7 data bytes + ETX byte. This is a code snippet (kotlin) which performs both controls:

fun isParityBitOrLrcOk(frame: List<Byte>, lrc: Byte? = null): Boolean {
    var isParityAndLrcOk = false
    var computedLrc: Byte = 0x0
    // frame only contains ASCII-7 data bytes
    for (byte in frame) {
        val oneBitsCount = byte.countOneBits()
        // oneBitsCount is odd, there is a parity error
        if (oneBitsCount % 2 != 0) {
            return isParityAndLrcOk 
        }
        // LRC Computation
        if (lrc != null)
            computedLrc = computedLrc xor byte
    }
    // Frame does not contain ETX command, do a XOR using ETX value manually
    if (lrc != null && frame.last() != 0x03.toByte())
        computedLrc = computedLrc xor 0x03
    // Compare incoming LRC to the computed one
    return lrc == null || computedLrc == lrc
}

Same thing has to be done during the message building when cash register wants to send a message to the POS. This is a code snippet (kotlin) which builds the data to be sent with parity and lrc computation:

fun buildChunksForEmit(dataToSend: String): String {
    val commandStringBuilder = StringBuilder()
    var computedLrc: Byte = 0x0
    commandStringBuilder.append("02") // STX
    for (char in dataToSend) {
        val binaryRepresentation = char.code.toByte()
        val oneBitsCount = binaryRepresentation.countOneBits()
        val isOdd = oneBitsCount % 2 != 0
        val binaryRepresentationWithParity = 
            if (isParityCheckEnabled && isOdd) it.raiseBit(8)
            else it
        computedLrc = computedLrc xor binaryRepresentationWithParity 
        commandStringBuilder.append(
            binaryRepresentationWithParity
                .toUByte()
                .toInt()
                .toString(16)
        )    
    }
    // padStart ensure LRC hex representation length will always be 2
    val lrcAsString =
        (computedLrc xor 0x03)
            .toUByte()
            .toInt()
            .toString(16)
            .padStart(2, '0')
    val etxAndLrc = "03$lrcAsString" // ETX + LRC
    commandStringBuilder.append(etxAndLrc)
    return commandStringBuilder.toString()
}

If you want to use the code snippet above, please be careful, it builds a hex representation of the string, so each byte will become two chars. It is helpful for debugging/logs but make sure when you are sending this hex string that you convert each two chars couples in one byte before.

Regarding events and state tables, Concert specifications contain a lot of examples when something goes wrong

Concert data structure

Depending the Concert specifications version, the structure of the data changes very significantly. This documentation will explain the main changes between V2 & V3

Concert V2 data structure

First of all, in V2, there is only one supported communication method which is USB/RS232. In this version, all the data are structured following a specific order. The structure is different between the query of the cash register and the reply of the POS.

Following tables will detail the structure of data <message> including STX, ETX and LRC.

Data structure of the cash register query

Data structure of the POS reply

A POS message could look like this (STX + <message> + ETX + lrc):

Concert V3 data structure

API

The Concert Protocol API allows the cash register to communicate with PayXpress (who in turn, communicates with the back end), in order to handle all aspects of the payment request (and tickets):