Simplify Overview

On this page:

Simplify is Elavon’s PIN Pad-based application designed to process electronic payment transactions received from a Point of Sale (POS) or a Property Management System (PMS).

This document is a developer guide for customers interfacing their POS / PMS process to Simplify. It applies specifically to implementations that run Simplify on Verifone MX PIN Pads (MX915, MX 925), and send transactions to Elavon’s Fusebox host.

This document is reviewed for every application update and change to PCI P2PE requirements (at least annually) and updated as required.

See under Usage for conventions used in this document.

General Guidelines

POS development for Simplify should be based on the following set of principles:

1. PCI DSS Compliance: The customer is responsible for securely deleting the encrypted account data and making it unrecoverable after authorization using a method that supports PCI DSS secure delete standards (PCI DSS 3.0 Requirement 3.2).

2. The POS process should disregard any message that does not correspond with the POS state.

3. The POS process should compare the Transaction ID / Reference Number (field 7) in the request and response. If the response doesn’t match the request, the message should be discarded.

4. If multiple POS workstations can be associated with a single PIN Pad, Simplify assumes that the POS process ensures there is only one outstanding transaction per PIN Pad. (This situation can occur under TCP/IP.)

5. Simplify can return encrypted account data to allow Stand-in processing by the POS. See Stand-in Processing for more information.

6. For support purposes, Elavon strongly recommends that the POS logs all messages received from and sent to Simplify.

7. API fields in messages sent to the POS will not necessarily appear in order by field number. E.g. the following sequence of fields is possible:

   API Field #, Value	Description
   0001,36	Transaction Type
   5001,010003888	Non-Financial Data
   0011,14123010000?V102.18B01803	User Data

8. For API fields that are defined as variable length, the POS must be able to handle data of varying lengths.

9. Terminal maintenance and updates can be managed using the Verifone MX Downloader or POS commands. Elavon recommends testing this functionality during pilot.

10. Elavon uses Inquiry and Voids to recover from communication issues on Financial Messages. Please pay close attention when implementing Inquiry and Void logic.

11. Fields 13 (date) and 14 (time) are required in all financial requests.

12. To protect against EMV cards being left in the Simplify device, Simplify will not accept any message from the POS until the card is removed. An error message will be returned indicating that the card is still inserted.

13. If no response is received for a financial request, or if you need to start over for any reason, the POS should send a Cancel before sending another financial request.

Message and Communications Protocol

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

TCP/IP

TCP/IP communications between the POS and Simplify is by wired ethernet.

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

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 in Message Details This appendix describes the Link-level messaging.

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.

Sample Link Level Exchanges (Serial Communications 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 is received (bad LRC), the response is a NAK. The POS device should attempt to transmit the message a parameterized number of times before assuming communications are lost.

Recovery after Timeout Flow

Simplify will attempt to transmit a message a parameterized number of times before assuming communications is lost.

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 below), 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 exceptions noted:

The message flow without an ACK is shown below. If no ACK is expected, 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)
9.	        {
10.	          chLRC ^= *pbData++;
11.	          iCount--;
12.	          }
13.	        return chLRC;
14.	}

• previousRelease Notes
• nextMessage Details