API Message Format

Input requests and output responses are formatted using the following components:

FieldNo - The 4-digit numeric code (0001, for example)

FieldData - The data being sent or received by the Elavon Gateway application. The data cannot contain tab characters and must meet the validation requirements (data type and maximum field length) defined by the Elavon Gateway message.

LineTerminator - This hexadecimal character is required to terminate the line. 

• Line feed (xOA) and a carriage return (0x0D) for Windows
• Line feed (0x0A) for UNIX.

API Message Format Overview

Building Input Requests

The following rules help ensure that your POS application builds properly formatted input requests.

• Each line of the file should contain a separate field entry.
• Each line must contain at least a field number, a comma, field data, and a line terminator (in that order).
• The input request must not have any additional blank lines or line terminator characters at the end of the input request.
• The required fields for a particular transaction type must be included in the input request, otherwise, the Elavon Gateway applications will return an error indicating the field is missing.
• All input request must conform to the attributes defined for that field including: length, type, and acceptable values as outlined in this guide and associated industry and payment method guides.
• Output fields from the processor must be “re-presented” in a subsequent transaction exactly as they were received (example: do not justify, zero-fill, pad with spaces, etc.)

XML Best Practices

To ensure XML document inputs are valid and well-formed:

• Each XML document begins with the XML version tag and encoding.
• All documents consumed by Fusebox are forced to Unicode Translation Format (UTF)-8 encoding of the Unicode character set.

The next line identifies the type of XML document we are dealing with. In this case:

• Follows 3C XML Schema rules
• URL of the online schema-instance
• No namespaces

The next line indicates that this batch of transactions is for authorization. The use of Prior Authorizations (Transaction Type 07) does not require that this line be changed.

An XML file might contain:

• One or more (1 to n) transactions, and all transaction data is within the <Transaction></Transaction> start and end tags.
• A limit of 50 transactions are allowed inside a single XML DOC.
• Each transaction must be enclosed in a <Transaction></Transaction> tag.

The following example shows the coding as explained above.

XML Document coding example:

<?xml version="1.0" encoding="UTF-8"?>
<!--Copyright Elavon., 2009 -->
<ProtoBase_Transaction\_Batch
xmlns:xsi="<http://www.w3.org/2001/XMLSchema-instance>"
xsi:noNamespaceSchemaLocation="<http://www.protobase.com/XML/PBAPI1.xsd>">
<Settlement_Batch>false</Settlement_Batch>
<Transaction>
<API_Field>
<Field_Number>0001</Field_Number> 
<Field_Value>1</Field_Value>
</API_Field>
<API_Field>
<Field_Number>0002<Field_Number>
<Field_Value>30.00<Field_Value>
</API_Field>
<API_Field>
<Field_Number>0003</Field_Number>
<Field_Value>4012XXXXXXXX0001\</Field_Value>
</API_Field>
<API_Field>
<Field_Number>0004</Field_Number>
<Field_Value>1020</Field_Value>
</API_Field>
<API_Field>
<Field_Number>0007</Field_Number>
<Field_Value>323456</Field_Value>
</API_Field>
</Transaction>
</ProtoBase_Transaction_Batch>

Sending Input Requests

When the input request is ready to send to the Elavon Gateway applications:

• Transmit the input request information to the Elavon Gateway via TCP/IP over TLS 1.2 or XML via an HTTPS Post.
  • Fusebox utilizes redundant IP endpoints with Domain Name System (DNS). 
• All applications must be coded to Fusebox with a URL when using the public Internet.
  • If not coded, in the event of a switch failure, failover is not available.
• Discuss the available private network options with a Solution Engineer or Gateway Integration Analyst.

Fusebox supports the following connectivity options with the Elavon Gateway message:

Elavon Gateway Message over the Internet

• Extensible Markup Language (XML) with SSL or an HTTPS: Post
• In compliance with industry standards, and to protect our clients, all applications are required to support TLS 1.2 protocol and SHA-2 certificates in all transmissions to our host. 
• POS terminals operating on lower level TLS protocols or SSL are required to update their communication routines as part of the development effort to communicate with the Fusebox gateway.

Elavon Gateway Message over a Trusted Network

• TCP/IP with Transport Layer Security or Secure Sockets Layer (TLS/SSL)
• TCP/IP over a trusted network
• TCP/IP with TLS/SSL
• XML over a trusted network
• XML with SSL

TCP/IP Communication using Elavon Gateway Message Method

• Fusebox only responds using UNIX version LF (0x0A) EOL characters no matter which type was originally sent to Fusebox.

• All standard input and response APIs are transmitted with the addition of an EOT (End of Transmission, ASCII hex 0x04), to the end of the last record.

  • Connection remains established until the server sends the response and terminates it with an EOT at the end of the last record.
  • Server closes the TCP/IP connection after response is sent.
  • Client initiates closing the server connection so that can handle new incoming requests more quickly.
  • Client can close its connection any time after receiving the response message.

• Multiple APIs can be sent in a single message, with a RS (record separator ASCII hex 0x1E) between each API and an EOT at the end of the last record.

  • Your code must match the responses to the requests because the records may not be returned in the same order.

• Fusebox also responds to a persistent TCP connection.

  • The process is the same as described above, other than the client does not need to close its connection after receiving the response message.
  • The next request can be sent over the existing TCP socket, using the same EOT/RS logic.
  • Idle socket timeout is 600 seconds. If the timing between transactions on an open persistent socket will exceed that window, we recommend sending a Heartbeat Transaction Type (73).

Cipher groups

Fusebox supports the following cipher groups:

• TLS1-AES-256-CBC-SHA
• TLS1-AES-128-CBC-SHA
• TLS1-DHE-DSS-RC4-SHA
• TLS1-DHE-DSS-AES-256-CBC-SHA
• TLS1-DHE-DSS-AES-128-CBC-SHA
• TLS1-DHE-RSA-AES-256-CBC-SHA
• TLS1-DHE-RSA-AES-128-CBC-SHA

The Elavon Gateway message passes information between your POS application and Elavon Gateway applications through input requests and output responses. This allows the capture of data requirements for every TPP supported by the Elavon Gateway applications.

For example, on a basic credit card authorization transaction, the input request provided by your POS application is the same regardless of the TPP. The output responses are also similar.