Message and Communications Protocols
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. See below for sample messages.
The communications protocol between the POS process and Simplify is TCP/IP, or RS-232 (Serial), or PPP with TCP/IP over RS-232.
(0x0D) = <CR> 1 byte, hex D
(0x0A) = <LF> 1 byte, hex A
(0x04) = EOT 1 byte, hex 4
Simplify server/client configuration for TCP/IP varies depending on whether the system supports Pay@Table.
For non-Pay@Table 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.
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. There can be multiple Pay@Table terminals for a single base. All terminals connected to the same base will have the same IP address, with the POS responsible for managing multiple sockets.
Simplify-POS messaging can use plain TCP/IP or TCP/IP with TLS 1.2. For Pay@Table Elavon will need to be given the certificate if encryption is used.
Note: If multiple POS workstations are associated with a single PIN Pad, Simplify assumes that the POS process ensures that there is only one outstanding transaction per PIN Pad.
- Appendix B describes the Simplify RS-232 communication protocol.
Simplify RS-232 communication could optionally be over USB emulating RS232.
Note: Sample messages shown in the remainder of this document do not show the control characters.
PPP over 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 RS232 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) An IngEstate server address to use for TCP/IP communications between the PIN Pad and 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 IngEstate server. 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.
HID USB Interface
HID USB is a protocol that allows for serial bidirectional data transfer in a manner similar to the serial protocol (as described in Appendix B), but using the USB link layer. This has some advantages over “regular” Serial; for example you don’t need to specify baud rate or stop bits, as these are not part of the USB link layer.
In general there are two ways an ECR can communicate using HID USB. The first is via a third-party driver; this software will hide the HID complexity and allow existing ECR software to work unmodified. However if a direct HID USB interface is preferred, additional steps must be taken to conform to the HID USB link layer data transfer requirements:
For Ingenico PIN Pads, the HID interface requires 32 byte frames, with the first byte being a Report ID and the next 31 bytes available for payload data. Extra bytes must always be padded with zeroes, as you can never transfer less or more than a full 32 byte frame. For frames going to the PIN Pad, the Report ID byte must be 2; when receiving data from the PIN Pad, you can expect a Report ID byte with a value of 1. Messages longer than 31 bytes must be transferred in multiple frames. The payload data must still start with STX and include ETX and LRC (same as for Visa2 transfers).
Messages received from the PIN Pad must also be filtered to skip over both the Report ID bytes (value = 1) and any extra padding bytes (value = 0) from the incoming data stream. This will allow the ECR to interpret messages received from the PIN Pad. Special care must be taken in locating the LRC byte when processing incoming data. It’s not necessarily the byte following the ETX, as that byte might be a Report ID. Also, the LRC byte can have any value (including 1) so it’s not sufficient to simply ignore a “1” byte after the ETX. The correct algorithm keeps track of how many bytes into the frame it is, identifying the Report ID byte by its position (i.e. at the start of the frame), not its value.
HID USB protocol also includes the concepts of Interface and Endpoint. In this implementation, there is only one Interface (0) and two endpoints, ENDPOINT_OUT (0x04) and ENDPOINT_IN (0x85).
To connect to a HID USB terminal, an application must know the Vendor ID and Product ID values. For Ingenico PIN Pads, the following table shows the model name, the VID and the PID for each supported hardware model: