EMV API Fields

Gateway EMV API Fields

EMV binary data must be translated to ASCII in order to be accepted by the Fusebox switch. The field sizes have been adjusted accordingly.

Field Name Length
Type
Description
0002 Transaction Amount 1-14
cents
Authorized Amount. EMV Tag 9F02
0013 Transaction Date 6
date
Terminal Transaction Date. EMV Tag 9A
0017 Cash Back 1-14
cents
Cashback / Other Amount - Optional. EMV Tag 9F03
0023 Account Type 2
numeric
Type of account used.
00=Checking (default) 01 = Savings 02 = Other, 03 = Credit
EMV Tag 5F57
0052 Transponder / Proximity Indicator 1
numeric
Indicator stating that a transponder or proximity device was used to originate the transaction. Valid values:
0 = no transponder
1 = transponder initiated transaction
2 = Proximity using VSDC rules
3 = Proximity using magstripe rules
4 = Chip / Smart Card
5 = Transponder equipped using magstripe or key entry
0054 POS Entry Mode 2
numeric
ISO POS Entry Mode values:
00-Unknown
01 – Manual / Key Entry
04 – OCR code read
05 – Integrated circuit card read - CVV data reliable (smart card)
07 – Contactless M/Chip or Visa Smart Card read
10 - Scanned MICR/check
79 – Chip Card capable – chip and magstripe read failed, fall back to manual
80 – Chip Card capable - unaltered track data read (used for EMV fall back to swipe)
82 – Contactless Mobile Commerce device
90 – Magnetic Stripe-CVV/CVC certified, unaltered Track Data (1 or 2) included in Authorization Request. Required to participate in PS/2000 or CPS/2000
91 – Contactless chip magnetic stripe read
95 – Integrated circuit card read - CVV data unreliable
85 – Internet (not an ISO value)
0055 PIN Capabilities 1
numeric
PIN Capabilities Flag of POS Entry Mode.
ISO specs, values:
0 – Unknown
1 – Can accept PIN
2 – Cannot accept PIN (Valid Value for Transponders)
8 – PIN Pad is down
9 - PIN verified by terminal device
0057 ICC Chip Condition Code 1
numeric
Required to support Fallback identification for EMV enabled POS. Provides information about magnetic-stripe read or manually-entered transactions for ICC enabled cards at EMV-capable terminals.
0 – ICC enabled card chip read
1 – ICC enabled card first magnetic stripe Fallback
2 – ICC enabled card subsequent magnetic stripe Fallback
3 – ICC enabled card manually entered Fallback.
0140 Terminal Currency Tri-graph 3
alpha
ISO alpha currency code of the terminal running at the merchant location
0141 Terminal Currency Code 3
numeric
ISO numeric currency code of the terminal running at the merchant location. Code defining the common currency used by the terminal in case the Transaction Currency Code is different from the Application Currency Code. EMV Tag 9F3C
0163 Cardholder Language Preference 2
alphanumeric
Alpha characters according to ISO 639 representing language indicated by cardholder or card data for transaction. EMV Tag 5F2D
0201 TIP 1-14
cents
Tip / Other Amount - Optional. EMV Tag 9F03
1300 Application Cryptogram 16
alphanumeric
Cryptogram returned by the ICC in response to the “Generate AC’ command. Used by the issuer to verify the request came from the card. EMV Tag 9F26
1301 Issuer Authentication Data 32
alphanumeric
Data sent to the ICC for online issuer authentication, used by the ICC to verify the response came from the issuer. EMV Tag 91
1302 Application Expiration Date 6
date
Date the application expires. Format YYMMDD. EMV Tag 5F24
1303 Cardholder Verification Method (CVM) Results 1-6
alphanumeric
Indicates the results of the last CVM performed. EMV Tag 9F34
1304 Device (IFD) Serial Number 8
alphanumeric
Unique and permanent serial number assigned to the IFD by the manufacturer. EMV Tag 9F1E
1305 Issuer Application Data 1-64
alphanumeric
Contains proprietary application data for transmission to the issuer in an online transaction. EMV Tag 9F10
1306 Terminal Capabilities 6
alphanumeric
Indicates the card data input, CVM and security capabilities of the terminal. EMV Tag 9F33
1307 Terminal Verification Result (TVR) 10
alphanumeric
A set of indicators from the terminal application risk analysis and cardholder verification. EMV Tag 95
1308 Pre-AC Generate Issuer Scripts 1-256
alphanumeric
Contains proprietary issuer data for transmission to the ICC before the second GENERATE AC command. EMV Tag 71
1309 Issuer Script Results 1-84
alphanumeric
Indicates the result of the terminal script processing. EMV Tag 9F5B
1310 Issuer Script Identifier 8
alphanumeric
Identification of the Issuer Script. EMV Tag 9F18
1311 Application Currency Code 3
numeric
Indicates the country of the ICC chip issuer. EMV Tag 9F42
1312 Terminal Country Code 3
numeric
Indicates the country of the terminal. EMV Tag 9F1A
1313 Application PAN Sequence Number 2
numeric
Identifies and differentiates cards with the same PAN. EMV Tag 5F34
1314 Dedicated File Name 10-32
alphanumeric
Identifies the name of the DF as described in ISO/IEC 7816-4. EMV Tag 84
1315 ICC Application Version Number 4
alphanumeric
Version number assigned by the payment system for the application. EMV Tag 9F08
1316 EMV Device ID 8
alphanumeric
Designates the unique location of a terminal at a merchant (aka Terminal Identification). EMV Tag 9F1C
1317 Terminal Application Version Number 4
alphanumeric
Version number assigned by the payment system for the application. EMV Tag 9F09
1318 Transaction Sequence Counter 1-8
numeric
Counter maintained by the terminal application that is incremented by one for each transaction. EMV Tag 9F41
1319 Application Interchange Profile 4
alphanumeric
Indicates the capabilities of the card to support specific functions in the application. EMV Tag 82
1320 Application Transaction Counter (ATC) 4
alphanumeric
Counter maintained by the application in the ICC (incrementing the ATC is managed by the ICC). EMV Tag 9F36
1321 Cryptogram Information Data 2
alphanumeric
Indicates the type of cryptogram and the actions to be performed by the terminal. EMV Tag 9F27
1322 Terminal Type 2
alphanumeric
Indicates the environment of the terminal, its communications capability, and its operational control. EMV Tag 9F35
1323 Unpredictable Number 8
alphanumeric
Value to provide variability and uniqueness to the generation of a cryptogram. EMV Tag 9F37
1325 ICC Application Identifier 6-32
alphanumeric
ICC AID - Identifies the application as described in ISO/IEC 7816-5. EMV Tag 4F
1326 ICC Application Preferred Name 1-16
alphanumeric
Preferred mnemonic associated with the AID. EMV Tag 9F12
1327 Application Label 1-16
alphanumeric
Mnemonic associated with the AID according to ISO/IEC 7816-5. EMV Tag 50
1328 Terminal Application Identifier 6-32
alphanumeric
Terminal AID - Identifies the application as described in ISO/IEC 7816-5.
RID is first 10 bytes of AID data. Terminal AID - Identifies the application as described in ISO/IEC 7816-5.
RID is first 10 bytes of AID data.
EMV Tag 9F06
1329 Default Issuer Action Code 10
alphanumeric
Specifies the issuer's conditions that cause a transaction to be rejected if it might have been approved online, but the terminal is unable to process the transaction online. EMV Tag 9F0D
1330 Denial Issuer Action Code 10
alphanumeric
Specifies the issuer's conditions that cause the denial of a transaction without attempt to go online. EMV Tag 9F0E
1331 Online Issuer Action Code 10
alphanumeric
Specifies the issuer's conditions that cause a transaction to go online. EMV Tag 9F0F
1332 Application Usage Control 4
alphanumeric
Indicates issuer's specified restrictions on the geographic usage and services allowed for the application. EMV Tag 9F07
1333 Last Host EMV Key Download 8
numeric
Indicates the date of the latest EMV Key Update in MMDDYYYY format. If this date changes in the response messages, it indicates a new download may be required.
1334 Transaction Status Information 4
alphanumeric
Indicates the functions performed in a transaction. EMV Tag 9B
1338 Smart Card Scheme 2
alphanumeric
Smart Card Scheme. EMV Tag DF04
1339 EMV Response Code 1-2
alphanumeric
EMV Response Code. EMV Tag 8A
1340 Extra EMV ISO TLV Data 1-685
alphanumeric
Use for extra EMV Tag data, without an Elavon Gateway API Field identified, in TLV format.
1343 Post-AC Generate Issuer Scripts 1-265
alphanumeric
Contains proprietary issuer data for transmission to the ICC after the second GENERATE AC command. EMV Tag 72
1345 ICC Form Factor Indicator 8
alphanumeric
Form Factor Indicator. EMV Tag 9F6E
1346 ICC Customer Data 1-64
alphanumeric
Customer Exclusive Data. EMV Tag 9F7C
1357 Transaction Currency Code 3
alphanumeric
Indicates the currency code of the transaction according to ISO 4217. Indicates the currency code of the transaction according to ISO 4217. EMV Tag 5F2A
1358 Cryptogram Tran Type 2
alphanumeric
EMV Transaction Type. EMV Tag 9C
1359 EMV CVM Verification Indicator 1
alphanumeric
Field to indicate to the POS the cardholder verification methods. Valid values are:
0 - Failed CVM
1 - Signature required
2 - PIN verified
3 - PIN verified and signature required
4 - Request for Signature CVM not parsed
1361 Issuer Country Code 3
alphanumeric
Issuer Country Code. EMV Tag 5F56
1378 EMV Approved Receipt Field List 1-256
alphanumeric
A delimited field containing the Elavon Gateway API fields required by the merchant’s TPP to be printed to meet the additional EMV receipt requirements.
1379 EMV Declined Receipt Field List 1-256
alphanumeric
A delimited field containing the Elavon Gateway API fields required by the merchant’s TPP to be printed to meet the additional EMV receipt requirements.
1380 POS Entry Indicator 1-20
alphanumeric
TPP specific POS Entry Mode text for receipts based on the value in Field 0054 and the TPP rules.

error_outline
note

Depending on the payment type, card type, transaction type, the Third Party Processor being interfaced with, and other factors, not all of these tags may be available on every transaction. The recommended best practice is for the EMV Payment Application to retrieve all of the EMV tag data available from the EMV Kernel and place the values into the appropriate API field. If an EMV tag is present with no existing API field identified, the data should be entered into API Field 1340 in TLV format.

Quickchip

Quickchip is a methodology of EMV processing that speeds up the check-out times at the Point of Sale and enhances the cardholder experience. Quick Chip allows cardholders to remove their card from the terminal device before the final transaction amount is determined or before the transaction approval process is fully completed. Benefits include reduced total transaction processing time and a shorter time the card is inserted into the terminal, which can improve the cardholder’s perceived wait time at check out.

Fusebox has been updated to support EMV Quick Chip transactions, allowing for early removal of an EMV card and while standard EMV processing continues afterwards. This eliminates the wait for final transaction amount, authorization response and post-authorization issuer script processing to complete before removing the card.

Two new gateway API fields have been added to accept a pre-determined (estimated) transaction amount and another amount (such as cashback or tip). Terminal Applications such as Simplify use estimated amounts during EMV cryptogram generation and will send these estimated amounts in the new fields. Values provided in these new fields, 1362 and 1363, will be mapped to EMV Tags 9F02 and 9F03 respectively in the processor message and settlement file.

POS applications will continue to send the final total transaction amount in API field 0002, final cashback in field 0017 or final tip amounts in field 0201 and 0202. Tip and Cashback fields are only required if applicable for that transaction.

Relevant API Fields for Quick Chip Transactions

API Field Number Field Name Description
0002 Transaction Amount Total financial amount of the transaction. It may or may not be different than the amount used to generate the EMV cryptogram, see API Field 1362.
0017 Cashback Amount Actual Cashback amount of the transaction. It may or may not be different than the “Other Amount” used to generate the EMV cryptogram. See API Field 1363.
0201 Tip Amount 1 Actual Tip amount of the transaction. It may or may not be different than the Other Amount used to generate the EMV cryptogram. See API Field 1363. Restaurant field only.
0202 Tip Amount 2 Additional Restaurant Industry Tip Field, see API field 0201.
1362 EMV Cryptogram Amount Estimated amount of the transaction used to generate the EMV cryptogram, it may or may not be different than the final transaction amount in API Field 0002.
1363 EMV Cryptogram Other Amount Estimated “Other” amount of the transaction used to generate the EMV cryptogram, it can contain an estimated Cashback amount or an estimated Total Tip amount. It may or may not be different than the final Cashback or Tip amounts in API Field 0017, 0201, and 202.

Contactless API fields

Depending on the electronic payment transaction type, various data fields must be stored in the application database. This section describes the API fields required to create the transaction input request and fields that will be returned in the output response.

API Field Number Field Name Description
0001 Transaction Type Must be included in all input API files. This 2-digit instruction determines what action Gateway products will perform with the data presented in the API input file.
0002 Transaction Amount The total amount of the purchase.
0003 Account Number Swiped data from the card reader. Only the cardholder’s account number will be passed back in the Output Response.
Swiped data should never be stored. Only the parsed account number should be stored.
0006 Auth Code Code returned from the card issuer or authorizing institution indicating an approved authorization request.
0007 Reference Number Unique number supplied by the POS to identify the transaction within a batch/processing period. This number should be unique within a settlement batch.
Important: Elavon does not recommend padding the Reference Number field (field 0007) with leading zeros. Should you choose to do so, be sure to store the value in your system as a String instead of an Integer. This will eliminate any potential discrepancies in how this field is presented in two-part transactions, and the chance of downgrades or fees is greatly reduced.
0009 Batch No. Incrementing number which identifies the batch number. A batch # may not be available under some processor specs. In this case, Fusebox will keep an internal # and present it in every output file.
0025 Business Date Used to control business date in Elavon software applications.
0032 Original Auth Date Date the original authorization transaction took place.
0033 Original Auth time Time the original authorization transaction took place.
0034 Authorization Characteristics Indicator Code that is used to track participation status of this transaction in interchange rate programs.
0037 Validation Code Computed value assigned by the card association (VISA, MasterCard, and so on) and used to verify data integrity between authorization and settlement.
0038 Reason Code Code assigned by some third party processors to track why a transaction was rated as it was.
0040 Compliance Data Contains the indicator returned by the issuing bank to indicate the result of the CVV2 (VISA), CVC2 (MasterCard) or CID (AMEX) verification.
0042 Compliance Data Code assigned by the credit card issuing bank to the transaction.
0043 Trace Number Network trace returned with response.
0052 Transponder / Proximity Indicator Indicator stating that a transponder or proximity device was used to originate the transaction.
Valid Values:
0 = No transponder
1 =Transponder initiated transaction
2 = Proximity using VSDC rules
3 = Proximity using MagStripe Rules
5=Terminal Transponder equipped
Value 1 is a transponder as defined by Card Associations participating in RFID is a wireless communications device that usually uses satellite connection. These devices are commonly implemented at toll booths.

Value 2 are transactions conducted without manually swiping a card through a point of sale device using any number of different wireless technologies using protocol like Bluetooth or proprietary RF technology. The consumer must be in a certain range (between 2 centimeters and 20 meters) of the wireless reading device.

Value 3 has the capability of converting radio signal to magnetic stripe data.

It is best to confirm the type of RFID device being considered for deployment and that your system is flexible to have this field configurable.

Value of 5 is the terminal transponder is equipped, transaction swiped or key entered.
0054 POS Entry Mode 01 - Manual/Key Entry
07 - Contactless M/Chip or Visa Smart Card read
82 - Contactless Mobile Commerce device
90 - Magnetic Stripe-CVV/CVC certified, unaltered Track Data (1 or 2) included in Authorization Request
91 - Contactless magnetic stripe read
0060 Unique Device ID Merchant assigned value to meet TPP requirements for Spring 2013. Must be stored and displayed and may be used for settlement.
Used to identify the source lane or terminal through which a transaction is processed.
0070 Customer Code Merchant assigned code identifying this customer (customer ID or general ledger account number).
0105 Data files path Contains the directory path where Fusebox is installed on the system. The maximum field length is 60.
0106 Batch file path Directory path and file name where the Fusebox settlement file is located. The maximum field length is 60.
0107 Report file path Contains the directory path and file name for the Fusebox settlement report. Required for settlement.
0108 History file path Contains the directory path to where history files are to be archived. Not required for most Fusebox implementations.
0109 Terminal ID References a terminal defined in Fusebox, which is tied to a MID/TID.
0110 Cashier ID Can contain any code or name up to 8 characters to identify the person running the POS.
0115 Transaction Qualifier Determines type of account used.
010 = Credit
0125 Compliance Data Assigned for chargeback retrieval purposes.
0126 Compliance Data Indicator showing how card was presented on original authorization:
00 = Manual
01 = track1
02 = track2
0127 Compliance Data Any additional, non-standard data the processor requires to be tracked for CPS compliance.
0128 CPS Orig. Auth Amount Original authorization only dollar amount associated with this transaction. If not supplied, the value will default to the Authorization Amount (field 0002).
0130 CPS Total Authorized Amount Total amount authorized up to this point in the lifecycle of this transaction. If not supplied, the value will default to the Authorization Amount (field 0002). If the transaction is a Prior-Auth (07) this field should contain the dollar amount to be settled.
0131 CPS Total Incremental Auths Sent This is the total number of incremental authorizations that were sent within a batch settlement.
1000 Card Type Two character card abbreviation defined in configuration.
1001 Card Name Full card name defined in configuration.
1003 Gateway Response Code Code generated by the Gateway to indicate its state when exiting. Governs internal error messages parsed from pberrors.txt and displayed in field 1010 and / or host messages displayed in field 1004. Primary response field used in determining good or bad transaction status.
1004 Host Response Message Host response message, either verbatim or evaluated. May contain the Gateway error message.

Should be displayed for all transactions. Must be displayed if field 1003 is 0060.
1005 Merchant Number Merchant number from the merchant file.
1009 Host Response Code Host response code indicating condition of the transaction (both authorization and settlement).
1010 Gateway Response The Gateway response message corresponding to error code returned in field 1003.

Should be displayed for all transactions. Must be displayed if field 1003 is not 0000 or 0060.
1011 Host Reference Number Reference number assigned by host processor to track this transaction. Conditional.
5020 Token Account Status Identifies the account range as regulated or non-regulated and is received from the Card Brand. It will contain one of the below values to indicate the status of the account range and should be included in capture if present in the authorization response.
Code Description:
R – Regulated
N - Non-Regulated
5021 Token Assurance Level Defined by the token service provider, this Visa or MasterCard value indicates the assigned confidence level of the token-to-PAN/cardholder binding. It will be returned back to merchants in authorization response when it’s available from association.
5022 Token Requester ID This 11-character alphanumeric field contains the value that uniquely identifies the pairing of token requestor with the token domain. This value is sent in capture to identify the requestor to the card brand. For payment token transactions, merchant should send in token requestor id when it’s available. It’s a required field for MasterCard card-on-file token transactions.
5024 Last 4 Digits of Primary PAN Last 4 digits of actual account number will be returned back in authorization response when it’s available from association, merchant can use it for receipt-printing purposes instead of using payment token number.
5025 Card Brand Token Status Contains the status of the token. Valid Values:
0 = Non Token Transaction
1 = Active
2 = Suspended
3 = Deactivated
4 = Expired
5 = Unknown