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.

0002 (Transaction Amount)

• Description: Authorized Amount. EMV Tag 9F02
• Length: 1 - 14
• Data Type: cents

0013 (Transaction Date)

• Description: Terminal Transaction Date. EMV Tag 9A
• Length: 6
• Data Type: date

0017 (Cash Back)

• Description: Cashback / Other Amount - Optional. EMV Tag 9F03
• Length: 1 - 14
• Data Type: cents

0023 (Account Type)

• Description: Type of account used.
  • 00=Checking (default)
  • 01 = Savings
  • 02 = Other
  • 03 = Credit EMV Tag 5F57
• Length: 2
• Data Type: numeric

0052 (Transponder / Proximity Indicator)

• Description: 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
• Length: 1
• Data Type: numeric

0054 (POS Entry Mode)

• Description: 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
  • 85 – Internet (not an ISO value)
  • 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
• Length: 2
• Data Type: numeric

0055 (PIN Capabilities)

• Description: 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
• Length: 1
• Data Type: numeric

0057 (ICC Chip Condition Code)

• Description: 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.
• Valid Values:
  • 0 – ICC enabled card chip read
  • 1 – ICC enabled card first magnetic stripe Fallback
  • 2 – ICC enabled card subsequent magnetic stripe Fallback
• Length: 1
• Data Type: numeric

0140 (Terminal Currency Tri-graph)

• Description: ISO alpha currency code of the terminal running at the merchant location
• Length: 3
• Data Type: alpha

0141 (Terminal Currency Code)

• Description: 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
• Length: 3
• Data Type: numeric

0163 (Cardholder Language Preference)

• Description: Alpha characters according to ISO 639 representing language indicated by cardholder or card data for transaction. EMV Tag 5F2D
• Length: 2
• Data Type: alphanumeric

0201 (TIP)

• Description: Tip / Other Amount - Optional. EMV Tag 9F03
• Length: 1 - 14
• Data Type: cents

1300 (Application Cryptogram)

• Description: 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
• Length: 16
• Type: alphanumeric

1301 (Issuer Authentication Data)

• Description: Data sent to the ICC for online issuer authentication, used by the ICC to verify the response came from the issuer. EMV Tag 91
• Length: 32
• Data Type: alphanumeric

1302 (Application Expiration Date)

• Description: Date the application expires. Valid Value: Format YYMMDD. EMV Tag 5F24
• Length: 6
• Data Type: date

1303 (Cardholder Verification Method (CVM) Results)

• Description: Indicates the results of the last CVM performed. Valid Value: EMV Tag 9F34
• Length: 1 - 6
• Data Type: alphanumeric

1304 (Device (IFD) Serial Number)

• Description: Unique and permanent serial number assigned to the IFD by the manufacturer. Valid Value: EMV Tag 9F1E
• Length: 8
• Data Type: alphanumeric

1305 (Issuer Application Data)

• Description: Contains proprietary application data for transmission to the issuer in an online transaction. Valid Value: EMV Tag 9F10
• Length: 1 - 64
• Data Type: alphanumeric

Field 1306 (Issuer Application Data)

• Description: Indicates the card data input, CVM, and security capabilities of the terminal. Valid Value: EMV Tag 9F33
• Length: 6
• Data Type: alphanumeric

1307 (Terminal Verification Result TVR)

• Description: A set of indicators from the terminal application risk analysis and cardholder verification. Valid Value: EMV Tag 95
• Length: 10
• Data Type: alphanumeric

1308 (Pre-AC Generate Issuer Scripts)

• Description: Contains proprietary issuer data for transmission to the ICC before the second GENERATE AC command. Valid Value: EMV Tag 71
• Length: 1 - 256
• Data Type: alphanumeric

1309 (Issuer Script Results)

• Description: Indicates the result of the terminal script processing. EMV Tag 9F5B
• Length: 1 - 84
• Data Type: alphanumeric

1310 (Issuer Script Identifier)

• Description: Identification of the Issuer Script. Valid Value: EMV Tag 9F18
• Length: 8
• Data Type: alphanumeric

1311 (Application Currency Code)

• Description: Indicates the country of the ICC chip issuer. Valid Value: EMV Tag 9F42
• Length: 3
• Data Type: numeric

1312 (Terminal Country Code)

• Description: Indicates the country of the terminal. Valid Value: EMV Tag 9F1A
• Length: 3
• Data Type: numeric

1313 (Application PAN Sequence Number)

• Description: Identifies and differentiates cards with the same PAN. Valid Value: EMV Tag 5F34
• Length: 2
• Data Type: numeric

1314 (Dedicated File Name)

• Description: Identifies the name of the DF as described in ISO/IEC 7816-4. Valid Value: EMV Tag 84
• Length: 10 - 32
• Data Type: alphanumeric

1315 (ICC Application Version Number)

• Description: Version number assigned by the payment system for the application. Valid Value: EMV Tag 9F08
• Length: 4
• Data Type: alphanumeric

1316 (EMV Device ID)

• Description: Designates the unique location of a terminal at a merchant (aka Terminal Identification). Valid Value: EMV Tag 9F1C
• Length: 8
• Data Type: alphanumeric

1317 (Terminal Application Version Number)

• Description: Version number assigned by the payment system for the application. Valid Value: EMV Tag 9F09
• Length: 4
• Data Type: alphanumeric

1318 (Transaction Sequence Counter)

• Description: Counter maintained by the terminal application that is incremented by one for each transaction. Valid Value: EMV Tag 9F41
• Length: 1 - 8
• Data Type: numeric

1319 (Application Interchange Profile)

• Description: Indicates the capabilities of the card to support specific functions in the application. Valid Value: EMV Tag 82
• Length: 4
• Data Type: alphanumeric

1320 (Application Transaction Counter (ATC)

• Description: Counter maintained by the application in the ICC (incrementing the ATC is managed by the ICC). Valid Value: EMV Tag 9F36
• Length: 4
• Data Type: alphanumeric

1321 (Cryptogram Information Data)

• Description: Indicates the type of cryptogram and the actions to be performed by the terminal. Valid Value: EMV Tag 9F27
• Length: 2
• Data Type: alphanumeric

1322 (Terminal Type)

• Description: Indicates the environment of the terminal, its communications capability, and its operational control. Valid Value: EMV Tag 9F35
• Length: 2
• Data Type: alphanumeric

1323 (Unpredictable Number)

• Description: Value to provide variability and uniqueness to the generation of a cryptogram. Valid Value: EMV Tag 9F37
• Length: 8
• Data Type: alphanumeric

1325 (ICC Application Identifier)

• Description: ICC AID - Identifies the application as described in ISO/IEC 7816-5. Valid Value: EMV Tag 4F
• Length: 6 - 32
• Data Type: alphanumeric

1326 (ICC Application Preferred Name)

• Description: Preferred mnemonic associated with the AID. Valid Value: EMV Tag 9F12
• Length: 1 - 16
• Data Type: alphanumeric

1327 (ICC Application Preferred Name)

• Description: Preferred mnemonic associated with the AID. Valid Value: EMV Tag 9F12
• Length: 1 - 16
• Data Type: alphanumeric

1327 (Application Label)

• Description: Mnemonic associated with the AID according to ISO/IEC 7816-5. EMV Tag 50
• Length: 1 - 16
• Data Type: alphanumeric

1328 (Terminal Application Identifier)

• Description: Terminal AID - Identifies the application as described in ISO/IEC 7816-5. Valid Values:
  • 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
• Length: 6 - 32
• Data Type: alphanumeric

1329 (Default Issuer Action Code)

• Description: 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. Valid Value: EMV Tag 9F0D
• Length: 10
• Data Type: alphanumeric

1330 (Denial Issuer Action Code)

• Description: Specifies the issuer’s conditions that cause the denial of a transaction without attempt to go online. Valid Value: EMV Tag 9F0E
• Length: 10 -Data Type: alphanumeric

1331 (Online Issuer Action Code)

• Description: Specifies the issuer’s conditions that cause a transaction to go online. Valid Value: EMV Tag 9F0F
• Length: 10
• Data Type: alphanumeric

1332 (Application Usage Control)

• Description: Indicates issuer’s specified restrictions on the geographic usage and services allowed for the application. Valid Value: EMV Tag 9F07
• Length: 4
• Data Type: alphanumeric

1333 (Last Host EMV Key Download)

• Description: 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.
• Length: 8
• Data Type: numeric

1334 (Transaction Status Information)

• Description: Indicates the functions performed in a transaction. Valid Value: EMV Tag 9B
• Length: 4
• Data Type: alphanumeric

1338 (Smart Card Scheme)

• Description: Smart Card Scheme. Valid Value: EMV Tag DF04
• Length: 2
• Data Type: alphanumeric

1339 (EMV Response Code)

• Description: EMV Response Code. Valid Value: EMV Tag 8A
• Length: 1 - 2
• Data Type: alphanumeric

1340 (Extra EMV ISO TLV Data)

• Description: Use for extra EMV Tag data, without an Elavon Gateway API Field identified, in TLV format.
• Length: 1 - 685
• Data Type: alphanumeric

1343 (Post-AC Generate Issuer Scripts)

• Description: Contains proprietary issuer data for transmission to the ICC after the second GENERATE AC command. Valid Value: EMV Tag 72
• Length: 1 - 265
• Data Type: alphanumeric

1345 (ICC Form Factor Indicator)

• Description: Form Factor Indicator. Valid Value: EMV Tag 9F6E
• Length: 8
• Data Type: alphanumeric

1346 (ICC Customer Date)

• Description: Customer Exclusive Data. Valid Value: EMV Tag 9F7C
• Length: 1 - 64
• Data Type: alphanumeric

1357 (Transaction Currency Code)

• Description: Indicates the currency code of the transaction according to ISO 4217. Valid Value: EMV Tag 5F2A
• Length: 3
• Data Type: alphanumeric

1358 (Cryptogram Tran Type)

• Description: EMV Transaction Type. Valid Value: EMV Tag 9C
• Length: 2
• Data Type: alphanumeric

1359 (EMV CVM Verification Indicator)

• Description: Field to indicate to the POS the cardholder verification methods. Valid values:
  • 0 - Failed CVM
  • 1 - Signature required
  • 2 - PIN verified
  • 3 - PIN verified and signature required
  • 4 - Request for Signature CVM not parsed
• Length: 1
• Data Type: alphanumeric

1361 (Issuer Country Code)

• Description: Issuer Country Code. Valid Value: EMV Tag 5F56
• Length: 3
• Data Type: alphanumeric

1378 (EMV Approved Receipt Field List)

• Description: 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.
• Length: 1 - 256
• Data Type: alphanumeric

1379 (EMV Declined Receipt Field List)

• Description: 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.
• Length: 1 - 256
• Data Type: alphanumeric

1380 (POS Entry Indicator)

• Description: TPP specific POS Entry Mode text for receipts based on the value in Field 0054 and the TPP rules.
• Length: 1 - 20
• Data Type: alphanumeric

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

0002 (Cashback Amount)

• Description: 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 (Transaction Amount)

• Description: 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)

• Description: 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)

• Description: Additional Restaurant Industry Tip Field, see API field 0201.

1362 (EMV Cryptogram Amount)

• Description: 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)

• Description: 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.

0001 (Transaction Type)

• Description: 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)

• Description: The total amount of the purchase.

0003 (Account Number)

• Description: 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)

• Description: Code returned from the card issuer or authorizing institution indicating an approved authorization request.

0007 (Reference Number)

• Description: Unique number supplied by the POS to identify the transaction within a batch/processing period. This number should be unique within a settlement batch.

0009 (Batch No.)

• Description: 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)

• Description: Used to control business date in Elavon software applications.

0032 ( Original Auth Date)

• Description: Date the original authorization transaction took place.

Field 0033

• Field Name: Original Auth Time
• Description: Time the original authorization transaction took place.

Field 0034

• Field Name: Authorization Characteristics Indicator
• Description: Code that is used to track participation status of this transaction in interchange rate programs.

0037 (Validation Code)

• Description: 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)

• Description: Computed value assigned by the card association (VISA, MasterCard, and so on) and used to verify data integrity between authorization and settlement.

0040 (Compliance Code)

• Description: 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)

• Description: Code assigned by the credit card issuing bank to the transaction.

0043 (Trace Number)

• Description: Network trace returned with response.

0052 (Transponder / Proximity Indicator)

• Description: 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)

• Description:
• Valid Values:
  • 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)

• Description: 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.

0060 (Unique Device ID)

• Description: 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)

• Description: Merchant assigned code identifying this customer (customer ID or general ledger account number).

0105 (Data files path)

• Description: Contains the directory path where Fusebox is installed on the system. The maximum field length is 60.

0106 (Batch file path)

• Description: Directory path and file name where the Fusebox settlement file is located. The maximum field length is 60.

0107 (Report file path)

• Description: Contains the directory path and file name for the Fusebox settlement report. Required for settlement.

0108 (History file path)

• Description: Contains the directory path to where history files are to be archived. Not required for most Fusebox implementations.

0109 (Terminal ID)

• Description: References a terminal defined in Fusebox, which is tied to a MID/TID.

0110 (Cashier ID)

• Description: Can contain any code or name up to 8 characters to identify the person running the POS.

0115 (Transaction Qualifier)

• Description: Determines type of account used. Valid Value: 010 = Credit

0125 (Compliance Data)

• Description: Assigned for chargeback retrieval purposes.

0126 (Compliance Data)

• Description: Indicator showing how card was presented on original authorization.
• Valid Values:
  • 00 = Manual
  • 01 = track1
  • 02 = track2

0127 (Compliance Data)

• Description: Any additional, non-standard data the processor requires to be tracked for CPS compliance.

0128 (CPS Orig. Auth Amount)

• Description: 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)

• Description: Total amount authorized up to this point in the lifecycle of this transaction.
• Valid Values:
  • 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)

• Description: This is the total number of incremental authorizations that were sent within a batch settlement.

1000 (Card Type)

• Description: Two character card abbreviation defined in configuration.

1001 (Card Name)

• Description: Full card name defined in configuration.

1003 (Gateway Response Code)

• Description: 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)

• Description: Host response message, either verbatim or evaluated. May contain the Gateway error message. Note: Should be displayed for all transactions. Must be displayed if field 1003 is 0060.

1005 (Merchant Number)

• Description: Merchant number from the merchant file.

1009 (Host Response Code)

• Description: Host response code indicating condition of the transaction (both authorization and settlement).

1010 (Gateway Response)

• Description: 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)

• Description: Reference number assigned by host processor to track this transaction. Conditional.

5020 (Token Account Status)

• Description: 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.
• Valid Values:
  • R – Regulated
  • N - Non-Regulated

5021 (Token Assurance Level)

• Description: 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)

• Description: 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)

• Description: 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)

• Description: Contains the status of the token. Valid Values:
  • 0 = Non Token Transaction
  • 1 = Active
  • 2 = Suspended
  • 3 = Deactivated
  • 4 = Expired
  • 5 = Unknown

• previousCertification
• nextEMV Public Cap Keys, Parameters, and Reports