ATM I-file field mapping

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 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. 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)	`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	`contactless`
`schemeNE2ESettlementAmount`	`transaction`	DE5 Amount, Settlement	Decimal, settlement currency	`28.27`
`schemeNE2ESettlementRate`	`transaction`	DE9 Conversion Rate, Settlement	Decimal indicator applied (see 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:

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

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

File formats

Android app

Codes and standards

Field mapping

Conversion type values

Merchant and batch identifiers

Entry mode values

Settlement rate

Amount fields

Example