Child pages
  • NEXO protocol implementation
Skip to end of metadata
Go to start of metadata

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:

  1. NEXO Sale to POI Protocol Specifications V3.1

  2. NEXO Sale to POI Transport Protocols V3.1

  3. 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.
Once logged in, you can download the zip file NEXO SALE TO POI PROTOCOL specification containing all three PDF files.  


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:

  1. The terminal's TSP ID (the POIID data element in the message header);
  2. The PPL server that the payment application should go to for configuration data (ConfigHostAddress);
  3. The SPDH server that the payment application should use for transaction authorization (TxnHostAddress).


Login request message

Login request example

Login request (ECR -> POI):
{
  "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

Login response (POI -> ECR):
{
  "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

Logout request (ECR -> POI):
{
  "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

Logout response (POI -> ECR):
{
  "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.






Admin message

The Admin message allows the ECR to request specific administrative tasks from the payment application on the terminal. These are not related to an ongoing transaction.

Admin request

See section Admin Request Layout   in NEXO Sale to POI Protocol Specifications   for definition of header for each of the message types.

Admin response message

See section Admin Response Layout   in NEXO Sale to POI Protocol Specifications   for definition of header for each of the message types.




Enable Service message

The Enable Service message provides support to enable / disable the card readers outside of a transaction.  This allows the terminal to collect card details and perform initial checks and data acquisition ahead of the actual transaction, saving time for the customer since they can have the card ready to go while the cashier is busy.

Enable Service request message

See section Enable Service Request Layout   in NEXO Sale to POI Protocol Specifications   for definition of header for each of the message types.

Enable Service response message

See section Enable Service Response Layout   in NEXO Sale to POI Protocol Specifications   for definition of header for each of the message types.





Payment message

A Payment request sent by the ECR indicates the start of a transaction. It may include amount data, in which case the transaction can proceed normally, or it may exclude amount data in which case the amount data is provided later when known (the 'swipe-ahead' scenario.)

Payment request message

See section Payment Request Layout  in NEXO Sale to POI Protocol Specifications   for definition of header for each of the message types.

Payment response message

See section Payment Response Layout  in NEXO Sale to POI Protocol Specifications   for definition of header for each of the message types.





Loyalty Message

A Loyalty request message is sent from the terminal to the ECR when a card is read and the card is confirmed as a loyalty card.  Note that PCI rules prohibit sending payment card details to the ECR  without encryption, therefore combined payment / loyalty cards are treated only as payment cards when the payment application is running NEXO.

Loyalty request message

See section Loyalty Request Layout  in NEXO Sale to POI Protocol Specifications   for definition of header for each of the message types.

Loyalty response message

See section Loyalty Response Layout  in NEXO Sale to POI Protocol Specifications   for definition of header for each of the message types.





Reversal Message

The Reversal request informs the terminal that the previous transaction must be reversed. Only the most recent transaction can be reversed, and when a new transaction is started then the previous transaction can no longer be reversed.

Reversal request message

See section Reversal Request Layout  in NEXO Sale to POI Protocol Specifications   for definition of header for each of the message types.

Reversal response message

See section Reversal Response Layout  in NEXO Sale to POI Protocol Specifications   for definition of header for each of the message types.





Display Message

The NEXO specification defines the display processing as symmetrical, i.e. the ECR and the payment terminal can each send requests to the other to request that something is displayed on screen.  In practice there is limited support for this arrangement:

  • Display request from the terminal:  The West payment application will sending display requests to the ECR to inform the cashier of the transaction progress and also to get input from the cashier.
  • Display request from the ECR:  This is only supported in one specific case, which is to display a QR code on the screen of the payment application in order to support alternative payment methods.  The payment application will not handle requests to display text on the terminal's screen.

Display request message (when sent by the payment application)

The ECR can use the display requests to track the progress of a transaction by checking the prompt ID. This allows the ECR / cashier to be aware of what stage the transaction has reached.  The prompt IDs are included in a table below.

The Display Request message shall be sent for every time the payment terminal prompts for new information, e.g. insert card, enter PIN, pin invalid – try again. Display Request message is defined in  NEXO Sale to POI Protocol Specifications .

The payment terminal does not expect a response to this message. Display Response messages will be ignored.

The display output text will be provided in the chosen operator language, which may be different to the cardholder language being used on the terminal. To make it easier for the ECR device to know exactly which step the payment processing has reached, an enumerated type is added to the message. This will be constant regardless of the display language and uniquely identify each step.


Display request message (when sent by the ECR)

There is only one situation where the ECR can send a display request to the payment application, and that is to display a QR code on the terminal screen. The payment application will only display the QR code if that feature is enabled in configuration, and also it will only display the QR code at specific times. So this display request can be interpreted as supplying a QR code value to be displayed when appropriate, rather than to be displayed at the time the message is sent.

If the QR code is no longer required then a new request can be sent where the QR code value is empty.

See section Display Request Layout  in   NEXO Sale to POI Protocol Specifications   for definition of header for each of the message types.





Input response

The terminal application does not support the Input request message. Instead, if a response is required from the ECR then the information will be included in the optional Input element of the Display request that prompts for the information (see above).

Cashier responses are sent to the payment terminal using the Input response message.

The Input response message is also used to inform that application of the transaction amounts in cases where the Payment request was sent with no amount information.

Note that the Input response may be sent to the payment terminal without a previous Input request having been issued (since Input request is not supported).


Input response message

See section Input Response Layout  in   NEXO Sale to POI Protocol Specifications   for definition of header for each of the message types.




Print request - terminal to ECR

The Print request message is sent by the terminal to request the ECR to print, normally, a card receipt, but it is also used for error message and reports.

The NEXO specification defines the printed content as a series of text elements, each with a set of attributes, but even though this seems like a flexible approach it means that the exact layout of the receipt becomes the responsibility of the payment application, even though it does not know what type of printer is in use, or the paper size, etc.  The payment application uses a substantially altered print request message where each data element is provided separately and then it is up to the ECR to decide how the receipt should be formatted.

When sending receipt data the print request message includes a pre-formatted receipt, but this is intended for debug / test purposes and may not be supported in the future.  It is strongly recommended that integrators should use the individual data elements provided and construct the receipt according to the applicable layout rules.

Note that the terminal does not expect to receive, and will not wait for, a Print response message.

Print request message

See section  Print Request Layout   in   NEXO Sale to POI Protocol Specifications   for definition of header for each of the message types.




Print request - ECR to terminal

The ECR can send a print request to the terminal, but this is a very specific and limited implementation.  Support for this is a specific configuration option that must be enabled in the terminal.  The print request can only contain a monochrome Windows bitmap (.BMP) image and it must be no wider than 384 pixels.

The image data is prepared by taking the contents of a bitmap file and compressing it using the gzip compression algorithm.  It is then encoded using base64.  An example of this preparation is as follows:

Print request message

See section Print Request Layout  in   NEXO Sale to POI Protocol Specifications   for definition of header for each of the message types.

Print response message

See section Print Response Layout  in   NEXO Sale to POI Protocol Specifications   for definition of header for each of the message types.



Abort message

The Abort request message instructs the terminal to cancel the ongoing service request.  If there is no ongoing service request then the abort request will be ignored.

Note that there is no abort response, instead the normal service response will be sent.  For example, if a payment request is aborted then the payment response will be sent with the appropriate values in place.

If the abort request is received but the ongoing service request cannot be aborted then an event notification with a Reject status (see below) will be sent to indicate this.

Note that the terminal will regard the request as applying to the service that is active at the time when the request is received, and will not use the ServiceID component.  The MessageCategory value is only used in an error response, and is otherwise ignored.

Abort request message

See section Abort Request Layout  in   NEXO Sale to POI Protocol Specifications   for definition of header for each of the message types.



Event Notification

Event notification message

See section Event Notification Layout  in   NEXO Sale to POI Protocol Specifications   for definition of header for each of the message types.

Reconciliation request message

See section Reconciliation Request Layout  in   NEXO Sale to POI Protocol Specifications   for definition of header for each of the message types.

Reconciliation response message

See section Reconciliation Response Layout  in   NEXO Sale to POI Protocol Specifications   for definition of header for each of the message types.



GetTotals message

The GetTotals message is used to create the same kind of reports as Reconciliation did, but without closing the batch. 

Get totals request message

See section GetTotals Request Layout  in   NEXO Sale to POI Protocol Specifications   for definition of header for each of the message types.

GetTotals response message

See section GetTotals 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)


  • No labels