Reconciliation

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:

‍

‍

When to Use Each Report

flowchart TD
    A[Transaction Processed] --> B{Reconciled with Provider?}
    B -->|Yes| C[MARKOFF FILE - Transaction activity]
    B -->|No| D[Not in any report yet]
    C --> E{Settlement Data Available?}
    E -->|Yes| F[RECON FILE - Ready for settlement]
    E -->|No| G[EXCEPTION FILE - Requires investigation]

‍

File Format Specifications

Common Rules

All reconciliation files follow these formatting standards:

‍

‍

Data Type Formats

‍

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

Description

The Recon File is the primary output of the reconciliation process. It contains transaction-level data that has been successfully reconciled with settlement data and is the authoritative dataset for a given reconciliation cycle.

‍

Key Characteristics:

• Transactions are ready for settlement in an upcoming settlement cycle
• Contains complete transaction and settlement information
• Includes bank statement reconciliation data where available

‍

Use Cases

• Daily settlement reconciliation
• Financial reporting and accounting
• Audit trail documentation
• Fee analysis and verification

‍

Field Specification

Merchant & Brand Identification

‍

Transaction Identification

‍

Precium Invoicing

‍

Provider & Acquirer Information

‍

Transaction Details

‍

Settlement Information

‍

Settlement Amounts

‍

Internal Revenue Tracking

‍

Bank Statement Reconciliation

‍

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:

‍

‍

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:

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

‍

Sample CSV Structure

merchant_id,merchant_name,brand_id,brand_name,purchase_id,related_to_purchase,purchase_reference,status,type,paid_at,...
a1b2c3d4-e5f6-7890-abcd-ef1234567890,Acme Corp,b2c3d4e5-f6a7-8901-bcde-f12345678901,Acme Online,...

‍

Daily Reconciliation Workflow

flowchart LR
    subgraph T0["T+0 Morning"]
        A1[Transactions processed]
        A2[Data captured]
    end
    subgraph Night["T+0 to T+1 Overnight"]
        B1[Gateway-provider recon]
        B2[Settlement processing]
        B3[Bank statement matching]
    end
    subgraph T1["T+1 Morning"]
        C1[Recon File]
        C2[Markoff File]
        C3[Exception File]
    end
    subgraph Ongoing["Ongoing"]
        D1[Investigation]
        D2[Manual recon]
        D3[Resolution]
    end
    T0 --> Night --> T1 --> Ongoing
    D3 -.->|Resolved| C1

‍

Handling Refunds and Disputes

Refunds and disputes are linked to their original transactions via the related_to_purchase field:

‍

purchase_id,related_to_purchase,type,transaction_amount
original-purchase-uuid,,purchase,1000.0000
refund-purchase-uuid,original-purchase-uuid,refund,-500.0000

‍

Identifying Transaction Types:

‍

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:

‍

Troubleshooting

Transaction Missing from Recon File

Possible Causes:

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

‍

Resolution:

1. Check the Markoff File to confirm the transaction was processed
2. Check the Exception File for reconciliation issues
3. Wait for the next reconciliation cycle
4. 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:

1. Verify transaction and settlement currencies match
2. Check related_to_purchase for linked refunds
3. 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:

1. Transactions typically clear within 1-3 business days
2. Check subsequent Recon Files for resolution
3. 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

BASH

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

‍

Response:

JSON

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

BASH

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

BASH

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