Local integration

Transport protocol

Use of WebSocket as transport protocol is not described by Nexo, but is used for the following reasons:

Provides full-duplex communication, allowing messages to flow in both directions at any time, similar to plain TCP
More high level and easier to implement than plain TCP
Good support in programming languages and frameworks, including browsers
Proxy and firewall friendly as it uses HTTP/HTTPS to bootstrap the connection

General message flow

The following diagram shows an example high level message flow.

sequenceDiagram
    participant ECR
    participant Terminal as Terminal (OP-AIC)

    opt
        ECR->>Terminal: 1 Get terminals
        Terminal-->>ECR: 2 Get terminals response
    end

    ECR->>Terminal: 3 Connect (ECR identifier)

    loop
        ECR->>Terminal: 4 KeepAlive
    end

    loop
        Terminal-->>ECR: 5 KeepAlive
    end

    ECR->>Terminal: 6 Login request (ServiceID: 1)
    Terminal-->>ECR: 7 Login response (ServiceID: 1)

    ECR->>Terminal: 8 Payment request (ServiceID: 2)

    opt Zero or more - depending on service message category
        Terminal-->>ECR: 9 Device request (ServiceID: 2, DeviceID: 1)
    end

    Terminal-->>ECR: 10 Payment response (ServiceID: 2)

Step	Description
1,2	ECR performs terminal discovery to get a list of terminals it has access to. Not needed when one ECR is using only one terminal..
3	Initial WebSocket connection
4,5	When the connection is established, both ECR and AIC should start sending KeepAlive messages. This enables both parties to quickly detect if the connection is broken.
6,7	Login from ECR to terminal. Login creates a session between the ECR and the terminal, and allows the ECR and terminal to exchange information about capabilities. Login must be performed before other requests are sent from ECR..
8	ECR sends a service request, e.g. for standard payment
9	Depending on the type of service request, the terminal can send device requests to the ECR. For example display notifications to inform cashier about status.
10	Service response to the ECR.

Connection management

ECR connects to AIC, providing an ECR identifier (e.g. name of ECR) in a query parameter.

Connection string template

ws://<AIC host>:<port>/ws/nexo?saleName=<ECR identifier>

Messages are sent over the websocket using text frames.

Note: The connection string should be configurable in the ECR.

Terminal discovery

The ECR can perform a HTTP request to get a list of known terminals and their connectivity status:

Connection string template

GET http://<AIC host>:<port>/poi-list

Note: The request URL should be configurable in the ECR.

Example response

[
  {
    "poiName": "AT12345",
    "connectionStatus": "Disconnected"
  },
  {
    "poiName": "AT54321",
    "connectionStatus": "Connected"
  }
]

Property	Description	Mandatory / Optional
poiName	The name of the POI (terminal), a.k.a. terminal ID	Mandatory
connectionStatus	Connectivity status of the terminal. Enum: ‘Connected’ - the terminal is connected to AIC and ready to receive messages from the ECR Enum: ‘Disconnected’ - the terminal has been connected since AIC started, but is not connected now	Mandatory

Property

Description

Mandatory / Optional

poiName

The name of the POI (terminal), a.k.a. terminal ID

Mandatory

connectionStatus

Connectivity status of the terminal.

Enum: ‘Connected’ - the terminal is connected to AIC and ready to receive messages from the ECR

Enum: ‘Disconnected’ - the terminal has been connected since AIC started, but is not connected now

Mandatory

If /poi-list returns an empty list ([]), it means that no terminals are connected to AIC.

If the ECR does not already know (pre-configured) the terminal ID of the terminal it wants to use, it should retry the GET /poi-list with a delay between requests until it gets a response with a terminal with status Connected.

To send a message to a given terminal, the value from 'poiName' should be used in the POIID property in the message header. See section 7.2 for description of the message header fields.

Keep Alive

Keep alive messages are used to enable both parties to quickly detect if the connection is broken for any reason, such as network or power failure.

Keep alive must be sent by both ECR and AIC every 5 seconds, and a general read timeout of 10 seconds must be implemented. This will allow for one missing keep alive message before the connection is considered as lost.

A keep alive message is an empty web socket text frame.

If timeout occurs, the ECR should close and reopen the connection.

Note: For development purposes, disabling Keep alive messages can be done in AIC configuration.