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.
Control Characters are defined as follows:
<CR> = (0x0D) 1 byte, hex D
<LF> = (0x0A) 1 byte, hex A
EOT = (0x04) 1 byte, hex 4
Sample messages shown in this document do not show the control characters.
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 (using the same protocol as configured for POS messaging). See Appendix G - Routing Fusebox Messaging through the POS for details.
TCP/IP communications between the POS and Simplify can be by wired ethernet, Wifi or Bluetooth transport to the 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)Appendix B - Simplify Serial Communication Protocol describes the Simplify RS-232 communication protocol.
Simplify RS-232 communication could optionally be over USB emulating RS-232.
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.
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:
Telium 2 terminals: ENDPOINT_OUT (0x04) and ENDPOINT_IN (0x85).
Tetra terminals: ENDPOINT_OUT (0x02) and ENDPOINT_IN (0x81).
The endpoint information can be obtained from a Windows utility (e.g. the Simplify POS simulator).
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 (see next page) shows the model name, the VID and the PID for each supported hardware model:
|Lane/7000||0x0B00||0x6780||Ingenico Lane 7000||HID|
If the VID and PID is not on the above list, they can be obtained by the following procedure:
To obtain the VID and PID from a Window PC:
Connect the PIN Pad to the PC. Open the “Device Manager”, look for “Human Interface Devices”.
Under “Human Interface Devices”, Right-click on the “HID-compliant device” or “USB Input Device”, select “Properties”. The properties dialog box will be displayed.
Select the “Details” tab on the Properties dialog box.
Open the “Property” drop-down list and select “Hardware IDs”.
In the “Value” text box, look for string “VID_0B00”.
Next to the “VID_0B00”, you will find the “PID” value in the format of “PID_xxxx”.
If the VID is not “0B00”, it is not an Ingenico device. Go to Step 2 and choose another device.