# Reconciliation (/docs/server-to-server/reconciliation)

## Introduction [#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 [#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 [#when-to-use-each-report]

```mermaid
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 [#file-format-specifications]

### Common Rules [#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-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 [#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.

```text
'0012345678,Card Reference,...
```

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

```text
field1,field2,,field4
```

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

```text
"value1,value2,value3"
```

## Recon file fields [#recon-file-fields]

<Callout type="warning">
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](/docs/reconciliation).
</Callout>

## Markoff File [#markoff-file]

### Description [#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 [#use-cases]

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

### Field Specification [#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.

<Callout type="info">
Note: The Markoff File does not include Bank Statement Reconciliation fields.
</Callout>

## Exception File [#exception-file]

### Description [#description-1]

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 [#use-cases-1]

- Identifying reconciliation issues
- Manual investigation triggers
- Tracking unresolved transactions

### Field Specification [#field-specification-1]

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 [#working-with-reconciliation-files]

### File Naming Convention [#file-naming-convention]

Reconciliation files follow a consistent naming pattern:

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

Examples:

```text
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 [#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 [#sample-csv-structure]

```text
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](/docs/reconciliation).

### Daily Reconciliation Workflow [#daily-reconciliation-workflow]

```mermaid
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 [#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`.

```text
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
```

<Callout type="warning">
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.
</Callout>

**Transaction types**

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

### Settlement Amount Calculations [#settlement-amount-calculations]

Understanding the relationship between settlement fields:

```text
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 [#troubleshooting]

### Transaction Missing from Recon File [#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 [#amounts-dont-match]

**Possible Causes:**

- Currency conversion differences
- Fee calculation timing
- Partial refund applied

**Resolution:**

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

### Exception File Contains Expected Transactions [#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 [#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 [#api-access]

Reconciliation files can be retrieved programmatically via the Precium API.

### List Available Reports [#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 [#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 [#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 [#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