Handshake program implementation

The Gateway handshake request and response messages are implemented in XML. The messages consist of a header and an optional payload. When there is no payload for the outbound handshake response message, Gateway Server uses the unitOfWork field to match the response to the outbound handshake request.

Table 1 and Table 2 describe the fields required by the handshake messages.

Table 1. Header for the handshake messages
Field name Example value Description
msgDesc Service_Request, Service_Response The description of the message.
msgType Payments_Director_Handshake_Request, Payments_Director_Handshake_Response The type of the message. The options are:
  • Payments_Director_Handshake_Request
  • Payments_Director_Handshake_Response
version   The version of the handshake protocol used for this message.
messageTime 2008-09-10T16:52:47Z The date and time that the message was sent.
sourceId IBM_Payments_Director_Gateway, DTM This field is the ID of the message sender or the name of the sending system.
destinationId DTM, IBM_Payments_Director_Gateway This field is the ID of the message receiver or the name of the receiving system.
errorCode 0 Error codes are defined by the application that creates the handshake response. The error code must be an integer and should be zero if there is no error.
Note: This field is required for the handshake response message.
errorMessage   Error messages are defined by the application that creates the handshake response.
unitOfWork 1024 A unique tracking number for the handshake transaction.
Table 2. Payload for the handshake messages
Field name Contained by element Example value Description
fileDetails payload <fileDetails type="data"> The payload has one or more fileDetails elements that can contain information about each of the files that are sent with a transmission. The type attribute of the fileDetails element indicates the type of the file that its fields are describing. The values for the type attribute are:
  • data - the data file for the transmission
  • trigger - the Gateway trigger file for the transmission
  • route - the Gateway routing file for the transmission
name fileDetails filename.dat This field contains only the file name of the file.
fullName fileDetails C:\gateway\cmd\..\outProcessing\ filename.dat This field contains the file name with its full path.
expectedBy fileDetails 2010-07-08T12:01:23.456-05:00 The date and time by which the transmission is expected. This field must be in the dateTime format that is in the XSD file. The dateTime format is YYYY-MM-DDThh:mm:ss.SSS, where:
YYYY
Is the four digit year
MM
Is the two digit month
DD
Is the two digit day
T
Indicates the start of the required time section
hh
Is the hour
mm
Is the minutes
ss
Is the seconds
.SSS
Is the thousandths of a second
Note: All of the components are required for this field.
The time zone may be specified as UTC or as an offset from UTC. To specify UTC time, add a Z after the time. To specify an offset from UTC, add a positive or negative time after the time. Some examples of time zones are:
  • UTC: 2020-07-30T09:30:10Z
  • Offset from UTC: 2020-07-30T09:30:10-05:00
  • Offset from UTC: 2020-07-30T09:30:10+05:00
itemCount fileDetails 69 The number of transactions in the transmission. For a NACHA transmission type, this field is the sum of the debit item count, credit item count, and addenda record count.

This field is required for handshake request messages.
itemAmount fileDetails 200000 The total amount of all of the transactions in the transmission.
Providing values for at least one of the following field combinations is required for handshake request messages:
  • itemAmount
  • totalCreditAmount and totalDebitAmount
totalCreditAmount fileDetails 300000 The total amount of all of the credit transactions in the transmission.
Providing values for at least one of the following field combinations is required for handshake request messages:
  • itemAmount
  • totalCreditAmount and totalDebitAmount
totalDebitAmount fileDetails 100000 The total amount of all of the debit transactions in the transmission.
Providing values for at least one of the following field combinations is required for handshake request messages:
  • itemAmount
  • totalCreditAmount and totalDebitAmount
customerUniqueId payload or fileDetails customId_3333 A unique ID from the external client. When providing the customer unique ID in an inbound handshake request, the external client must use the same customer unique ID in the handshake request and the inbound routing file for the transmission. For an outbound handshake response, the value of the customer unique ID is stored with the transmission in the FTM database.
transmissionId fileDetails 49082 The ID of the transmission. For an inbound handshake response message, the transmission ID is the batch group ID. For an outbound handshake request message, the transmission ID is the outbound batch group ID.
businessDate fileDetails 20170320 The business date of the first batch (ICL) in the transmission.
type fileDetails ICL, CIFF The type of the transmission. For ACH, the type is NACHA.