Introduction
This document describes the NEXO protocol implementation in the West payment application.
The NEXO protocol is one method of controlling a payment terminal from an Electronic Cash Register (ECR). The NEXO protocol attempts to be very comprehensive and so there is a lot of the NEXO protocol that is unnecessary for these purposes. Despite this, there are a number of gaps in the protocol that mean some customization has been required. The aim of this document is to specify which NEXO messages are used, which parts of the messages are relevant, and which messages have been customized to fit the requirements of the payment application.
This document will refer to a number of specifications:
NEXO Sale to POI Protocol Specifications V3.1
NEXO Sale to POI Transport Protocols V3.1
NEXO Sale to POI Architectures and Models V3.1
The first of these is the full NEXO specification, and is the primary source for all aspects of the NEXO protocol.
The NEXO documentation is available on this website:
https://www.nexo-standards.org/user?category=protocols&about=nexo-retailer-protocols
Note that you need to create a account to login and access the website above. |
Protocol overview
The interface between the payment application and the ECR provides a range of functionality including:
ECR login
Starting a transaction
Handling message display on the ECR
Printing receipts on the ECR
Performing administrative functions
In an NEXO environment the ECR device is the retailer's interface to the complete sales system, while the payment terminal is the customer's interface. During a customer transaction, therefore, the retailer must be able to control and instruct the payment terminal via the ECR's display and keyboard.
Message transport and encoding
All messages are encoded in JSON. For more information, see section JSON Messages Coding/Decoding in the NEXO Sale to POI Protocol Specifications.
TCP/IP network connection
When operating over a TCP/IP network connection all messages are preceded by a four byte length field.
Keepalive
Once connected the ECR must send something to the terminal at regular intervals, otherwise the terminal will assume that the ECR has gone offline or lost connection and will terminate any ongoing service.
If the ECR has no data to send then it can send an empty packet, which is a sequence of four bytes with value zero. Since the first four bytes of a message indicate the message size, this is simply an empty message.
The ECR should aim to send something every two seconds. |
The normal approach here is to have a timer that will expire in two seconds. Whenever something is sent to the terminal the timer can be reset. Whenever the timer fires an empty message header can be sent, and the timer is reset to fire two seconds later.
Message contents
This section describes the NEXO messages that Westpay currently supports. |
Login message
The Login request is sent by the ECR to enable the payment application on the terminal to process transactions. It contains the three elements required for transaction processing, specifically:
- The terminal's TSP ID (the POIID data element in the message header);
- The PPL server that the payment application should go to for configuration data (ConfigHostAddress);
- The SPDH server that the payment application should use for transaction authorization (TxnHostAddress).
Login request message
Login request example
{
"SaleToPOIRequest": {
"MessageHeader": {
"ProtocolVersion": "3.1",
"MessageClass": "Service",
"MessageCategory": "Login",
"MessageType": "Request",
"ServiceID": "3819",
"POIID": "80000135"
},
"LoginRequest": {
"OperatorLanguage": "en",
"OperatorID": "Nisse",
"DateTime": "2019-09-24T15:42:18.9441701+02:00",
"ConfigData": {
"TxnHostAddress": "10.0.3.33:8005",
"ConfigHostAddress": "185.27.171.42:55133"
},
"SaleSoftware": {
"ProviderIdentification": "Westpay AB",
"ApplicationName": "Westpay NEXO ECR",
"SoftwareVersion": "1.0.0.0"
}
}
}
}
_ |
(See section Login Request Layout in NEXO Sale to POI Protocol Specifications for definition of header for each of the message types.)
Login response message
Login response example
{
"SaleToPOIResponse": {
"MessageHeader": {
"ProtocolVersion": "3.1",
"MessageClass": "Service",
"MessageCategory": "Login",
"MessageType": "Response",
"ServiceID": "3819"
},
"LoginResponse": {
"Response": {
"Result": "Success"
},
"POISystemData": {
"DateTime": "2019-09-24T13:42:19.1897420+00:00",
"POISoftware": [
{
"ProviderIdentification": "Westpay AB",
"ApplicationName": "Westpay Payment Application",
"SoftwareVersion": "1.0.0",
"ComponentType": "APPL"
}
]
}
}
}
} |
(See section Login Response Layout in NEXO Sale to POI Protocol Specifications for definition of header for each of the message types.)
Logout message
The Logout request is the reverse of the Login request. It may be sent by the ECR when one of the Login request parameters changes, e.g. the cashier ID, or it may be sent at close of business as a way to place the terminal in an idle mode.
Logout request message
The logout request message contain only the message header and a single LogoutRequest element. It has no children or attributes.
Logout request example
{
"SaleToPOIRequest": {
"MessageHeader": {
"ProtocolVersion": "3.1",
"MessageClass": "Service",
"MessageCategory": "Logout",
"MessageType": "Request",
"ServiceID": "3820",
"POIID": "80000135"
},
"LogoutRequest": {
"MaintenanceAllowed": "False"
}
}
}
_ |
(See section Logout Request Layout in NEXO Sale to POI Protocol Specifications for definition of header for each of the message types.)
Logout response message
-
Logout response example
{
"SaleToPOIResponse": {
"MessageHeader": {
"ProtocolVersion": "3.1",
"MessageClass": "Service",
"MessageCategory": "Logout",
"MessageType": "Response",
"ServiceID": "3820"
},
"LogoutResponse": {
"Response": {
"Result": "Success"
}
}
}
} |
(See section Logout Response Layout in NEXO Sale to POI Protocol Specifications for definition of header for each of the message types.
Transaction Flows
This section provides some example message flow diagrams. The earlier sections define the contents of the messages, this section shows how multiple messages are used to perform a complete function.
Start-up and Login
This diagram shows the start-up steps and sending the first message exchange. This will normally be a login request.
(The dotted lines represent TCP-IP events and the solid lines are EPAS messages.)
|
Payment Transaction (Example)
|
Payment Without Amount, Early PIN Entry (Example)
|
Payment With Swipe Ahead (Example)
|
