Sales data file
This specification defines the generic CSV interface for sales transactions of ReconHub. You will find all required and optional fields and their desired formats further below. Besides CSV, ReconHub also supports other formats such as XML, JSON, Excel and fixed length. Please contact support in this case.
Data exchange / file delivery
The sales 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.
Encoding, Escaping and Constraints
A straight-line character (‘|’, ASCII code 124) is used as delimiter of the values within one line. All occurrences of this character must be removed from the transmitted values.
- Each line is separated with a CR & LF (0x0D & 0x0A).
- [UTF8] encoding is used for sales data files.
- Except for line breaks, non-visible and functional characters are not allowed.
Data elements
The following table shows the used data types for the sales 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. |
Columns
The table below shows all available fields and their conditions.
| Column Number | Column name | Comment | Mandatory | Format | Length |
|---|---|---|---|---|---|
| 1 | Terminal ID | Identifier of the terminal. Note: Either the Terminal Identification or Location ID must be provided. | C | str | 16 |
| 2 | Brand ID | Brand identifier of the transaction. | R | str | 30 |
| 3 | Acquirer ID | Payment processor identifier of the transaction. | O | str | 30 |
| 4 | Transaction Date | Date and time of the transaction on the cash register (Sale). | M | dto | |
| 5 | Business Date | The Business date of the transaction. Depending on the day-end closing, the business date may differ from the transaction date. | R | dat | |
| 6 | Amount | Amount of the transaction. | M | amt | 19,4 |
| 7 | Currency | 3-letter currency code of the amount according to [ISO4217]. | M | str | 3 |
| 8 | Transaction Sequence Counter | 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 | 10 |
| 9 | Transaction Type | Type of transaction. Possible values:
| O | str | 20 |
| 10 | Merchant ID | Merchant Identification Number is a unique code given to a business unit. | R | str | 15 |
| 11 | Issuer Country Code | Country Code of the card origin according to [ISO3166] alpha-2 code. | O | str | 3 |
| 12 | Location ID | Used to identify the physical location of the terminal. Can be the number or name of the cash register, for example. Note: Either the terminal ID or the location ID must be provided. | C | str | 30 |
| 13 | Authorisation Code | Authorisation code of the Transaction | O | str | 50 |
| 14 | CardNumberMasked | Masked PAN (application primary account number) | R | str | 19 |
| 15 | EFT Transaction Date | Date on which the transaction was executed on the EFT/POS terminal. This value is transmitted from the terminal to the cash register after a successful authorization. | O | dto | |
| 16 | Transaction Reference | Payment Processor Reference Number | R | str | 50 |
| 17 | ApplicationId | Application Identifier | O | str | 32 |
| 18 | PAN Encrypted | The PAN encrypted of a transaction | O | str | 32 |
| 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 |
Mapping
This section describes how the columns of an sales data file are mapped to a ReconHub sales 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.
| Sales 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 by using the Terminal ID. If the terminal with the given Terminal ID is not found, the terminal is resolved by using the Location ID. |
| UID | The UID is calculated by concatenating the sales transaction fields: Terminal ID or Location ID, Transaction Date, Currency, Amount, TransactionSequenceCounter, Authorisation Code. Records with the same UID are considered identical. If a sales transaction with the same UID already exists in the file or in ReconHub, the sales transaction is recognized as a duplicate and will be ignored. |
Example
ABCD5222|MAESTRODOMESTIC|POSTFINANCE|2018-03-18T02:20:44+02:00|2018-03-18|195.18|CHF|29002932|Credit|ADN005550000010|CH|S15/CR028|ABC123|5678|2018-03-18T02:20:44+12:00|45768725285|A0000000031010|dGVzdHRlc3R0ZXN0ZXRlc3QxMTExMQ==|ExampleOrderId¶
96301|VPAY|BONCARD|2018-03-18T05:27:39+02:00|2018-03-18|820.29|CHF|48836022|Credit|ADN005550000010|CH|S19/CR008|ABC124|3254********3465|2018-03-18T05:27:38+02:00|0213785224|A0000001574443||ExampleOrderId¶
9999280223|VISA||2018-03-18T06:46:42+02:00|2018-03-18|917.34|CHF|76325557|Credit|ADN005550000010|CH|S01/CR011|KGHG135A|8678********2455|2018-03-18T06:46:42Z|OCHYGL2WWX|||¶
9999637351|PAYDIREKT|BSPAYONE|2018-03-18T07:17:33+02:00|2018-03-18|385.11|CHF|68753330|Debit|ADN005550000010|CH|S02/CR002|KGHG13X|4677********8467|2018-03-18T07:17:33+08:00|FQY3D|A0000001574443||¶
Terminal receipt example
The picture below shows as an example the printout of a terminal receipt. Fields which are supported by ReconHub are marked with a red rectangle.
