POS and eCommerce I-file field mapping

This page is for POS terminal and eCommerce integrations that process transactions through the dual message system (DMS), where authorisation and clearing are separate processes. If you operate ATMs, see ATM I-file field mapping instead.

This page maps each element of the I-file (schema version 25.2.0) to the Visa and Mastercard data element it is populated from. Use it to determine which scheme field maps to each I-file field when building your transaction file.

All amounts are presented as decimals with the ISO 4217 currency exponent applied. All currency codes are presented as ISO 4217 alpha-3 codes, converted from the numeric codes carried in the scheme message.

Field mapping

iFile element / attribute	XML level	Scheme source field	Format / transformation	Example
`merchantID`	`merchant` (attribute)	DE42 Card Acceptor ID Code	Trailing spaces removed	`333331017`
`terminalID`	`terminal` (attribute)	DE41 Card Acceptor Terminal ID	Trailing spaces removed	`44441017`
`batchNumber`	`terminal` (attribute)	File Sequence Number	Last 3 digits of the 6-digit File Sequence Number	`722`
`transactionID`	`transaction` (attribute)	DE37 Retrieval Reference Number (RRN)	an12, as received	`503209184527`
`rateOfferRef`	`transaction` (attribute)	`exchangeRate.uuid` from the DCC rate response	UUID	`b8e69289-3cb2-40d3-803a-fbb5f3d5e8a4`
`currencyConversionType`	`transaction` (attribute)	Indicates how the transaction was converted	`dcc` or `mcp`, case-insensitive (see conversion type values)	`dcc`
`bin`	`transaction`	DE2 Primary Account Number	First 10 digits of the PAN only	`4659012530`
`transactionCode`	`transaction`	Clearing transaction type. Visa: TC05 / TC06. Mastercard: IPM DE3	`debit` = sale (Visa TC05, Mastercard DE3 `00`); `credit` = refund (Visa TC06, Mastercard DE3 `20`)	`debit`
`baseAmount`	`transaction`	Original transaction amount before conversion	Decimal, merchant currency	`21.85`
`transactionCurrency`	`transaction`	DE49 Currency Code, Transaction	ISO 4217 alpha-3	`GBP`
`transactionAmount`	`transaction`	DE4 Amount, Transaction	Decimal, cardholder currency	`4.95`
`exchangeRate`	`transaction`	FX rate from the DCC rate response. `1.0000` if the cardholder opted out of DCC	Decimal, 4 decimal places	`0.2266`
`transactionDateTime`	`transaction`	Authorisation date and time	ISO 8601, local time with UTC offset (`YYYY-MM-DDThh:mm:ss±hh:mm`)	`2024-05-02T12:30:15+04:00`
`customerInstructions`	`transaction`	DE22 POS Entry Mode	See entry mode values	`contactless`
`authorisationCode`	`transaction`	DE38 Authorisation ID Response	an6, as received	`123456`
`additionalReferenceID`	`transaction`	Acquirer Reference Number (ARN). Visa: TC05 / TC06 clearing record. Mastercard: IPM DE31	n23, as submitted in clearing	`24000005032000001845271`
`additionalReferenceCode`	`transaction`	Visa: Transaction Identifier (Field 62.2). Mastercard: Trace ID (IPM DE63 Transaction Life Cycle ID)	As received. Optional element

Conversion type values

The currencyConversionType attribute indicates how the transaction was converted. Values are case-insensitive.

`currencyConversionType`	Description
`dcc`	Dynamic Currency Conversion
`mcp`	Multi-Currency Pricing

Batch identifier

iFile attribute	Rule	Example
`batchNumber`	Last 3 digits of the 6-digit File Sequence Number	File Sequence Number `000722` → `batchNumber="722"`

Entry mode values

The customerInstructions element is derived from positions 1-2 of DE22.

`customerInstructions`	DE22 positions 1-2	Description
`chip`	`05`	Chip (ICC) read
`contactless`	`07`	Contactless chip read
`magswipe`	`90` / `91`	Full magnetic stripe read
`eCommerce`	Mastercard: `81`. Visa: `01` with Field 25 POS Condition Code `59`	Card not present, eCommerce
`keyed`	`01`	Manual key entry, card present
`signed`	`05` / `90` / `91` with signature as the cardholder verification method (EMV tag 9F34 CVM Results)	Card present, cardholder verified by signature
`mailTelephoneOrder`	`01`. Visa: Field 25 POS Condition Code `08`. Mastercard: DE61 Cardholder Presence Indicator `2` (mail) / `3` (telephone)	Card not present, mail or telephone order

signed is determined by the cardholder verification method rather than by DE22 alone, as DE22 positions 1-2 only indicate how the card data was read.

DCC opt-out

Where the cardholder opts out of DCC, the transaction is processed in the merchant currency:

iFile element	Value on opt-out
`exchangeRate`	`1.0000`
`transactionCurrency`	Merchant currency
`transactionAmount`	Equal to `baseAmount`

Examples

DCC accepted:

<transaction transactionID="503209184527" rateOfferRef="b8e69289-3cb2-40d3-803a-fbb5f3d5e8a4" currencyConversionType="dcc">
  <bin>4659012530</bin>
  <transactionCode>debit</transactionCode>
  <baseAmount>21.85</baseAmount>
  <transactionCurrency>GBP</transactionCurrency>
  <transactionAmount>4.95</transactionAmount>
  <exchangeRate>0.2266</exchangeRate>
  <transactionDateTime>2024-05-02T12:30:15+04:00</transactionDateTime>
  <customerInstructions>contactless</customerInstructions>
  <authorisationCode>123456</authorisationCode>
  <additionalReferenceID>24000005032000001845271</additionalReferenceID>
</transaction>

DCC opted out:

<transaction transactionID="503213184528" rateOfferRef="b77a12e9-3bee-4412-a321-261ebd5ba975" currencyConversionType="dcc">
  <bin>4746120840</bin>
  <transactionCode>debit</transactionCode>
  <baseAmount>4.75</baseAmount>
  <transactionCurrency>AED</transactionCurrency>
  <transactionAmount>4.75</transactionAmount>
  <exchangeRate>1.0000</exchangeRate>
  <transactionDateTime>2025-02-01T05:52:01+04:00</transactionDateTime>
  <customerInstructions>chip</customerInstructions>
  <authorisationCode>943284</authorisationCode>
  <additionalReferenceID>24000005032000001845289</additionalReferenceID>
</transaction>

File formats

Android app

Codes and standards

POS and eCommerce I-file field mapping

Field mapping

Conversion type values

Batch identifier

Entry mode values

DCC opt-out

Examples