# Demo Cheat Sheet — Reconciliation Module

## Why there are multiple "types" of reconciliation

Money moves through several hops before it's truly done:

**Capture → Switch/QR confirmation → Network clearing (Visa/Mastercard) → Bank payout to merchant**

Each hop can break independently. Instead of one big "something's wrong" bucket, there's a dedicated reconciliation screen per leg, so ops can pinpoint exactly which hop failed rather than guessing.

---

## The four reconciliation types

### 1. Transaction Reconciliation (`/admin/reconciliation/transaction`)
**Leg:** Capture ↔ Switch/QR settlement dump — the finest-grain, per-transaction view.

**What it checks:** Every `core_transaction` you captured, matched against the settlement dump the switch/QR network later sends back.

**States shown:** Reconciled (matched), Awaiting Dump (not seen yet), Exception Hold, Risk/Chargeback Hold.

**Example:** Customer pays ₹1,000 on your platform. Until the switch's end-of-day dump confirms that exact transaction, it sits "Awaiting Dump." Once found, it flips to "Reconciled."

---

### 2. Settlement Reconciliation (`/admin/reconciliation/settlement`)
**Leg:** Payout ↔ Bank confirmation.

**What it checks:** What you instructed the bank to pay a merchant (payout batch) against what the bank actually confirmed happened (`bank_confirmation_records`).

**Example:** You instruct a payout of AED 10,000 to a merchant. The bank's confirmation file comes back showing AED 9,800. That's an "Amount Mismatch," flagged here.

---

### 3. Clearing Reconciliation (`/admin/reconciliation/clearing`)
**Leg:** Network clearing file ↔ your transactions.

**What it checks:** Matches Visa/Mastercard's clearing file records (by ARN/RRN + amount) against your own `core_transactions`. This is effectively the same matching engine behind the Clearing module's exceptions, surfaced here as one of the reconciliation legs for a unified cross-leg view.

**Example:** Visa's TC-33 file says ARN X was billed $50. If no core transaction matches that ARN + amount, it becomes a clearing exception.

---

### 4. Network Reconciliation (`/admin/reconciliation/network`)
**Leg:** Expected vs. actual settlement sync — totals-level, not per-transaction.

**What it checks:** Whether the job that syncs settlement data actually inserted what it expected to (`sync_log`: expected count/amount vs. inserted), plus a rollup of cleared volume per network.

**Example:** A sync run expected to pull 500 settled transactions worth $50k for the day; if only 480 got inserted, that run is flagged "Mismatch."

---

## Recon Exceptions (grouped, under "Exceptions")

The unmatched/broken records from all of the above, split by cause so ops can triage faster:
- **Recon Exceptions** — the general queue
- **Unmatched Transactions** — no counterpart found at all
- **Missing Transactions** — expected but never arrived
- **Duplicate Transactions** — same record seen twice
- **Amount Mismatches** — matched, but the amounts disagree

---

## File Tracker vs. File History — the distinction that trips people up

| | File Tracker | File History |
|---|---|---|
| **Path** | `/admin/reconciliation/files` | `/admin/reconciliation/files/history` |
| **Granularity** | One row **per file** | One row **per event** |
| **Shows** | Current status registry, tabbed by source (**Alipay / Acquirer-Switch / AANI**), with an upload button | Chronological log: uploaded → processing → processed/failed/reprocessed, each with actor + error detail |
| **Answers** | "What files exist and what's their latest status right now?" | "What exactly happened to this file over time, and who did it?" (compliance/audit-trail view) |

**Example:** A file can appear once in Tracker ("Status: Failed") but show 3 rows in History — uploaded → processing → failed — telling you it failed on the second attempt, not the first, and who reprocessed it.

*(There are two further "Files" group items — File Processing and Processing Errors — not detailed here; ask if you need them covered before the demo.)*

---

## Quick reference table

| Screen | One-line purpose |
|---|---|
| Transaction Reconciliation | Per-transaction: capture vs. switch/QR dump |
| Settlement Reconciliation | Payout batches vs. bank confirmations |
| Clearing Reconciliation | Network clearing file vs. your transactions |
| Network Reconciliation | Expected vs. actual settlement sync totals, by network |
| Recon Exceptions (+ sub-queues) | Triage queues for unmatched/missing/duplicate/mismatched records |
| File Tracker | Current-state registry of settlement dump files, by source |
| File History | Chronological audit log of every file event |