AP Concert Protocol

1) Overview

To begin with, Concert is the name of a communication protocol defined by “Association du Paiement”.
This protocol is used to define exchanges between a card payment terminal (POS) and a cash register software. It is widely used in the payments ecosystem, it has been available since July 2020 in its version 3.20.

This document lists all the communication interfaces it supports (ex: WiFi, Bluetooth), and it describes data content and data exchange workflow.

2) Supported POS Devices

This integration is supported by:

• Castles Devices: S1F2, S1P

• SUNMI Devices: P2 SMARTPAD

3) Transaction Flow

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):

Open

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

Open

Quick overview of how Concert works in PayXpress app

Today, Concert Service supports these communication interfaces:

5) 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 via IP/Wifi

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

IP/Ethernet and IP/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. This port number must be configurable on both the cash register and the POS in order to adapt to different network configurations.

To send a message, the cash register will make a connection to this port number (socket opening) and when the connection is established, the data will be sent.

The logical connection will remain established during the entire processing time of the requested action.

Once the cash register has received the return message from the POS, the cash register will close the connection (socket closure), and the terminal will wait for the reception of a new message.

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

The 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 the Burger menu > “Settings” > “Concert configuration” > “Whitelist”.

Developer implementation notes

Use a socket for sending data to the POS and keep it alive until the 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 the cardholder’s ‘insert card’ page and the ticket dematerialization page, so shutting down the socket would cause the cash register to lose the transaction result (such cases can be prevented; this will be covered in the following sections).

WiFi communication is not constrained to single threads, so you can call the POS device with a new socket as many times as you want, and you will get a reply for each call. Keep in mind that only one transaction can be processed at a time, so any other transaction queries would be declined if there is already one running.

USB/RS232 connections specifications

See USB/RS232 - Specifications.

6) Format of Concert Protocol & Rules

Given its use and for simplicity, the definition of the protocol used does not follow the Basic Encoding Rules for TLV standard “BER-TLV” (ITU-T X.690).

TLV = Type Lenght Value
The Type and Length fields are fixed.

The Length field is defined by three bytes aligned on the right and completed on the left by 0s.

The Type, Length and Value (TLV) information form what is called a “Tag”:

Composition of a Tag:

An example Tag CZ: Encoding the concert protocol version to be used

Constructed Tags

Tags whose first byte of the Type string is “Z” indicate it is a constructed Tag (which contains a set of TLVs).

A constructed Tag allows several simple Tags to be grouped within the same Tag.

An example of a constructed Tag

The rules of using Tags

• A zero-length Tag is not transmitted.

• The Protocol Version Tag CZ is the first tag in the cash register or terminal message. The protocol version allows you to associate the dictionary of Tags managed in the message.

• The order of other Tags in a message is not important.

• There is only one level of constructed Tags: A constructed Tag does not group other constructed Tags, it can only hold simple Tags.
  Except for the ZT tags which is the only one that is composed of AK & CK tags. Furthermore, it’s the only one which can be repeated.

7) Concert data structure

Depending the Concert specifications version, the structure of the data changes very significantly. The pages below explain the main changes between V3 & V2 (Legacy).

Version 3.2 Data structure & Examples

See Concert V3.

Version 2.0 Data structure - Legacy version

See Concert V2 - Legacy.