Reconciliation files | Precium Docs

Precium delivers reconciliation data as CSV over SFTP. This page describes the files as they are produced today, against Recon File Specification v3.

The recon file format is versioned and has changed twice. Column names differ between versions, so a parser written against an older file will not find its columns in a newer one. Confirm which version your SFTP account receives before you build against this page.

The three files

File	What it contains	Settlement required
Recon	Transactions reconciled against settlement data, ready for settlement in an upcoming cycle. The authoritative comparison dataset for a cycle.	Yes
Markoff	Transactions reconciled between Precium’s gateways and the providers, within the timeframe the file covers.	No
Exception	Transactions that could not be reconciled within the expected timeframe. Populated best effort, because only partial data exists.	n/a

An exception row is not a failed payment. It means settlement for that transaction was still outstanding when the file for that date was cut, so it appears in the exception file instead of the recon file. It may reconcile normally in a later cycle.

Parsing rules

These apply to every file unless stated otherwise.

Rule	Value
Encoding	UTF-8
Format	CSV, header row always present
Delimiter	Comma. Values containing a comma are quoted with `"`
Line terminator	CRLF
Dates	`YYYY-MM-DD`
Datetimes	`YYYY-MM-DD HH:MM`
Timezone	UTC throughout
Monetary values	Period decimal separator, rounded to 4 decimal places

Two things will break a naive parser.

Leading apostrophes. Numeric-looking values that must be read as strings are prefixed with a single quote (') so that Excel does not reformat them. In the v3 file this affects settlement_bank_account_number, gateway_transaction_reference, transaction_rrn and transaction_auth_code. Strip the leading ' before matching.

Amounts are in major units, not cents. transaction_amount is 40.0000 for ZAR 40.00. This is the opposite of the API, where amounts are in cents. Refunds and chargebacks carry a negative amount.

Recon file v3.0

27 columns. One row per transaction.

Identification

Column	Type	Notes
`merchant_name`	string	Merchant display name
`merchant_id`	uuid	Merchant identifier
`brand_name`	string	Brand display name
`brand_id`	uuid	Brand identifier
`gateway_transaction_id`	uuid	Precium gateway transaction identifier. This is your primary matching key.
`gateway_transaction_reference`	string	Your own reference, as supplied on the purchase. Prefixed with `'`

Transaction

Column	Type	Notes
`transaction_type`	enum	`PURCHASE`, `REFUND`, `CHARGEBACK`
`transaction_amount`	decimal	Major units, 4 dp. Negative for refunds and chargebacks. Defaults to `0.0000`
`transaction_currency`	string	ISO 4217
`transaction_date_time_utc`	datetime	`YYYY-MM-DD HH:MM`, UTC
`transaction_payment_method`	enum	For example `CARD`
`transaction_rrn`	string	Retrieval Reference Number. Prefixed with `'`
`transaction_auth_code`	string	Authorisation code. Prefixed with `'`

Card

Every field below is populated only when transaction_payment_method is CARD, and is empty otherwise.

Column	Type	Notes
`card_country`	string	Issuing country, ISO 3166-1 alpha-2
`card_type`	enum	`DEBIT`, `CREDIT`
`card_authenticated`	boolean	`TRUE` / `FALSE`. Whether 3D Secure authentication was applied
`card_tokenized`	boolean	`TRUE` / `FALSE`. Whether tokenisation was applied
`card_issuer`	string	Card scheme or issuer, for example `VISA`, `MASTERCARD`

Settlement and fees

Column	Type	Notes
`settlement_acquiring_bank`	enum	`ABSA`, `STANDARD_BANK`, `FNB`, `UNKNOWN`
`settlement_bank_account_number`	string	Destination account. Prefixed with `'`
`settlement_date`	date	Reporting settlement date
`fee_codes`	string	Comma-separated list of fee codes applied. Quoted when it contains commas. Empty when no fees apply
`invoiced_fee_total_ex_vat`	decimal	Defaults to `0.0000`
`invoiced_fee_total_incl_vat`	decimal	Defaults to `0.0000`
`settlement_fee_total_ex_vat`	decimal	Defaults to `0.0000`
`settlement_fee_total_incl_vat`	decimal	Defaults to `0.0000`
`fee_currency_code`	string	ISO 4217. Empty when no fees apply

Matching a transaction

Match on gateway_transaction_id. It is the purchase identifier Precium returns when you create a purchase, so it is the one value that is stable from your API call through to settlement.

Keep transaction_rrn, transaction_auth_code and the amount as secondary data. You will need them if a transaction has to be investigated at the acquiring bank, where the Precium identifier means nothing.

A refund does not carry its original purchase identifier in v3.0.

A refund is a separate payment transaction with its own gateway_transaction_id, its own RRN and its own authorisation code. Recon v2.1 carried a related_transaction_reference column linking it back to the original purchase. That column does not exist in v3.0.

If you need refund-to-purchase linkage, hold it on your side from the refund call, or ask your account contact which file version you are receiving.

Granularity

Event	Rows
A purchase	One
A hold followed by a capture	One. It is a single purchase
A refund	Its own row, `transaction_type` `REFUND`, negative amount
A chargeback	Its own row, `transaction_type` `CHARGEBACK`, negative amount

Column names across versions

A column changed name more than once. If you are reading an older file, or older documentation, this is the mapping.

v1.0	v2.1	v3.0 (current)
`purchase_id`	`gateway_transaction_id`	`gateway_transaction_id`
`purchase_reference`	`gateway_transaction_reference`	`gateway_transaction_reference`
`auth_code`	`auth_code`	`transaction_auth_code`
`rrn`	`rrn`	`transaction_rrn`
`is_3DS`	`three_ds`	`card_authenticated`
`is_tokenized`	`tokenization`	`card_tokenized`
`paid_at`	`transaction_date_time_utc`	`transaction_date_time_utc`
`type`	`type`	`transaction_type`
`related_to_purchase`	`related_transaction_reference`	(removed)
`settlement_id`	`settlement_id`	(removed)

So auth_code, transaction_auth_code and the authorisation_approval_code you may see in other material are the same value under three names, from three different file versions.

Delivery

Files are delivered daily by SFTP. A captured transaction appears once it has been fully reconciled with the acquirer, which can be a few days after it was processed. Inclusion in the recon file means Precium has matched the transaction to acquiring bank data and considers it reconciled; reconciled transactions are then eligible for settlement under the agreed settlement schedule.