Reconciliation | Precium Docs

Introduction

The Precium Reconciliation Service provides automated transaction reconciliation between your payment processing activity and settlement data. This service generates daily report files that enable you to track transactions through the complete payment lifecycle, from authorization to bank settlement.

This documentation covers the structure, format, and interpretation of reconciliation report files to ensure accurate financial reporting and streamlined operations.

Report Types Overview

The reconciliation system produces three distinct report types, each serving a specific purpose in the reconciliation workflow:

Report Type	Purpose	Settlement Required
Recon File	Primary reconciliation output with full settlement data	Yes
Markoff File	Transaction activity reconciled between gateways and providers	No
Exception File	Transactions that could not be reconciled within expected timeframe	Partial data

When to Use Each Report

File Format Specifications

Common Rules

All reconciliation files follow these formatting standards:

Attribute	Specification
Encoding	UTF-8
Header Row	Always included
Delimiter	Comma (`,`)
Escape Character	Double quotes (`"`) for values containing commas
Line Terminator	CRLF (`\r\n`)
Timezone	UTC

Data Type Formats

Data Type	Format	Example
Date	`YYYY-MM-DD`	`2026-01-15`
Datetime	`YYYY-MM-DD HH:MM`	`2026-01-15 14:30`
Decimal	`#.####` (4 decimal places)	`1234.5678`
UUID	36-character string	`a1b2c3d4-e5f6-7890-abcd-ef1234567890`
Boolean	`True` / `False`	`True`
Currency	ISO 4217	`ZAR`, `USD`, `EUR`
Country	ISO 3166-1 alpha-2	`ZA`, `US`, `GB`

Special Formatting Notes

Numeric Strings: Values intended to be interpreted as strings (not numbers) are prepended with a single quote (') to prevent spreadsheet applications from reformatting them.


'0012345678,Card Reference,...

Empty Values: Fields without data are represented as empty strings between delimiters:


field1,field2,,field4

Multi-Value Fields: Some fields (like bank_statement_line_item) may contain multiple values separated by commas within the quoted field:


"value1,value2,value3"

Recon file fields

The field tables that were here described Recon File Specification v1.0. The current file is v3.0, and almost every column was renamed between the two. purchase_id is now gateway_transaction_id, auth_code is now transaction_auth_code, and settlement_id and related_to_purchase no longer exist.

The current schema, the parsing rules and a version mapping are on Reconciliation files.

Markoff File

Description

The Markoff File contains transaction data that has been reconciled between Precium’s gateways and payment providers. This file represents all transaction actions within the reporting timeframe, regardless of settlement status.

Key Characteristics:

Settlement to Precium is not required for inclusion
Serves as a transaction activity log
Useful for tracking transactions before settlement data is available

Use Cases

Daily transaction activity monitoring
Pre-settlement transaction verification
Operational reporting
Transaction volume analysis

Field Specification

The Markoff File shares the same field structure as the Recon File across Merchant & Brand Identification, Transaction Identification, Precium Invoicing, Provider & Acquirer Information, Transaction Details, Settlement Information, Settlement Amounts, and Internal Revenue Tracking sections.

Note: The Markoff File does not include Bank Statement Reconciliation fields.

Exception File

Description

The Exception File contains transaction records that could not be reconciled successfully within the normal or expected reconciliation timeframe.

Key Characteristics:

Contains transactions with incomplete reconciliation
Data is populated on a best-effort basis (partial data expected)
May require manual investigation or subsequent automated processing

Use Cases

Identifying reconciliation issues
Manual investigation triggers
Tracking unresolved transactions

Field Specification

The Exception File includes all standard fields plus extended Precium Invoicing fields:

Field	Type	Format	Description
`precium_invoiced_vat`	decimal	`#.####`	VAT portion of invoiced amount
`precium_invoiced_incl_vat`	decimal	`#.####`	Total invoiced including VAT

It also uses service_type instead of card_type and projected_settlement_date instead of projected_clearance_date.

Working with Reconciliation Files

File Naming Convention

Reconciliation files follow a consistent naming pattern:


{report_type}_{merchant_id}_{date}.csv

Examples:


recon_a1b2c3d4-e5f6-7890-abcd-ef1234567890_2026-01-15.csv
markoff_a1b2c3d4-e5f6-7890-abcd-ef1234567890_2026-01-15.csv
exception_a1b2c3d4-e5f6-7890-abcd-ef1234567890_2026-01-15.csv

Importing into Spreadsheet Applications

When importing reconciliation files into Excel or Google Sheets:

Use UTF-8 encoding when importing
Treat UUID fields as text to prevent truncation
Note the single-quote prefix on numeric strings (Excel will display without the quote)
Set decimal columns to 4 decimal places for accurate monetary values

Sample CSV structure


merchant_name,merchant_id,brand_name,brand_id,settlement_acquiring_bank,settlement_bank_account_number,settlement_date,gateway_transaction_id,gateway_transaction_reference,transaction_amount,transaction_currency,transaction_type,...
Acme Corp,a1b2c3d4-e5f6-7890-abcd-ef1234567890,Acme Online,b2c3d4e5-f6a7-8901-bcde-f12345678901,ABSA,'62012345678,2026-09-22,a1b2c3d4-0001-4a1a-9e16-000000000001,'WWILJH1789639210276600001,40.0000,ZAR,PURCHASE,...

Full column list on Reconciliation files.

Daily Reconciliation Workflow

Handling refunds and disputes

A refund or a chargeback is a separate payment transaction with its own gateway_transaction_id, RRN and authorisation code, and its own row carrying a negative transaction_amount.


gateway_transaction_id,gateway_transaction_reference,transaction_type,transaction_amount
a1b2c3d4-0002-4a1a-9e16-000000000002,'EAQSFU1789639185638600002,PURCHASE,100.0000
a1b2c3d4-0003-4a1a-9e16-000000000003,'12442,REFUND,-30.0000

Recon v2.1 linked a refund back to its purchase through related_transaction_reference. That column does not exist in v3.0. Record the linkage on your side when you make the refund call.

Transaction types

`transaction_type`	Description
`PURCHASE`	Original payment transaction
`REFUND`	Full or partial refund
`dispute`	Chargeback or dispute
`reversal`	Transaction reversal

Settlement Amount Calculations

Understanding the relationship between settlement fields:


gross_settlement_amount
    - precium_settlement_deduction_incl_vat
    - settlement_provider_fees
    - acquirer_settlement_deduction_incl_vat
    ═════════════════════════════════════════
    = net_settlement_amount

Example:

Field	Amount
`gross_settlement_amount`	1,000.0000
`precium_settlement_deduction_incl_vat`	-25.0000
`settlement_provider_fees`	-15.0000
`acquirer_settlement_deduction_incl_vat`	-10.0000
`net_settlement_amount`	950.0000

Troubleshooting

Transaction Missing from Recon File

Possible Causes:

Settlement data not yet received from the provider
Transaction still in processing
Reconciliation exception occurred

Resolution:

Check the Markoff File to confirm the transaction was processed
Check the Exception File for reconciliation issues
Wait for the next reconciliation cycle
Contact support if the transaction remains missing after 3 business days

Amounts Don’t Match

Possible Causes:

Currency conversion differences
Fee calculation timing
Partial refund applied

Resolution:

Verify transaction and settlement currencies match
Match a refund to its purchase using the linkage you recorded at refund time
Review fee deduction fields

Exception File Contains Expected Transactions

Possible Causes:

Provider settlement file delayed
Bank statement not yet processed
Data mismatch requiring investigation

Resolution:

Transactions typically clear within 1-3 business days
Check subsequent Recon Files for resolution
Contact support for persistent exceptions

Data Validation Checklist

When processing reconciliation files, validate:

File encoding is UTF-8
All UUIDs are 36 characters
Dates follow YYYY-MM-DD format
Datetimes follow YYYY-MM-DD HH:MM format
Decimal values have up to 4 decimal places
Currency codes are valid ISO 4217
Country codes are valid ISO 3166-1 alpha-2
Boolean fields contain only True or False

API Access

Reconciliation files can be retrieved programmatically via the Precium API.

List Available Reports


curl -X GET "https://gate.reviopay.com/api/v1/reconciliation/reports/" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:


{
  "reports": [
    {
      "id": "rpt_abc123",
      "type": "recon",
      "date": "2026-01-15",
      "merchant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "file_name": "recon_a1b2c3d4_2026-01-15.csv",
      "download_url": "https://...",
      "created_at": "2026-01-16T06:00:00Z"
    }
  ]
}

Download Report


curl -X GET "https://gate.reviopay.com/api/v1/reconciliation/reports/{report_id}/download/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o report.csv

Filter by Date Range


curl -X GET "https://gate.reviopay.com/api/v1/reconciliation/reports/?start_date=2026-01-01&end_date=2026-01-15&type=recon" \
  -H "Authorization: Bearer YOUR_API_KEY"

Support

For questions about reconciliation reports or to report discrepancies:

Email: support@precium.com
Subject Line:[Recon] {Merchant Name} - {Issue Description}
Include: Merchant ID, affected date(s), purchase ID(s), and description of issue

Introduction

This documentation covers the structure, format, and interpretation of reconciliation report files to ensure accurate financial reporting and streamlined operations.

Report Types Overview

The reconciliation system produces three distinct report types, each serving a specific purpose in the reconciliation workflow:

Report Type	Purpose	Settlement Required
Recon File	Primary reconciliation output with full settlement data	Yes
Markoff File	Transaction activity reconciled between gateways and providers	No
Exception File	Transactions that could not be reconciled within expected timeframe	Partial data

When to Use Each Report

File Format Specifications

Common Rules

All reconciliation files follow these formatting standards:

Attribute	Specification
Encoding	UTF-8
Header Row	Always included
Delimiter	Comma (`,`)
Escape Character	Double quotes (`"`) for values containing commas
Line Terminator	CRLF (`\r\n`)
Timezone	UTC

Data Type Formats

Data Type	Format	Example
Date	`YYYY-MM-DD`	`2026-01-15`
Datetime	`YYYY-MM-DD HH:MM`	`2026-01-15 14:30`
Decimal	`#.####` (4 decimal places)	`1234.5678`
UUID	36-character string	`a1b2c3d4-e5f6-7890-abcd-ef1234567890`
Boolean	`True` / `False`	`True`
Currency	ISO 4217	`ZAR`, `USD`, `EUR`
Country	ISO 3166-1 alpha-2	`ZA`, `US`, `GB`

Special Formatting Notes

Numeric Strings: Values intended to be interpreted as strings (not numbers) are prepended with a single quote (') to prevent spreadsheet applications from reformatting them.


'0012345678,Card Reference,...

Empty Values: Fields without data are represented as empty strings between delimiters:


field1,field2,,field4

Multi-Value Fields: Some fields (like bank_statement_line_item) may contain multiple values separated by commas within the quoted field:


"value1,value2,value3"

Recon file fields

The current schema, the parsing rules and a version mapping are on Reconciliation files.

Markoff File

Description

Key Characteristics:

Settlement to Precium is not required for inclusion
Serves as a transaction activity log
Useful for tracking transactions before settlement data is available

Use Cases

Daily transaction activity monitoring
Pre-settlement transaction verification
Operational reporting
Transaction volume analysis

Field Specification

Note: The Markoff File does not include Bank Statement Reconciliation fields.

Exception File

Description

The Exception File contains transaction records that could not be reconciled successfully within the normal or expected reconciliation timeframe.

Key Characteristics:

Contains transactions with incomplete reconciliation
Data is populated on a best-effort basis (partial data expected)
May require manual investigation or subsequent automated processing

Use Cases

Identifying reconciliation issues
Manual investigation triggers
Tracking unresolved transactions

Field Specification

The Exception File includes all standard fields plus extended Precium Invoicing fields:

Field	Type	Format	Description
`precium_invoiced_vat`	decimal	`#.####`	VAT portion of invoiced amount
`precium_invoiced_incl_vat`	decimal	`#.####`	Total invoiced including VAT

It also uses service_type instead of card_type and projected_settlement_date instead of projected_clearance_date.

Working with Reconciliation Files

File Naming Convention

Reconciliation files follow a consistent naming pattern:


{report_type}_{merchant_id}_{date}.csv

Examples:


recon_a1b2c3d4-e5f6-7890-abcd-ef1234567890_2026-01-15.csv
markoff_a1b2c3d4-e5f6-7890-abcd-ef1234567890_2026-01-15.csv
exception_a1b2c3d4-e5f6-7890-abcd-ef1234567890_2026-01-15.csv

Importing into Spreadsheet Applications

When importing reconciliation files into Excel or Google Sheets:

Use UTF-8 encoding when importing
Treat UUID fields as text to prevent truncation
Note the single-quote prefix on numeric strings (Excel will display without the quote)
Set decimal columns to 4 decimal places for accurate monetary values

Sample CSV structure


merchant_name,merchant_id,brand_name,brand_id,settlement_acquiring_bank,settlement_bank_account_number,settlement_date,gateway_transaction_id,gateway_transaction_reference,transaction_amount,transaction_currency,transaction_type,...
Acme Corp,a1b2c3d4-e5f6-7890-abcd-ef1234567890,Acme Online,b2c3d4e5-f6a7-8901-bcde-f12345678901,ABSA,'62012345678,2026-09-22,a1b2c3d4-0001-4a1a-9e16-000000000001,'WWILJH1789639210276600001,40.0000,ZAR,PURCHASE,...

Full column list on Reconciliation files.

Daily Reconciliation Workflow

Handling refunds and disputes

A refund or a chargeback is a separate payment transaction with its own gateway_transaction_id, RRN and authorisation code, and its own row carrying a negative transaction_amount.


gateway_transaction_id,gateway_transaction_reference,transaction_type,transaction_amount
a1b2c3d4-0002-4a1a-9e16-000000000002,'EAQSFU1789639185638600002,PURCHASE,100.0000
a1b2c3d4-0003-4a1a-9e16-000000000003,'12442,REFUND,-30.0000

Recon v2.1 linked a refund back to its purchase through related_transaction_reference. That column does not exist in v3.0. Record the linkage on your side when you make the refund call.

Transaction types

`transaction_type`	Description
`PURCHASE`	Original payment transaction
`REFUND`	Full or partial refund
`dispute`	Chargeback or dispute
`reversal`	Transaction reversal

Settlement Amount Calculations

Understanding the relationship between settlement fields:


gross_settlement_amount
    - precium_settlement_deduction_incl_vat
    - settlement_provider_fees
    - acquirer_settlement_deduction_incl_vat
    ═════════════════════════════════════════
    = net_settlement_amount

Example:

Field	Amount
`gross_settlement_amount`	1,000.0000
`precium_settlement_deduction_incl_vat`	-25.0000
`settlement_provider_fees`	-15.0000
`acquirer_settlement_deduction_incl_vat`	-10.0000
`net_settlement_amount`	950.0000

Troubleshooting

Transaction Missing from Recon File

Possible Causes:

Settlement data not yet received from the provider
Transaction still in processing
Reconciliation exception occurred

Resolution:

Check the Markoff File to confirm the transaction was processed
Check the Exception File for reconciliation issues
Wait for the next reconciliation cycle
Contact support if the transaction remains missing after 3 business days

Amounts Don’t Match

Possible Causes:

Currency conversion differences
Fee calculation timing
Partial refund applied

Resolution:

Verify transaction and settlement currencies match
Match a refund to its purchase using the linkage you recorded at refund time
Review fee deduction fields

Exception File Contains Expected Transactions

Possible Causes:

Provider settlement file delayed
Bank statement not yet processed
Data mismatch requiring investigation

Resolution:

Transactions typically clear within 1-3 business days
Check subsequent Recon Files for resolution
Contact support for persistent exceptions

Data Validation Checklist

When processing reconciliation files, validate:

File encoding is UTF-8
All UUIDs are 36 characters
Dates follow YYYY-MM-DD format
Datetimes follow YYYY-MM-DD HH:MM format
Decimal values have up to 4 decimal places
Currency codes are valid ISO 4217
Country codes are valid ISO 3166-1 alpha-2
Boolean fields contain only True or False

API Access

Reconciliation files can be retrieved programmatically via the Precium API.

List Available Reports


curl -X GET "https://gate.reviopay.com/api/v1/reconciliation/reports/" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:


{
  "reports": [
    {
      "id": "rpt_abc123",
      "type": "recon",
      "date": "2026-01-15",
      "merchant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "file_name": "recon_a1b2c3d4_2026-01-15.csv",
      "download_url": "https://...",
      "created_at": "2026-01-16T06:00:00Z"
    }
  ]
}

Download Report


curl -X GET "https://gate.reviopay.com/api/v1/reconciliation/reports/{report_id}/download/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o report.csv

Filter by Date Range


curl -X GET "https://gate.reviopay.com/api/v1/reconciliation/reports/?start_date=2026-01-01&end_date=2026-01-15&type=recon" \
  -H "Authorization: Bearer YOUR_API_KEY"

Support

For questions about reconciliation reports or to report discrepancies:

Email: support@precium.com
Subject Line:[Recon] {Merchant Name} - {Issue Description}
Include: Merchant ID, affected date(s), purchase ID(s), and description of issue