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.

FieldNameLength
Type
Description
0002Transaction Amount1-14
cents
Authorized Amount. EMV Tag 9F02
0013Transaction Date6
date
Terminal Transaction Date. EMV Tag 9A
0017Cash Back1-14
cents
Cashback / Other Amount - Optional. EMV Tag 9F03
0023Account Type2
numeric
Type of account used.
00=Checking (default) 01 = Savings 02 = Other, 03 = Credit
EMV Tag 5F57
0052Transponder / Proximity Indicator1
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
0054POS Entry Mode2
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
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)
0055PIN Capabilities1
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
0057ICC Chip Condition Code1
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
0140Terminal Currency Tri-graph3
alpha
ISO alpha currency code of the terminal running at the merchant location
0141Terminal Currency Code3
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
0163Cardholder Language Preference2
alphanumeric
Alpha characters according to ISO 639 representing language indicated by cardholder or card data for transaction. EMV Tag 5F2D
0201TIP1-14
cents
Tip / Other Amount - Optional. EMV Tag 9F03
1300Application Cryptogram16
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
1301Issuer Authentication Data32
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
1302Application Expiration Date6
date
Date the application expires. Format YYMMDD. EMV Tag 5F24
1303Cardholder Verification Method (CVM) Results1-6
alphanumeric
Indicates the results of the last CVM performed. EMV Tag 9F34
1304Device (IFD) Serial Number8
alphanumeric
Unique and permanent serial number assigned to the IFD by the manufacturer. EMV Tag 9F1E
1305Issuer Application Data1-64
alphanumeric
Contains proprietary application data for transmission to the issuer in an online transaction. EMV Tag 9F10
1306Terminal Capabilities6
alphanumeric
Indicates the card data input, CVM and security capabilities of the terminal. EMV Tag 9F33
1307Terminal Verification Result (TVR)10
alphanumeric
A set of indicators from the terminal application risk analysis and cardholder verification. EMV Tag 95
1308Pre-AC Generate Issuer Scripts1-256
alphanumeric
Contains proprietary issuer data for transmission to the ICC before the second GENERATE AC command. EMV Tag 71
1309Issuer Script Results1-84
alphanumeric
Indicates the result of the terminal script processing. EMV Tag 9F5B
1310Issuer Script Identifier8
alphanumeric
Identification of the Issuer Script. EMV Tag 9F18
1311Application Currency Code3
numeric
Indicates the country of the ICC chip issuer. EMV Tag 9F42
1312Terminal Country Code3
numeric
Indicates the country of the terminal. EMV Tag 9F1A
1313Application PAN Sequence Number2
numeric
Identifies and differentiates cards with the same PAN. EMV Tag 5F34
1314Dedicated File Name10-32
alphanumeric
Identifies the name of the DF as described in ISO/IEC 7816-4. EMV Tag 84
1315ICC Application Version Number4
alphanumeric
Version number assigned by the payment system for the application. EMV Tag 9F08
1316EMV Device ID8
alphanumeric
Designates the unique location of a terminal at a merchant (aka Terminal Identification). EMV Tag 9F1C
1317Terminal Application Version Number4
alphanumeric
Version number assigned by the payment system for the application. EMV Tag 9F09
1318Transaction Sequence Counter1-8
numeric
Counter maintained by the terminal application that is incremented by one for each transaction. EMV Tag 9F41
1319Application Interchange Profile4
alphanumeric
Indicates the capabilities of the card to support specific functions in the application. EMV Tag 82
1320Application Transaction Counter (ATC)4
alphanumeric
Counter maintained by the application in the ICC (incrementing the ATC is managed by the ICC). EMV Tag 9F36
1321Cryptogram Information Data2
alphanumeric
Indicates the type of cryptogram and the actions to be performed by the terminal. EMV Tag 9F27
1322Terminal Type2
alphanumeric
Indicates the environment of the terminal, its communications capability, and its operational control. EMV Tag 9F35
1323Unpredictable Number8
alphanumeric
Value to provide variability and uniqueness to the generation of a cryptogram. EMV Tag 9F37
1325ICC Application Identifier6-32
alphanumeric
ICC AID - Identifies the application as described in ISO/IEC 7816-5. EMV Tag 4F
1326ICC Application Preferred Name1-16
alphanumeric
Preferred mnemonic associated with the AID. EMV Tag 9F12
1327Application Label1-16
alphanumeric
Mnemonic associated with the AID according to ISO/IEC 7816-5. EMV Tag 50
1328Terminal Application Identifier6-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
1329Default Issuer Action Code10
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
1330Denial Issuer Action Code10
alphanumeric
Specifies the issuer’s conditions that cause the denial of a transaction without attempt to go online. EMV Tag 9F0E
1331Online Issuer Action Code10
alphanumeric
Specifies the issuer’s conditions that cause a transaction to go online. EMV Tag 9F0F
1332Application Usage Control4
alphanumeric
Indicates issuer’s specified restrictions on the geographic usage and services allowed for the application. EMV Tag 9F07
1333Last Host EMV Key Download8
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.
1334Transaction Status Information4
alphanumeric
Indicates the functions performed in a transaction. EMV Tag 9B
1338Smart Card Scheme2
alphanumeric
Smart Card Scheme. EMV Tag DF04
1339EMV Response Code1-2
alphanumeric
EMV Response Code. EMV Tag 8A
1340Extra EMV ISO TLV Data1-685
alphanumeric
Use for extra EMV Tag data, without an Elavon Gateway API Field identified, in TLV format.
1343Post-AC Generate Issuer Scripts1-265
alphanumeric
Contains proprietary issuer data for transmission to the ICC after the second GENERATE AC command. EMV Tag 72
1345ICC Form Factor Indicator8
alphanumeric
Form Factor Indicator. EMV Tag 9F6E
1346ICC Customer Data1-64
alphanumeric
Customer Exclusive Data. EMV Tag 9F7C
1357Transaction Currency Code3
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
1358Cryptogram Tran Type2
alphanumeric
EMV Transaction Type. EMV Tag 9C
1359EMV CVM Verification Indicator1
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
1361Issuer Country Code3
alphanumeric
Issuer Country Code. EMV Tag 5F56
1378EMV Approved Receipt Field List1-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.
1379EMV Declined Receipt Field List1-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.
1380POS Entry Indicator1-20
alphanumeric
TPP specific POS Entry Mode text for receipts based on the value in Field 0054 and the TPP rules.

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 NumberField NameDescription
0002Transaction AmountTotal 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.
0017Cashback AmountActual 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.
0201Tip Amount 1Actual 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.
0202Tip Amount 2Additional Restaurant Industry Tip Field, see API field 0201.
1362EMV Cryptogram AmountEstimated 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.
1363EMV Cryptogram Other AmountEstimated “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 NumberField NameDescription
0001Transaction TypeMust 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.
0002Transaction AmountThe total amount of the purchase.
0003Account NumberSwiped 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.
0006Auth CodeCode returned from the card issuer or authorizing institution indicating an approved authorization request.
0007Reference NumberUnique 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.

0009Batch 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.
0025Business DateUsed to control business date in Elavon software applications.
0032Original Auth DateDate the original authorization transaction took place.
0033Original Auth timeTime the original authorization transaction took place.
0034Authorization Characteristics IndicatorCode that is used to track participation status of this transaction in interchange rate programs.
0037Validation CodeComputed value assigned by the card association (VISA, MasterCard, and so on) and used to verify data integrity between authorization and settlement.
0038Reason CodeCode assigned by some third party processors to track why a transaction was rated as it was.
0040Compliance DataContains the indicator returned by the issuing bank to indicate the result of the CVV2 (VISA), CVC2 (MasterCard) or CID (AMEX) verification.
0042Compliance DataCode assigned by the credit card issuing bank to the transaction.
0043Trace NumberNetwork trace returned with response.
0052Transponder / Proximity IndicatorIndicator 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.
0054POS Entry Mode01 - 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
0060Unique Device IDMerchant 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.
0070Customer CodeMerchant assigned code identifying this customer (customer ID or general ledger account number).
0105Data files pathContains the directory path where Fusebox is installed on the system. The maximum field length is 60.
0106Batch file pathDirectory path and file name where the Fusebox settlement file is located. The maximum field length is 60.
0107Report file pathContains the directory path and file name for the Fusebox settlement report. Required for settlement.
0108History file pathContains the directory path to where history files are to be archived. Not required for most Fusebox implementations.
0109Terminal IDReferences a terminal defined in Fusebox, which is tied to a MID/TID.
0110Cashier IDCan contain any code or name up to 8 characters to identify the person running the POS.
0115Transaction QualifierDetermines type of account used.
010 = Credit
0125Compliance DataAssigned for chargeback retrieval purposes.
0126Compliance DataIndicator showing how card was presented on original authorization:
00 = Manual
01 = track1
02 = track2
0127Compliance DataAny additional, non-standard data the processor requires to be tracked for CPS compliance.
0128CPS Orig. Auth AmountOriginal authorization only dollar amount associated with this transaction. If not supplied, the value will default to the Authorization Amount (field 0002).
0130CPS Total Authorized AmountTotal 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.
0131CPS Total Incremental Auths SentThis is the total number of incremental authorizations that were sent within a batch settlement.
1000Card TypeTwo character card abbreviation defined in configuration.
1001Card NameFull card name defined in configuration.
1003Gateway Response CodeCode 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.
1004Host Response MessageHost 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.
1005Merchant NumberMerchant number from the merchant file.
1009Host Response CodeHost response code indicating condition of the transaction (both authorization and settlement).
1010Gateway ResponseThe 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.
1011Host Reference NumberReference number assigned by host processor to track this transaction. Conditional.
5020Token Account StatusIdentifies 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
5021Token Assurance LevelDefined 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.
5022Token Requester IDThis 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.
5024Last 4 Digits of Primary PANLast 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.
5025Card Brand Token StatusContains the status of the token. Valid Values:
0 = Non Token Transaction
1 = Active
2 = Suspended
3 = Deactivated
4 = Expired
5 = Unknown