# Reconciliation (/docs/payment-orchestration/reconciliation)

<Callout type="info">
Note: The reconciliation service is currently available for card payments only. Support for additional payment methods will be added in future releases.
</Callout>

## Overview [#overview]

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 card transactions through the complete payment lifecycle, from authorisation to bank settlement.

## Report Types [#report-types]

The reconciliation system produces three distinct report types:

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

### Report Selection Guide [#report-selection-guide]

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

## File Format [#file-format]

### Common Specifications [#common-specifications]

| Attribute | Value |
|---|---|
| Encoding | UTF-8 |
| Delimiter | Comma (`,`) |
| Header Row | Always included |
| Line Terminator | CRLF |
| Timezone | UTC |

### Data Formats [#data-formats]

| Type | Format | Example |
|---|---|---|
| Date | `YYYY-MM-DD` | `2026-01-15` |
| Datetime | `YYYY-MM-DD HH:MM` | `2026-01-15 14:30` |
| Decimal | `#.####` | `1234.5678` |
| UUID | 36 characters | `a1b2c3d4-e5f6-...` |
| Boolean | `True` / `False` | `True` |
| Currency | ISO 4217 | `ZAR` |
| Country | ISO 3166-1 alpha-2 | `ZA` |

## 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>

## Accessing Reports [#accessing-reports]

### SFTP Delivery [#sftp-delivery]

Reconciliation reports are delivered automatically via SFTP to your designated location:

- **Delivery Method:** Secure SFTP transfer
- **Location:** Agreed upon during merchant onboarding
- **Schedule:** Daily, typically available by 06:00 UTC
- **Format:** CSV files as specified in this document

Contact your account manager to configure or update your SFTP delivery settings.

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

Reports follow this naming pattern:

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

Example: `recon_550e8400-e29b-41d4-a716-446655440000_2026-01-15.csv`

### Report Availability [#report-availability]

| Report Type | Delivery | Contents |
|---|---|---|
| Recon File | T+2 morning | Settled transactions ready for reconciliation |
| Markoff File | T+1 morning | All reconciled transactions (settlement not required) |
| Exception File | T+1 morning | Unreconciled transactions requiring review |

## Reconciliation Workflow [#reconciliation-workflow]

```mermaid
flowchart LR
    subgraph T0["T+0 Morning"]
        direction TB
        A1[Transactions processed]
        A2[Data captured]
    end

    subgraph Night["T+0 → T+1 Overnight"]
        direction TB
        B1[Gateway-provider recon]
        B2[Settlement processing]
        B3[Bank statement matching]
    end

    subgraph T1["T+1 Morning"]
        direction TB
        C1["ð Recon File"]
        C2["ð Markoff File"]
        C3["ð Exception File"]
    end

    T0 --> Night --> T1
```

## Settlement Timing [#settlement-timing]

Settlement timing varies based on transaction characteristics and acquirer processing:

### Standard Settlement Timeline [#standard-settlement-timeline]

| Transaction Type | Typical Settlement | Notes |
|---|---|---|
| 3D Secure authenticated | T+2 | Standard processing |
| High-risk transactions | T+3 or longer | Extended fraud department clearance |

### Important Considerations [#important-considerations]

<Callout type="info">
Acquirer Fraud Review: Non-3DS transactions may experience delayed settlement (T+2 or T+3) as acquirers route these transactions through their fraud departments for additional clearance before releasing funds. This is standard industry practice for transactions without strong customer authentication.
</Callout>

### Factors Affecting Settlement Time [#factors-affecting-settlement-time]

- **3DS Status:** Authenticated transactions typically settle faster
- **Transaction Amount:** Higher-value transactions may undergo additional review
- **Merchant Risk Profile:** Settlement timing may vary by merchant category
- **Acquirer Policies:** Each acquirer has specific fraud review procedures
- **Public Holidays:** Settlement may be delayed around bank holidays

### Projected vs Actual Clearance [#projected-vs-actual-clearance]

The `projected_clearance_date` field in the Recon File provides an estimate, while `clearance_date` reflects actual bank clearance. Discrepancies may occur due to:

- Acquirer fraud department holds
- Bank processing delays
- Weekend/holiday adjustments

## Settlement Amount Calculation [#settlement-amount-calculation]

Understanding how net settlement is calculated:

```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 | R1,000.00 |
| Precium Fee | -R25.00 |
| Provider Fee | -R15.00 |
| Acquirer Fee | -R10.00 |
| **Net Settlement** | **R950.00** |

## Handling refunds [#handling-refunds]

A refund is a separate payment transaction. It gets its own
`gateway_transaction_id`, its own RRN and its own authorisation code, and it
appears as its own row with `transaction_type` of `REFUND` and a **negative**
`transaction_amount`.

<Callout type="warning">
Recon v2.1 carried a `related_transaction_reference` column linking a refund
back to the original purchase. **That column does not exist in v3.0.** If you
need the linkage, record it on your side when you make the refund call. See
[Reconciliation files](/docs/reconciliation).
</Callout>

## Exception Handling [#exception-handling]

Transactions in the Exception File require investigation:

**Common Exception Causes:**

- Settlement data not received from the provider
- Bank statement matching failure
- Data discrepancy between systems

**Resolution Process:**

1. Check the Exception File daily
2. Investigate unmatched transactions
3. Transactions auto-resolve when settlement data arrives
4. Contact support for persistent exceptions (>3 business days)

## Integration Best Practices [#integration-best-practices]

1. **Automate Downloads:** Schedule daily report downloads
2. **Match references:** use `gateway_transaction_reference` to link to your orders
3. **Monitor Exceptions:** Set up alerts for exception file entries
4. **Reconcile Daily:** Process files daily for timely issue detection
5. **Archive Reports:** Retain reports for audit purposes

## Coming Soon [#coming-soon]

The following payment methods will be added to reconciliation:

- Ozow
- Capitec Pay
- DebiCheck
- Debit Orders

Contact your account manager for timeline updates.

## Support [#support]

For reconciliation questions or discrepancies:

**Email:** support@precium.com

**Subject:**`[Recon] {Merchant Name} - {Issue Description}`

**Include:**

- Merchant ID
- Affected date(s)
- Purchase ID(s)
- Description of discrepancy