> ## 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.

# ATM I-file field mapping

> Mapping of I-file v25.2.0 elements to Visa and Mastercard single message (SMS) data elements for DCC ATM transactions.

> [!NOTE]
>
> This page is for **ATM integrations** that process transactions through the single message system (SMS), where authorisation, clearing, and settlement happen in one message. If you operate POS terminals or eCommerce, see [POS and eCommerce I-file field mapping](https://docs.fexco.com/dcc/developer-resources/file-formats/pos-ecommerce-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. If DE42 is not used, populated with the DE41 value | Trailing spaces removed | `33331017` |
| `terminalID` | `terminal` (attribute) | DE41 Card Acceptor Terminal ID | Trailing spaces removed | `33331017` |
| `batchNumber` | `terminal` (attribute) | File Sequence Number | Last 3 digits of the 6-digit File Sequence Number | `822` |
| `transactionID` | `transaction` (attribute) | DE37 Retrieval Reference Number (RRN) | an12, as received | `503218184601` |
| `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 | `4761340000` |
| `transactionCode` | `transaction` | Message Type Indicator (MTI) | `debit` = MTI 0200 (withdrawal); `credit` = MTI 0400/0420 (reversal) | `debit` |
| `baseAmount` | `transaction` | Withdrawal amount + DE28 Access Fee (if levied) | Decimal, terminal currency | `100.00` |
| `transactionCurrency` | `transaction` | DE49 Currency Code, Transaction | ISO 4217 alpha-3 | `SGD` |
| `transactionAmount` | `transaction` | DE4 Amount, Transaction | Decimal, cardholder currency | `38.66` |
| `exchangeRate` | `transaction` | FX rate from the DCC rate response | Decimal, 4 decimal places | `0.3866` |
| `transactionDateTime` | `transaction` | Authorisation date and time | ISO 8601 with UTC offset | `2022-03-09T16:05:58+04:00` |
| `customerInstructions` | `transaction` | DE22 POS Entry Mode | See [entry mode values](#entry-mode-values) | `contactless` |
| `schemeNE2ESettlementAmount` | `transaction` | DE5 Amount, Settlement | Decimal, settlement currency | `28.27` |
| `schemeNE2ESettlementRate` | `transaction` | DE9 Conversion Rate, Settlement | Decimal indicator applied (see [settlement rate](#settlement-rate)) | `0.731247` |
| `schemeNE2ESettlementCurrency` | `transaction` | DE50 Currency Code, Settlement | ISO 4217 alpha-3 | `USD` |
| `dispensedAmount` | `transaction` | Withdrawal amount excluding DE28 Access Fee | Decimal, terminal currency | `100.00` |
| `authorisationCode` | `transaction` | DE38 Authorisation ID Response | an6, as received | `123456` |
| `additionalReferenceID` | `transaction` | DE11 System Trace Audit Number (STAN) | n6, as received | `009450` |
| `additionalReferenceCode` | `transaction` | Visa: Field 62.2 Transaction Identifier. Mastercard: DE63 Network Data | As received | `503201847301842` |

## 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 |

## Merchant and batch identifiers

| iFile attribute | Rule | Example |
| - | - | - |
| `merchantID` | Populated from DE42. Where DE42 is not used, DE42 = DE41 and `merchantID` takes the DE41 value | DE41 `33331017` → `merchantID="33331017"` |
| `batchNumber` | Last 3 digits of the 6-digit File Sequence Number | File Sequence Number `000822` → `batchNumber="822"` |

## 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 |

## Settlement rate

DE9 is an 8-digit field where the first digit indicates the number of decimal places in the remaining seven digits. The value is presented in the iFile with the decimal point applied.

| DE9 (raw) | Decimal places | `schemeNE2ESettlementRate` |
| - | - | - |
| `60731247` | 6 | `0.731247` |
| `70917803` | 7 | `0.0917803` |
| `51089540` | 5 | `10.89540` |

The settlement amount is calculated as:

```text theme={null}
schemeNE2ESettlementAmount (DE5) = transactionAmount (DE4) x schemeNE2ESettlementRate (DE9)
```

## Amount fields

| Scenario | `baseAmount` | `dispensedAmount` |
| - | - | - |
| No Access Fee | Withdrawal amount | Withdrawal amount |
| Access Fee levied | Withdrawal amount + Access Fee | Withdrawal amount |

## Example

```xml theme={null}
<transaction transactionID="503218184601" rateOfferRef="b8e69289-3cb2-40d3-803a-fbb5f3d5e8a4" currencyConversionType="dcc">
  <bin>4761340000</bin>
  <transactionCode>debit</transactionCode>
  <baseAmount>100.00</baseAmount>
  <transactionCurrency>SGD</transactionCurrency>
  <transactionAmount>38.66</transactionAmount>
  <exchangeRate>0.3866</exchangeRate>
  <transactionDateTime>2022-03-09T16:05:58+04:00</transactionDateTime>
  <customerInstructions>contactless</customerInstructions>
  <schemeNE2ESettlementAmount>28.27</schemeNE2ESettlementAmount>
  <schemeNE2ESettlementRate>0.731247</schemeNE2ESettlementRate>
  <schemeNE2ESettlementCurrency>USD</schemeNE2ESettlementCurrency>
  <dispensedAmount>100.00</dispensedAmount>
  <authorisationCode>123456</authorisationCode>
  <additionalReferenceID>009450</additionalReferenceID>
  <additionalReferenceCode>503201847301842</additionalReferenceCode>
</transaction>
```


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