Ingenico Developer Guide 2.03.024-028
Ingenico Download Configuration and Troubleshooting Guide 2.03.024-028
Telium Developer Guide 2.02.021
Verifone Developer Guide 2.19
Verifone Download Configuration and Troubleshooting Guide 2.19
Verifone Guides 2.18
Implementing TLS 1.2 to Simplify
Field 11 (User Data)
Field 11 is defined by the Gateway Interface Specification as a user-defined field with a variable length (up to a maximum of 512 characters).
Structure of Field
For added flexibility, this field contains two data areas, a Command Area for non-tokenized data and a Token Area for tokenized data ("TAG Length Data Structure"). These data areas are used as follows (see below for details):
The Command Area contains subfields required in the request. Some or all of these subfields may be echoed in the response. In Non-Financial Messages, the Command Area in the response may contain a Completion Code indicating the outcome of the request.
The Token Area is informational. It can be used to inform the POS of error conditions and/or Simplify version data.
- Exception: In the Quick Chip (36-40) Message, data is required in both the Command and Token areas of the request.
The generic format of field 11 is as follows:
|Command Area||The format of fields in the Command Area depends on the Transaction Type (and Message Type for Transaction Type = 36). The Maximum Length of this area is currently 11 characters.||0||VAR|
|Field Separator||The character ‘?’ is used to separate the Command Area from the Token Area||VAR||1|
|Token Area||The Token Area contains Tokenized fields in the format “TLLDDD…” where
T = Token
LL = Length of Data
DDD… = Data (Length = LL)
The Command Area will be discussed below, followed by the Token Area
As shown in the following tables, the use of the Command Area can vary by Tran Type and (for Non-Financial Messages) by Message Type. Since the use of this field for Financial Messages is totally distinct from that for Non-Financial Messages, the following discussion will be broken down by these two categories.
Command Area - Financial Messages
Depending on Tran Type, the following subfields may be used in the Command Area of field 11 for Financial Messages.
|1-3||Switch Timeout Value||Defines host timeout value used by Simplify|
|4||Offline Response||Set to “Y” on Inquiry Request to ensure correct offline processing.|
|4-5||Auto Signature Control||Can be used to ovrride configured Auto Sigature settings|
The following table shows supported Command Area subfields for each defined Financial Message Type:
Field 11 Command Area subfields are used in Financial messages as follows:
Switch Timeout Value -- Three-digit field (right-justified / zero-filled) controls how long (in seconds) Simplify will wait for a response from Fusebox.error_outline
The length of this timeout value must be shorter than the POS timeout value.
Auto Signature Control -- Two-byte field that can be used to override auto signature configuration on a per transaction basis. The use of this field is optional and must be enabled under configuration. Use as follows:
Send S0 to suppress auto signature for the transaction regardless of configuration settings. (No signature processing will occur unless a Signature Request is received.)
Send S1 to force auto signature for the transaction regardless of configuration settings.
If blank, configured settings will determine whether auto signature processing occurs.
For additional information on auto signature,see Chapter 9.
Offline Response –- Set to “Y” to ensure that an offline Inquiry Response is sent to POS when an Inquiry Request does not receive a response from the host.
Command Area - Non-Financial Messages
The purpose of a Non-Financial Message (Tran Type 36) is defined by its Message Type (field 11 bytes 1-2). The structure of the Command Area for field 11 on a Non-Financial Message can vary depending on the Message Type (bytes 1-2), but the following subfields are typical:
|1-2||Message Type||Defines purpose of message.|
|3-5||Transaction Sequence Number||POS transaction sequence number.|
|6-8||Screen ID||Used in request to define PIN Pad screen to be displayed (may be blank or not used).|
|9-11||Completion Code||Used in response to inform POS of request outcome.|
Variations from the above structure are illustrated in the following table showing supported Command Area subfields for each defined Message Type. Except where indicated, the Command Area in the response echoes the request.
Note concerning the following Non-Financial Message Types:
Message Types 08, 09, 13, 16-21 -- These values are reserved for future use.
Message Type 14 (Informational Prompting) -- The fields shown above are followed by Version and Build Information (preceded by a “?”). For Tag 013, the Timeout field (in the request) is not used.
Message Type 15 (System Command) -- Completion Code and Update Timing not used for Reboot command.
Message Type 40 (Quick Chip Message) -- Data is also required in the Token Area (Q token).
Field 11 Command Area subfields are used in Non-Financial messages as follows:
Message Type -- Two-digit field used along with the Tran Type to identify the purpose of the message. Always present for Tran Type = 36.
Transaction Sequence Number -- Three-byte field containing POS transaction sequence number. This field is echoed back in the response. Always present for Tran Type = 36.
Screen ID -- Three-digit field in Signature Request used to indicate which screen should be displayed when prompting for the customer's signature. This field is echoed back in Signature Response. (Currently supported values are 001 and 002.) This field is also present in the Informational Prompt request and response messages, but is not used.
Completion Code -- Three-digit field in Signature, Informational Prompt or Quick Chip response indicating the outcome of the request.
|004||DONE/ACCEPT key pressed with Signature data present|
|006||ABORT/CANCEL key pressed twice with no detectable signature|
|008||Signature entry aborted by Simplify|
|009||Signature entry aborted due to memory being exceeded|
|099||Customer pressed CANCEL after starting to sign. (NA 006 will be sent if cannot detect signature)|
|100||Transaction not allowed for device.
PIN Pad is currently busy.
For signature capture: Unable to create sigcap object or signature too small two times.
In Quick Chip response: error (e.g. Quick Chip not enabled).
|111||In System Command (Graphics Update) response:
Invalid sequence number. Update aborted.
|112||In System Command (Graphics Update) response:
Other error during download process. Update aborted.
|113||In System Command (Graphics Update) response:
Error during graphics conversion process. Update aborted.
|131||In Quick Chip response: Customer pressed Cancel.|
|132||In Quick Chip response: Bad Card Type|
|133||In Quick Chip response: Transaction not allowed.|
|200||EMV card still inserted|
Version Build Info -- Simplify version and build information.
Timeout -- Screen timeout in seconds. (000=No timeout)
Command – System command from POS to Simplify. Currently supported commands:
|001||PIN Pad reboot|
Update Timing – 0 = Update after next reboot (not currently supported). 1 = Update when PIN Pad goes to Closed state.
Status Identifier -- Three-digit transaction status code sent from Simplify to POS in Status Messages. A table included in a Simplify parameter file indicates which Status Identifiers are enabled. The following Status Identifiers are currently defined:
|Status Identifier||Status Message|
|001||Processing Please Wait|
|005||Enter Tender Type (Debit / Credit)|
|007||Enter Account Number|
|008||Enter Expiration Date|
|010||Enter ZIP Code (AVS Data)|
|011||Cash Back Other|
|012 – 016||[Reserved]|
|017||EMV AID list|
|019||EMV Account Type Selection|
|021||EMV card has been removed|
|022||Swiped not allowed, must use chip|
|024||Waiting for Mifare Tap|
Sample Field 11
The following sample of field 11 is for a Signature Response message sent in response to a Signature Request:
This value is broken down as follows:
|1-2||02||Message Type 02 – Signature Response|
|3-5||555||POS Transaction sequence number.|
|6-8||001||Screen ID (Echoed from Signature Request message)|
|9-11||004||Completion Code. 004 = DONE/ACCEPT key pressed with signature data present.|
Defined Tokens for the Token Area are as follows:
|V||Simplify Version||Simplify response to POS||10|
|S||Identifies the Source Routine of the Error||Simplify error response to POS||40|
|R||Return code from Source Routing||Simplify error response to POS||20|
|E||Actual Error if different from ‘R’||Simplify error response to POS||20|
|Q||Transaction Type and Tender Type
(data is optional)
|POS Quick Chip request to Simplify, echoed in response||20|
With the exception of the Q token, the above tokens are for informational purposes only.
The Q token must be present in order for Simplify to approve a Quick Chip (36-40) request. The format of the Q token is as follows:
- Q = Quick chip token
aa = Length of the following data (including field separators)
bb = Optional Transaction type (01=Auth, 02=Sale, 09=Refund)
FS = Field separator (1 byte)
ccc = Optional Tender type (e.g. 010=Credit, 030=Debit)
FS = Field separator (1 byte)
A sample Quick Chip request, showing the Command Area, '?' separator and Token Area for field 11 is as follows:
This request is for a Sale (=02) transaction. (Tender Type not specified.)