Simplify-Controlled Field Definitions
On this page:
This page describes the following fields whose definition is controlled by Simplify:
Since Fusebox does not modify these fields (and in some cases, does not receive them), they allow the POS and Simplify to communicate with each other with no concern for how Fusebox might affect the data.
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 Allow Pre-Tendering (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:
Subfield Name | Description | Offset | Length |
---|---|---|---|
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:
| VAR | VAR |
The Command Area will be discussed below, followed by the Token Area
Command 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.
Bytes | Subfield Name | Use |
---|---|---|
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 (Tran Type):
Tran Type | Message Name | Bytes 1-3 | Bytes 4-5 |
---|---|---|---|
01 | Auth Only Message | Switch Timeout Value (all financial messages) | Auto Signature Control |
02 | Sale Message | Auto Signature Control | |
07 | Prior Auth Sale Message | ||
09 | Return Message | Auto Signature Control | |
13 | Batch Close Message | ||
14 | Batch Inquiry Message | ||
22 | Inquiry Message | Offline Response (byte 4 only) | |
24 | Balance Inquiry Message | ||
37 | Token Request Message | ||
61 | Full Auth Reversal Message | ||
75 | Incremental Auth Message | ||
76 | Auth Reversal Message |
Command Area subfields (Financial Messages)
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.
Important 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 Auto Signature.
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:
Bytes | Subfield Name | Use |
---|---|---|
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. |
The following table shows supported Command Area subfields for each defined Non-Financial message (Message Type). Except where indicated, the Command Area in the response echoes the request. ** means see note below.
Tran Type | Message Name | bytes 1-2 (Message Type) | bytes 3-5 | bytes 6-8 | bytes 9-11 |
---|---|---|---|---|---|
36 (all messages) | Signature Request | 01 | Transaction Sequence # (all messages unless stated) | Screen ID | |
Signature Response | 02 | Screen ID | Completion Code | ||
Version Number Inquiry Request/Response ** | 06 | ||||
Initiate HEM/IngEstate Request/Response | 07 | ||||
Scrolling Receipt Request | 10 | ||||
Scrolling Receipt Stop | 11 | ||||
Exit Reversal Mode | 12 | ||||
SAF Done Request/Response | 13 | ||||
Informational Prompt Request/Response ** | 14 | Screen ID (not used) | Timeout/ Completion Code | ||
System Command Request/Response | 15 | Command | |||
Allow Pre-Tendering Request/Response ** | 40 | Completion Code (only in response) | |||
Print Request Message Request/Response | 45 | (not sent) | |||
Status Inquiry | 51 | Status Identifier |
** Note concerning the following Non-Financial Message Types:
Message Type 06 (Version Number Inquiry) – Transaction Sequence Number is followed in the response by variable-length Version and Build Information (preceded by a “?”).
Message Type 14 (Informational Prompting) – Completion Code (response) is followed by variable-length Version and Build Information (preceded by a “?”). For Tag 013, the Timeout field (in the request) is not used.
Message Type 40 (Allow Pre-Tendering Message) – Data is also required in the Token Area (Q token).
Message Types 08, 09, 16-21 – These values are reserved for future use.
Command Area subfields (Non-Financial Messages)
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, Allow Pre-Tendering or Fast Graphics Download response indicating the outcome of the request. The following Completion Codes are currently defined:
Completion Code | Outcome |
---|---|
000 | Successful |
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 |
010 | Memory exhaustion (Signature response) |
099 | Customer pressed CANCEL after entering detectable Signature |
100 |
|
112 | In Fast Graphics Download response: Download error. |
113 | In Fast Graphics Download response: File error. |
131 | In Allow Pre-Tendering response: Customer pressed Cancel. |
132 | In Allow Pre-Tendering response: Bad Card Type |
133 | In Allow Pre-Tendering response: Transaction not allowed. |
200 | EMV card still inserted |
998 | Invalid format |
999 | Timeout |
Version Build Info – Simplify version and build information.
Timeout – Screen timeout in seconds. (000=No timeout)
Command – System command from POS to Simplify. The following commands are currently supported:
Command | Requested Action |
---|---|
001 | PIN Pad reboot |
- 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 | PIN Pad Status |
---|---|
001 | Processing Please Wait |
002 | Slide Card |
003 | Enter PIN |
004 | Amount OK |
005 | Enter Tender Type (Debit / Credit) |
006 | Cash Back |
007 | Enter Account Number |
008 | Enter Expiration Date |
009 | Enter CVV |
010 | Enter ZIP Code (AVS Data) |
011 | Cash Back Other |
012 – 016 | [Reserved] |
017 | EMV AID list |
018 | Language Selection |
019 | EMV Account Type Selection |
020 | Enter Tip |
021 | EMV card has been removed |
022 | Swiped not allowed, must use chip |
023 | EMV fallback |
024 | Waiting for Mifare Tap |
025 | Waiting for Cashier |
026 | Waiting for QR code |
Sample Field 11
The following sample of field 11 is for a Signature Response message sent in response to a Signature Request:
- 0011,02555001004
This value is broken down as follows:
Bytes | Subfield Value | Use |
---|---|---|
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. |
Token Area
Defined Tokens for the Token Area are as follows:
Token (Case Sensitive) | Description | Usage | Max Length |
---|---|---|---|
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 Allow Pre-Tendering request to Simplify, echoed in response | 20 |
With the exception of the Q token, the above tokens are for informational purposes only.
Q token
The Q token must be present in order for Simplify to approve an Allow Pre-Tendering (36-40) request. The format of the Q token is as follows:
QaabbFScccFS, where:
Q = Allow Pre-Tendering 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 Allow Pre-Tendering request, showing the Command Area, ‘?’ separator and Token Area for field 11 is as follows:
API Field #, Value | Description |
---|---|
0001,36 | Transaction Type |
0011,40001000000?Q0402FSFS | User Data |
This request is for a Sale (=02) transaction. (Tender Type not specified.)
Field 5001 (Non-Financial Data)
Field 5001 is used in the following types of messages as follows:
- In Non-Financial Messages (Tran Type 36):
- Used in requests and/or responses for most Message Types:
- In request, used to define display or screen operation.
- In response, used to indicate outcome of requested operation. In Informational Prompting Messages (36-14), this field returns customer feedback.
- Details are message-specific. For more information, see the formats and sample messages given under Non-Financial Messages.
- Used in requests and/or responses for most Message Types:
- In Financial Responses:
- For auto signature-eligible transactions, Field 5001 is used in the financial response to inform the POS whether Simplify is performing auto signature processing for the transaction. For details, see Auto Signature.
- Simplify returns the time remaining (in seconds) till a PCI reboot in API 5001 Tag 400. (If the time is less than 5 minutes, the transaction will be declined with a communications error.)
- In Mifare Activation Response:
- The POS can activate Mifare tap by sending a request to Simplify with “M” or “m” in API 0003. For valid tap, Simplify will extract the UID, and send it to the POS in the response as token 300 in Field 5001 (no Fusebox message). E.g. 5001,300014042A18C25B6285
- In Sale, Auth, Return, Token Request and Balance Inquiry responses:
- If enabled in configuration, Simplify returns the first 8 digits of the PAN in API 5001 Tag 301.
Field 5070 (Simplify Load Information)
Field 5070 is used in financial responses and the Version Number Inquiry (36-06) Response to return information about the PIN Pad and its Simplify implementation. This includes the Simplify version number, other Simplify load information (e.g. parameter file version numbers, TMS Identifier, build number, patch level), and Device Serial Number data. The maximum size of this field is 256 bytes.
A current sample of this field is as follows:
5070,Merchant: Test01;Simplify: N-OG-2.03.12818;PARM: 2.28.1;TENDERDEF: 2.28.2;EMVPARM: EMVPARM-E4-2– ;TMS: 88802013;Package: 2.28.5;Full SN: 181052213011023907225277;Injected SN: ;Build: 28118-PatchN
Subfield Name | Current value | Meaning |
---|---|---|
Merchant | Test01 | Identifies implementation by merchant name. |
Simplify | N-OG-2.03.12818 | Simplify version number |
PARM | 2.28.1 | parm.fil parameter file version |
TENDERDEF | 2.28.2 | tenderdef.fil parameter file version |
EMVPARM | EMVPARM-E4-2– | emvparm.fil parameter file version |
TMS | 88802013 | TMS identifier of the PIN Pad |
Package | 2.28.5 | ID of package used to build current load |
Full SN | 181052213011023907225277 | Serial number shown on the back of the device |
Injected SN | Serial number injected during the KIA process | |
Build | 28118-PatchN | Version number, Build number, Patch level |
Field 5071 (Card/Cardholder Present?)
Field 5071 is used in financial requests from the POS to inform Simplify whether the card and cardholder were present for the transaction. This field is only used by Simplify to help set field 47, and is not sent to Fusebox. If sent in the request, this field will be echoed in the response.
Supported values are:
- 0=neither present (including all manual entry with cardholder not present)
- 1=both present
- 2=only cardholder present
If the value in 5071 is invalid or not present, Simplify will use a default value of 1. However Elavon recommends sending this field in all financial requests, using the value that reflects the actual transaction environment.
Field 5104 (Tip Prompting)
This section describes the use of API 5104 for non-Pay@Table systems on Tetra Attended devices. Note for other systems and devices:
- API 5104 is supported for Pay@Table, with somewhat different rules. See under API 5104 (Pay@Table) for details.
- The Self 4000 and Telium devices support tne functionalty described below with the following exceptions:
- The maximum number of supported percentages is three.
- Custom Tip amounts are not supported.
- Sending dollar amounts in API 5104 is not supported .
Supported Settings
- Define up to four Tip percentages or amounts.
- Set Tip flag.
- Define Tip prompting text.
See below under Usage for details.
Supported messages
- Financial requests (echoed in Simplify response).
Format
API 5104 can be used to prompt the customer to select from up to four suggested Tips. These can be defined in terms of Tip percentages or dollar amounts:
- To send percentages in this field, use the format aa;bb;cc;dd<FS>e<FS>f where:
- aa, bb, cc, dd = Tip percentages. (1 or 2 digits supported. Percentage sign is assumed.)
- e = Tip flag. (0=disable, 1=enable.)
- f = Tip prompting text. (Can include \n to indicate the start of an additional line of text.)
- To send amounts in this field, use the above format with the following modifications:
- If the value in a percentage subfield is preceded by a dollar sign (“$“), it will be interpreted as a dollar amount.
- There is no assumed decimal point. An amount will be treated as a whole dollar amount unless an explicit decimal point (“.“) is included. If more than 2 decimal places are sent, the amount will be rounded to the nearest cent.
- API 5104 also supports entry of a custom (user-selected) amount. If one of the percentage subfields is set to Cust_Tip, selecting the corresponding button on a Tip selection screen will display the custom Tip screen and prompt the customer to enter a Tip amount.
Note concerning the above:
- FS represents a 1 byte field separator between subfields (Hex 1C).
- Semi-colons (;) and field separators (FS) are required, even if some subfields are null.
Usage
Overrides configured Tip settings for the current transaction:
- Tip Flag
- 0 – No Tip prompting. Total transaction amount = Base amount (no tip).
- 1 – If Tip percentages are defined, a Tip selection screen will be displayed showing the percentages/corresponding Tip amounts. Else the custom Tip screen will be displayed.
- Tip Percentages
- Used if Tip Flag = 1. See further under Samples.
- Tip Prompting Text
- Replaces configured prompt on the Tip selection screen (if displayed) and the custom Tip screen (if displayed).
Samples
5104,15;18;20<FS>1<FS>Enter Tip
Simplify will display a Tip selection screen showing the requested Tip percentages and corresponding Tip amounts. Prompt will be “Enter Tip”.
5104,;;<FS>1
Simplify will go directly to the custom Tip screen. Configured prompting text will be used.
5104,0;15;18;Cust_Tip<FS>1
Simplify will display a Tip selection screen showing the requested Tip percentages and corresponding Tip amounts. Pressing the fourth button (verbiage configurable) will go to the custom Tip screen. Configured prompting text will be used.
5104, $5;$7.50;$10;<FS>1
Simplify will display a Tip selection screen showing the requested dollar amounts. Configured prompting text will be used.