# Demo Cheat Sheet — Clearing, Recon & General Ledger

## The big picture (say this first)

When a customer pays by card, three things happen at three different times:
1. **Authorization** (instant) — "approve or decline" — not part of this module.
2. **Clearing** (batch, end of day) — the card network sends/receives a **file** confirming exactly which transactions happened and for how much.
3. **Settlement** — the actual money moves, based on what cleared.

**Clearing & Settlement = everything that happens after the swipe, to reconcile and move money.**

**One-line demo narrative, in order:**
Files (file comes in / gets uploaded) → Batches (track its processing status) → Exceptions (fix anything that didn't reconcile) → Dashboard (the summary of all of it) → General Ledger (the accounting record of the money movement).

---

## Clearing Dashboard (`/admin/clearing`)

**What's on it:** 4 stat cards (Total Batches, Visa TC-33 Batches, Mastercard IPM Batches, Open Exceptions), "Batches by Status," "Open Exceptions by Type," and a "Recent Batches" table.

**What it's for:** One-glance answer to "did today's Visa/Mastercard clearing files land, and did they match cleanly?" — so ops doesn't have to open three screens.

**Say:** "This is our control tower — one look tells us how many clearing files landed today and whether anything needs attention."

---

## Clearing Batches (`/admin/clearing/batches`)

**What's on it:**
- "Generate Outbound File" panel — builds & submits a Mastercard presentment file for a chosen bank/date (this is the *outbound* direction — us sending a file to Mastercard).
- Filters: Source / Direction / Status.
- Table: Filename, Source, Direction, Batch Date, Records, **Matched**, Status, "View records," and a "Rollback" action (audit-trail marker only — doesn't reverse postings).

**What it's for:** The operational lifecycle tracker. Inbound files go `received → processing → matched/error`; outbound files go `generated → submitted/error`. Answers "where is this batch right now?"

**Say:** "Every clearing file we receive or generate shows up here with its live status, so ops can spot anything stuck or errored instead of completing."

---

## Clearing Files (`/admin/clearing/files`)

**What's on it:**
- Upload widget — drag/drop a Visa TC-33 or Mastercard IPM file; it's parsed and reconciled on upload.
- "Clearing File Registry" table: Filename, Network, Direction, Batch Date, **Size**, Records, Matched, Status, Processed timestamp.

**How it differs from Batches:** Files is the **file-level** view (the physical file — did it arrive, parse OK, how big, when processed). Batches is the **reconciliation outcome** view (matched vs. exceptions, rollback). If asked "isn't this the same as Batches?" → "Files is the intake/upload point, Batches is where you track and act on the result."

---

## Clearing Exceptions (`/admin/clearing/exceptions`)

**What's on it:** Filters (Status: open/investigating/resolved; Type). Table: Type, Clearing ID, Transaction ID, Merchant, Amount, Description, Status, and a **Resolve** action with resolution notes.

**What the exception types mean (your dashboard showed 61 open):**
- **Record rejected (43)** — decoded fine but failed to process/save on our side.
- **Unmatched (18)** — the network says a transaction happened but we have no matching record locally.
- Others possible: `unparseable` (bytes didn't decode), `amount_mismatch` (matched but amount disagrees), `duplicate` (already processed).

**Say:** "Nothing is ever silently dropped — anything that doesn't reconcile automatically lands here, gets investigated, and is marked resolved with notes. That's our audit trail."

---

## General Ledger (`/admin/ledger`)

**Concept:** The master accounting book. Every financial event (settlement paid, fee earned, adjustment) is recorded as a **journal entry** using **double-entry bookkeeping** — every entry has a debit side and a credit side, and they must always be equal.

**Example:** $100 transaction settles, $5 interchange fee taken:
- Debit: Bank/Clearing account **$100**
- Credit: Merchant Payable **$95**
- Credit: Interchange Fee Income **$5**

($100 debit = $95 + $5 credit — balanced.)

**What's on the screen:**
- **Trial Balance** — sums every account's debits/credits; shows "Balanced" / "Out of balance." This is the fundamental accounting sanity check.
- **Chart of Accounts** — the defined accounts (Asset / Liability / Income / Expense / Equity), pre-seeded — **will show data**.
- **Journal Entries** — individual postings with date, description, and debit/credit lines.

**⚠️ Heads up for tonight:** This GL is real and fully built, but **not yet wired into the live settlement-approval flow** — live settlements currently post through a simpler per-merchant ledger (the separate "Merchant Ledger" page). So **Trial Balance and Journal Entries will likely show empty** ("No journal activity posted yet") — that's expected, not a bug.

**If asked why it's empty:** *"This is our new standardized double-entry accounting layer — built and validated, and we're in the process of cutting live settlement postings over to it."*

---

## Quick reference table

| Screen | One-line purpose |
|---|---|
| Clearing Dashboard | Summary/control tower |
| Clearing Files | Raw file intake & upload |
| Clearing Batches | Processing status & lifecycle per file |
| Clearing Exceptions | Manual review queue for anything unreconciled |
| General Ledger | Double-entry accounting record of money movement (not live-wired yet) |