> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fexco.com/llms.txt
> Use this file to discover all available pages before exploring further.

# POS and eCommerce I-file field mapping

> Mapping of I-file v25.2.0 elements to Visa and Mastercard dual message (DMS) data elements for DCC POS and eCommerce transactions.

> [!NOTE]
>
> 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](https://docs.fexco.com/dcc/developer-resources/file-formats/atm-ifile-field-mapping.md) 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.

> [!NOTE]
>
> 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](#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](#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 |

> [!NOTE]
>
> `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:

```xml theme={null}
<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:

```xml theme={null}
<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>
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.