EFT data file
This specification defines the generic XML interface for EFT transactions of ReconHub. You will find all required and optional fields and their desired formats further below. Besides XML, ReconHub also supports CSV format. Please contact support in this case.
Data exchange / file delivery
The EFT data files must be submitted periodically to ReconHub. ReconHub provides an SFTP server as the preferred option. Please contact your project manager at Abrantix to receive your credentials to access our SFTP server. If you already have a data exchange platform or if you prefer another technology, please let us know. In this case, we will determine the best way forward.
Notes and Constraints
- Each line is separated with a CR & LF (0x0D & 0x0A).
- [UTF8] encoding is used for EFT data files.
- Except for line breaks, non-visible and functional characters are not allowed.
- Root element of the XML file must be called EftTransactions. The default namespace must be "http://www.abrantix.com/recon/eftTransaction/v1".
- The root element may contain an array of <EftTransaction> elements, each of which corresponds to a single EFT transaction. See Example below.
- For certain amount fields, the XML element should contain an attribute called currency that provides the 3-letter currency code of the amount according to [ISO4217]. See Fields to find the amount fields that require the currency attribute.
Data types
The following table shows the used data types for the EFT data file.
| Format | Description | Example |
|---|---|---|
| amt | Amount, with a total of 19 digits and 4 fraction digits. Amounts are always specified in the interface as decimal values in the main unit of the corresponding currency. The subunit is a decimal fraction (usually one hundredth) of the value of the main unit. '.' (dot) must be used as the decimal separator. Amounts must not contain thousands separators. Leading or trailing zeros, as well as the decimal separator for integer values, can be omitted. All amounts in the interface must always be interpreted with a +/- sign, where
| -98341.15 |
| dat | Defines a date in [ISO8601] format. | 2018-06-21 |
| dto | Defines a date including optional offset relative to Coordinated Universal Time (UTC). Formatted according to [ISO8601]: For format and examples can be found under Datetime formats. | 2018-06-06T12:11:25+01:00 2018-06-06T12:11:25Z 2018-06-06T12:11:25 |
| num | Integer number without decimal and thousands separator | 81231 |
| str | Unicode string data | CHF Test123 ABC |
Legend
| Abbreviation | Name | Description |
|---|---|---|
| C | Conditional | The value of the field is based on a condition. |
| M | Mandatory | The field must be provided in the file. |
| O | Optional | The field is optional. |
| R | Recommended | If the data is available, the field should be filled. The reconciliation of the transaction can be more precise with this field. |
Fields
The table below shows all available fields (XML elements) that can be provided for an EFT transaction and their conditions. They should be the child elements of <EftTransaction> element.
| Number | Element name | Description | Mandatory | Format | Length |
|---|---|---|---|---|---|
| 1 | UniqueIdentifier | Unique identifier of the transaction. Used to detect duplicates. For instance, a unique identifier can be generated by concatenating certain fields of transaction like TerminalId, TransactionDate, TransactionAmount, TransactionReference, Authorisation Code etc. (e.g. 123456|2023-05-09T14:02:03+02:00|2.34|BFP452124A54X09|56XC2B). See also Mapping for EFT transaction field UID. | M | str | |
| 2 | TerminalId | Identifier of the terminal. Note: Either TerminalId or LocationId must be provided. See also Mapping for EFT transaction field Terminal. | C | str | 100 |
| 3 | LocationId | Used to identify the physical location of the terminal. Can be the cash register number or the store ID. | C | str | 100 |
| 4 | TransactionAmount | Amount of the transaction. Note: Element must contain currency attribute. | M | amt | 19,4 |
| 5 | TransactionDate | Date on which the transaction was executed on the EFT/POS terminal | M | dto | |
| 6 | FeeAmount | Fee for the transaction. Note: Element must contain currency attribute. | R | amt | 19,4 |
| 7 | SettlementAmount | Amount to be settled by the payment processor for the transaction. Note: Element must contain currency attribute. | M | amt | 19,4 |
| 8 | SettlementGrossAmount | Gross amount of the settlement | O | amt | 19,4 |
| 9 | SettlementNetAmount | Net amount of the settlement | O | amt | 19,4 |
| 10 | AuthorisationCode | Authorisation code of the transaction | O | str | 50 |
| 11 | CardNumberMasked | Masked PAN (application primary account number) | R | str | 20 |
| 12 | AcquirerId | Payment processor identifier of the transaction. See also Mapping for EFT transaction field Acquirer | M | str | 30 |
| 13 | BrandId | Brand identifier of the transaction. See also Mapping for EFT transaction field Brand | M | str | 30 |
| 14 | SettlementId | Settlement identifier for the transaction | R | str | 50 |
| 15 | AcquirerPaymentDate | Date of payment by the payment processor | R | dat | |
| 16 | TransactionReference | Payment Processor Reference Number | R | str | 75 |
| 17 | TransactionSequenceCounter | Transaction sequence number maintained by the terminal, which is increased by one for each transaction. The terminal guarantees that this counter is unique per terminal. This field can also be used for the system traced audit number (STAN). | R | num | 50 |
| 18 | MerchantId | Merchant Identification Number is a unique code given to a business unit | R | str | 100 |
| 19 | OrderId | The merchant’s reference number. This is typically generated by the merchant’s ordering system. Also known as Merchant Order ID. | R | str | 50 |
| 20 | ContractNumber | Contract number for the transaction | O | str | 100 |
| 21 | TransactionTypes | This element can contain an array of transaction types that apply to the transaction. See Example below. Possible values:
| O | str | |
| 22 | AdditionalDatas | This element can be used to provide an array of additional data fields related to the transaction. This can be used to provide custom data by the merchant for their transactions (e.g. merchant specific IDs). These values can later be used for the reconciliation and posting of this transaction. For each <AdditionalData> element, attributes key (required) and type (optional) can be used to define the field name and type respectively. Possible values for type are:
| O |
Mapping
This section describes how the fields of an EFT data file are mapped to a ReconHub EFT transaction. Only fields that use a conversion or a lookup mechanism are listed. Fields that are simple one-to-one mappings are not listed here. These fields should be self-explanatory.
| EFT transaction field | Description |
|---|---|
| Acquirer | The payment processor of the transaction is resolved to an internal ID using the payment processor list. All supported values can be found in the dedicated payment processor list. If the given payment processor ID is not defined in the list, the payment processor is set to Unknown. |
| Brand | The brand of the transaction is resolved to an internal ID using the brand list. All supported values can be found in the dedicated brand list. If the given Brand ID is not defined in the list, the brand is set to Unknown. |
| Terminal | The terminal is resolved using the field TerminalId. If the terminal with the given Terminal ID is not found, the terminal is resolved using the field LocationId. |
| UID | The UID is calculated using the field UniqueIdentifier. Records with the same UID are considered identical. If an EFT transaction with the same UID already exists in the file or in ReconHub, the new transaction is recognized as a duplicate and will be ignored. |
Example
EFT data (XML) file
<?xml version="1.0" encoding="utf-8"?>
<EftTransactions xmlns="http://www.abrantix.com/recon/eftTransaction/v1">
<EftTransaction>
<UniqueIdentifier>UID-1</UniqueIdentifier>
<TerminalId>123456</TerminalId>
<TransactionAmount currency="CHF">2.34</TransactionAmount>
<TransactionDate>2023-05-09T14:02:03+02:00</TransactionDate>
<FeeAmount currency="CHF">0.2</FeeAmount>
<SettlementAmount currency="CHF">2.14</SettlementAmount>
<SettlementGrossAmount>2.34</SettlementGrossAmount>
<SettlementNetAmount>2.14</SettlementNetAmount>
<AuthorisationCode>56XC2B</AuthorisationCode>
<CardNumberMasked>12345xxxxxxxxx6789</CardNumberMasked>
<AcquirerId>TestAcquirer</AcquirerId>
<BrandId>Mastercard</BrandId>
<SettlementId>ABR.RE2305.004</SettlementId>
<AcquirerPaymentDate>2023-10-21</AcquirerPaymentDate>
<TransactionReference>BFP452124A54X09</TransactionReference>
<TransactionSequenceCounter>006589</TransactionSequenceCounter>
<MerchantId>Merchant</MerchantId>
<OrderId>MRCHNT-3300-230509-XBPA84G</OrderId>
<ContractNumber>003300</ContractNumber>
<TransactionTypes>
<TransactionType>FinancialAdjustment</TransactionType>
</TransactionTypes>
<AdditionalDatas>
<AdditionalData key="ProductCodes">0171 / 0173 / other</AdditionalData>
<AdditionalData key="Source">My Source 2</AdditionalData>
<AdditionalData key="Comment">Financial adjustment due to reason X</AdditionalData>
</AdditionalDatas>
</EftTransaction>
<EftTransaction>
<UniqueIdentifier>UID-2</UniqueIdentifier>
<LocationId>123456</LocationId>
<TransactionAmount currency="EUR">2.34</TransactionAmount>
<TransactionDate>2023-05-09T14:02:03+02:00</TransactionDate>
<SettlementAmount currency="AUD">2.14</SettlementAmount>
<AcquirerId>SomeUnknown</AcquirerId>
<BrandId>Visa</BrandId>
<AdditionalDatas>
<AdditionalData key="UnitPrice" type="Decimal">0.8</AdditionalData>
<AdditionalData key="Kilometer" type="Int32">13579</AdditionalData>
</AdditionalDatas>
</EftTransaction>
</EftTransactions>
XSD for EFT data (XML) file
XSD
<?xml version="1.0" encoding="utf-8"?>
<xs:schema
attributeFormDefault="unqualified"
elementFormDefault="qualified"
targetNamespace="http://www.abrantix.com/recon/eftTransaction/v1"
xmlns:ax="http://www.abrantix.com/recon/eftTransaction/v1"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<!-- Simple types -->
<xs:simpleType name="amount">
<xs:restriction base="xs:decimal" />
</xs:simpleType>
<xs:simpleType name="currency">
<xs:restriction base="xs:string">
<xs:pattern value="[A-Z]{2,3}"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="notEmptyString">
<xs:restriction base="xs:string">
<xs:minLength value="1" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="string50">
<xs:restriction base="xs:string">
<xs:maxLength value="50" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="string75">
<xs:restriction base="xs:string">
<xs:maxLength value="75" />
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="string100">
<xs:restriction base="xs:string">
<xs:maxLength value="100" />
</xs:restriction>
</xs:simpleType>
<!-- Complex types -->
<xs:complexType name="amountWithCurrency">
<xs:simpleContent>
<xs:extension base="ax:amount">
<xs:attribute name="currency" type="ax:currency" use="required" />
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<!-- Eft Transactions structure -->
<xs:element name="EftTransactions">
<xs:complexType>
<xs:sequence>
<xs:element minOccurs="0" maxOccurs="unbounded" name="EftTransaction">
<xs:complexType>
<xs:sequence>
<xs:element minOccurs="1" maxOccurs="1" name="UniqueIdentifier" type="ax:notEmptyString" />
<xs:element minOccurs="0" maxOccurs="1" name="TerminalId" type="ax:string100" />
<xs:element minOccurs="0" maxOccurs="1" name="LocationId" type="ax:string100" />
<xs:element minOccurs="1" maxOccurs="1" name="TransactionAmount" type="ax:amountWithCurrency" />
<xs:element minOccurs="1" maxOccurs="1" name="TransactionDate" type="xs:dateTime" />
<xs:element minOccurs="0" maxOccurs="1" name="FeeAmount" type="ax:amountWithCurrency" />
<xs:element minOccurs="1" maxOccurs="1" name="SettlementAmount" type="ax:amountWithCurrency" />
<xs:element minOccurs="0" maxOccurs="1" name="SettlementGrossAmount" type="xs:decimal" />
<xs:element minOccurs="0" maxOccurs="1" name="SettlementNetAmount" type="xs:decimal" />
<xs:element minOccurs="0" maxOccurs="1" name="AuthorisationCode" type="ax:string50" />
<xs:element minOccurs="0" maxOccurs="1" name="CardNumberMasked" type="ax:string50" />
<xs:element minOccurs="1" maxOccurs="1" name="AcquirerId" type="xs:string" />
<xs:element minOccurs="1" maxOccurs="1" name="BrandId" type="xs:string" />
<xs:element minOccurs="0" maxOccurs="1" name="SettlementId" type="ax:string50" />
<xs:element minOccurs="0" maxOccurs="1" name="AcquirerPaymentDate" type="xs:date" />
<xs:element minOccurs="0" maxOccurs="1" name="TransactionReference" type="ax:string75" />
<xs:element minOccurs="0" maxOccurs="1" name="TransactionSequenceCounter" type="ax:string50" />
<xs:element minOccurs="0" maxOccurs="1" name="MerchantId" type="ax:string100" />
<xs:element minOccurs="0" maxOccurs="1" name="OrderId" type="ax:string50" />
<xs:element minOccurs="0" maxOccurs="1" name="ContractNumber" type="ax:string100" />
<xs:element minOccurs="0" maxOccurs="1" name="TransactionTypes">
<xs:complexType>
<xs:sequence>
<xs:element maxOccurs="unbounded" name="TransactionType">
<xs:simpleType>
<xs:list>
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="Chargeback" />
<xs:enumeration value="FinancialAdjustment" />
</xs:restriction>
</xs:simpleType>
</xs:list>
</xs:simpleType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element minOccurs="0" maxOccurs="1" name="AdditionalDatas">
<xs:complexType>
<xs:sequence>
<xs:element maxOccurs="unbounded" name="AdditionalData">
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="key" />
<xs:attribute name="type">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="Char" />
<xs:enumeration value="String" />
<xs:enumeration value="Decimal" />
<xs:enumeration value="Int32" />
<xs:enumeration value="Int64" />
<xs:enumeration value="UInt64" />
<xs:enumeration value="DateTime" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>