Message and Communications Protocols

On this page:

Introduction

A message using the Elavon Gateway API format consists of a list of fields, each assigned a field number. The field number (which can be 0-filled to 4 characters or just the number up to 4 characters) is followed by a comma which is followed by the field value. Each line is terminated with a <CR><LF>. Alternatively each line might be terminated by a UNIX <LF>. The message is terminated with an EOT.

Control Characters are defined as follows:

• <CR> = (0x0D) 1 byte, hex D

• <LF> = (0x0A) 1 byte, hex A

• EOT = (0x04) 1 byte, hex 4

The communications protocol between the POS process and Simplify is TCP/IP, or RS-232 (Serial), or PPP with TCP/IP over RS-232.

Simplify supports routing Fusebox messaging via the POS. This is referred to as POS Routing and uses the same protocol as configured for POS messaging.

TCP/IP

TCP/IP communications between the POS and Simplify can be by wired ethernet, Wifi or Bluetooth to base. The availability of these communication methods is device-dependent.

In most systems, Simplify will act as the TCP/IP server. The POS process will act as a TCP/IP client and initiate the connection to Simplify.

• Exception: For Pay@Table systems, the POS process will act as the TCP/IP server. Simplify will act as a TCP/IP client and initiate the connection to the POS.

Simplify-POS messaging can use plain TCP/IP or TCP/IP with TLS 1.2. Depending on security configuration, a certificate may be needed if TLS is used.

RS-232 (Serial)

A serial communication protocol can be used between the POS device and the Simplify application when the device and PIN Pad are attached using a RS-232 connection or USB emulating RS-232. The Simplify serial protocol includes the following elements:

• Start of Text (STX)

• End of Text (ETX)

• Longitudinal Redundancy Check (LRC)

The Longitudinal Redundancy Check (LRC) is generated by performing an exclusive OR on all characters in the message except the Start of Text (STX), but inclusive of the End of Text (ETX). The LRC calculation is performed by both the sending and receiving stations. (See below for calculation and sample message exchanges.)

There are two types of messages flowing between the POS device and Simplify:

• Link-level messages

• Data-level messages

Data-level messages are described under Message Details. Link-level messaging is as follows:

The Link-level Response between the POS device and Simplify provides positive acknowledgement to a message. All messages result in a Link-level Response:

• An ACK (hex 06) is a positive acknowledgement to a received message. It indicates to the sending station that the message was correctly received, including proper message format and a successful LRC check. If the sending station does not receive an ACK within a parameterized amount of time, it must retransmit the previous message. If the retransmission is repeated a parameterized number of times for the same message and an ACK is not received, communication with the device is assumed to be lost and the proper actions are to be taken by the sending station.

• A NAK (hex 15) is a negative acknowledgement to a received message. It indicates to the sending station that some data was received but it was not received correctly. The reasons for a NAK include invalid format or failed LRC check. If the sending station receives a NAK response to a message, it should re-transmit the previous message. If a NAK continues to be received after a parameterized number of retransmissions, communications with the other device is assumed to be lost and the proper actions are to be taken by the sending station.

Note: The following values are configurable parameters in Simplify (it is suggested they should also be configurable parameters in the POS device as well):

• Number of Retries – a default value of 3
• Timeout Waiting for ACK / NAK – a default value of 3 seconds.

Sample Link Level Exchanges (Serial and USB emulating Serial)

Normally the POS and Simplify respond to each message received with an ACK (followed by the response message, if any).

If a corrupted message (bad LRC) is received, the response is a NAK. The POS device should attempt to transmit the message a parameterized number of times before assuming communications are lost.

PPP under RS-232 (Serial)

Simplify supports PPP (Point to Point Protocol) communications over RS-232. Using this protocol for the transport layer allows customers to communicate via TCP/IP over a RS-232 physical link.

The Simplify PIN Pad will be the PPP client and communicate with a PPP server on the customer network. Elavon will set the PIN Pad to receive the following data from the PPP server: (1) A host IP address to use for TCP/IP communications between the PIN Pad and Fusebox. (2) A HEM/IngEstate server address to use for TCP/IP communications between the PIN Pad and HEM/IngEstate.

There will be three TCP/IP sockets:

• One socket is from the POS to Simplify. The POS will be the socket client and Simplify will be the socket server.
• Another socket is from Simplify to Fusebox. FuseBox will be the socket server and Simplify will be the socket client. This socket is non-persistent (as usual) and is secured by TLS 1.2.
• Another socket is from Simplify to the HEM/IngEstate server. HEM/IngEstate will be the socket server and Simplify will be the socket client.

Apart from interaction with the PPP server, Simplify TCP/IP communications under PPP will follow the usual Simplify TCP/IP rules.

Recovery after Timeout Flow

Simplify attempts to transmit a message a parameterized number of times before assuming comm is lost.

The message flow is bi-directional. The POS device or Simplify can initiate a message. In order to avoid timeouts and retransmissions between the POS device and Simplify, each endpoint (POS device or Simplify) should read an incoming message, calculate the LRC (see Message and Communications Protocols), and immediately respond with an ACK or NAK.

** Recommended configuration for timeout on ACK is at least 3 seconds.

Exception to Timeout/Recovery Rules

After a timeout on a non-critical message, Simplify does not expect an ACK and will not retry the message. Sending an ACK for a non-critical message will not cause any issue. The following messages are considered non-critical, with the default exceptions noted:

The list of Status Identifiers for which a Status Message must be ACK’d is configurable. Please consult your Elavon representative for more information.

The message flow without an ACK is shown below. If a Status Message is configured for no ACK, Simplify is ready for the next message after sending the Status message.

LRC Calculation

Message data is preceded by an STX and followed by an EOT, ETX and LRC (Longitudinal Redundancy Checksum). The LRC is a 1 byte value calculated from the data, EOT and ETX (STX not included), as follows:

    1.	 
    2.	BYTE GetLRC(BYTE* pbData, //[in] data buffer including 
    3.	                          //termination character (ETB/ETX/EOT)
    4.	int iCount)               //[in] size of data in bytes including
    5.	                          //termination character
    6.  { 
    7.	    BYTE chLRC = 0;
    8.	    while(iCount > 0)
    12.	    {
    10.	       chLRC ^= *pbData++;
    11.	       iCount--;
    12.	    }
    13.	    return chLRC;
    14.	}

Routing Fusebox Messaging through the POS

Not supported in Canada. Simplify supports routing Simplify-Fusebox messaging via the POS, using the same connection (Ethernet, RS232 etc.) as used for POS-Simplify messaging. The POS forwards the Simplify request to Fusebox and forwards the Fusebox response to Simplify. The POS must manage the certificate for the socket connection to Fusebox.

For requests from Simplify to the POS and responses from the POS to Simplify, a header attached to the message indicates forwarding, FBREQ: for the request and FBRSP: for the response. This header immediately precedes the first message field (no CR/LF). For example:

• FBREQ:0001,02

Exception: If the POS cannot connect to Fusebox, the response from the POS contains the header FBERR: For example:

• FBERR:0001,02

Points to Consider

• Elavon recommends turning off status message 1 (in parm.fil).

• The POS can use the request from Simplify as the starting point to wait for a response (before timing out).

Offline Processing

If POS Routing is enabled, communication errors on the request from the POS to Fusebox can be handled as follows:

• If the POS does not receive a response from Fusebox, it allows Simplify to time out (no response sent to Simplify).

• If the POS cannot connect to Fusebox, it echoes the request from Simplify except for the header, which is FBERR:

In either case, further processing is as described under POS SAF Processing (if enabled) and Inquiry Message (except any required Fusebox messaging uses POS routing). I.e. if POS SAF is enabled and the transaction is SAF-eligible, Simplify sends a Stand-in Response to the POS (API 1010 = “*SLR STAND-IN.”) containing the data needed for the POS to perform Stand-in and SAF processing; else Simplify sends a decline.

The message flow for an offline Sale transaction processed using POS Routing can be summarized as follows:

Simplify processes a Sale request from the POS and sends it to Fusebox via the POS with a FBREQ: header. Offline processing by Simplify occurs under either of the following circumstances:

• If the POS cannot open a socket to Fusebox , it echoes the request back to Simplify with a FBERR: header.
• If the POS times out waiting for a response from Fusebox, it lets Simplify time out.

In either case:

• If Stand-in is enabled and the transaction is SAF-eligible, Simplify returns “*SLR STAND-IN.” in API 1010, together with the data required for the POS to perform Stand-in.
  • If Stand-in is performed, Inquiry request meesages for the transaction sent from the POS to Simplify will be routed to Fusebox through the POS with FBREQ: and FBRSP: headers, and similarly for the Inquiry response.
    • If the Inquiry response from Simplify indicates transaction not found, the POS re-sends the Sale (as a Forced transaction) which will be routed as above.
    • If found, POS is done.
• Else, Simplify declines the transaction with a comm error.
  • In this case, or if the POS declines the transaction, Inquiries for the transaction will be routed as described above.
    • If the Inquiry response from Simplify indicates transaction found, the POS sends a Void request, which will be routed as described above, i.e. with FBREQ: and FBRSP: headers, and similarly for the Void response.
    • If transaction not found, POS is done.
• For timeouts on Voids and Inquiries, an Inquiry will need to be sent (or re-sent).

Implementing TLS 1.2 to Simplify

Introduction

TCP/IP Socket communication between the POS and Simplify can be implemented with or without SSL security layer. Although there is no PCI data exchanged between the POS and Simplify, some implementations would like to have the added security by implementing SSL. TLS 1.2 is the preferred implementation for SSL encryption. This section serves as a guide in the implementation of TLS 1.2.

Simplify Communication Diagram

Below is the overview of SSL Socket Communication implemented by Simplify. No PCI-sensitive data is transmitted between the POS and Simplify.

Simplify obtains account data from the PIN Pad, and sends the encrypted PCI-sensitive data with the transaction to Fusebox. The Simplify response to the POS does not contain any PCI-sensitive data. In the scenario diagrammed, all messages are sent by TCP/IP and encrypted using TLS 1.2.

TLS 1.2 Guidelines

The following guidelines are relevant for implementing TLS 1.2 on Simplify systems:

1. Socket connection between the POS and Simplify can be configured with or without SSL Encryption.

2. Simplify supports the industry accepted standard, TLS 1.2.

3. There are 2 types of Simplify implementations:

   • Non-Pay at the Table - Simplify is the socket server to the POS.
   • Pay at the Table - Simplify is the socket client to the POS.

4. Open SSL is used to implement TLS 1.2. Please refer to the Open SSL documentation for details.

5. There are 2 types of certificates supported:

   • Self-Signed Certificate.
   • Certificate issued by a Certificate Authority.

   Since each Simplify device needs a certificate,Elavon recommends the use of the Self Signed Certificate. Elavon can supply the POS provider with an Elavon-created certificate, or the merchant can opt to supply Elavon with its own Self-Signed Certificate.

6. Please refer to the Open SSL on how to create a Self-Signed Certificate.

7. Cipher groups (suites) supported by Simplify are documented in the Download Configuration and Troubleshooting Guide under “Terminal Maintenance”.

8. Since Self Signed certificate is used, SSL will not verify the IP address of the server.