Reconciliation

Reconciliation verifies that wallet balances match ledger entries, ensuring data integrity and detecting discrepancies.

What is Reconciliation?

Compares two sources of truth:

Source	Description
Wallet Balance	Denormalized field on User/Vendor model
Ledger Balance	Sum of posted ledger entries (source of truth)

Goal: Wallet Balance = Ledger Balance

---

Why Reconcile?

Purpose	Benefit
Data Integrity	Detect database corruption or tampering
Audit Compliance	Meet regulatory verification requirements
Bug Detection	Catch programming errors
Fraud Detection	Identify unauthorized balance modifications

---

Reconciliation Types

Type	Description
User Balance	Verify single user wallet vs ledger
Vendor Balance	Verify single vendor wallet vs ledger
All Users	Reconcile all user balances
All Vendors	Reconcile all vendor balances
Trial Balance	Verify total debits = total credits

---

Daily Automated Reconciliation

Runs automatically at 2 AM daily.

Tasks Performed:

1. Auto-post pending entries > 30 minutes old
2. Verify all user balances
3. Verify all vendor balances
4. Generate and verify trial balance
5. Create reconciliation record
6. Alert on critical discrepancies

---

Discrepancy Severity Levels

Severity	Difference	Action
LOW	E0.01 - E1.00	Log only, auto-correct
MEDIUM	E1.01 - E10.00	Alert admin, review
HIGH	E10.01 - E100.00	Alert admin, freeze account
CRITICAL	> E100.00	Alert, freeze, escalate

---

Handling Discrepancies

Auto-Correct (< E1.00)

For small rounding errors:

1. Find discrepancies < E1.00
2. Create manual adjustment journal entry
3. Update wallet balance to match ledger
4. Log correction in audit trail

Manual Correction (E1.00 - E100.00)

For larger discrepancies:

1. Calculate difference
2. Investigate cause
3. Create manual adjustment with approval
4. Update wallet balance
5. Notify admin of correction

Investigation Required (> E100.00)

For critical discrepancies:

1. Freeze account - Prevent further transactions
2. Review audit log - Find cause
3. Check ledger entries - Verify all entries posted
4. Check wallet transactions - Find orphaned transactions
5. Manual correction - After investigation complete

---

Trial Balance

Lists all accounts with their debit/credit totals.

Account Code	Account Name	Debit	Credit
1110	User Wallets	E50,000	-
1120	Vendor Wallets	E25,000	-
4110	Fee Revenue	-	E2,500
...	...	...	...
TOTAL		E75,000	E75,000

If debits ≠ credits, there's a fundamental accounting error.

---

Reconciliation Records

Each run is recorded:

Field	Description
reconciliationId	Unique identifier (REC-XXXXXX)
startedAt	Start timestamp
completedAt	End timestamp
status	IN_PROGRESS, COMPLETED, FAILED
scope	USER, VENDOR, TRIAL_BALANCE, FULL
results	Counts, discrepancies, trial balance

---

Account Statements

Generate detailed transaction history for users/vendors:

Fields Included:

• Opening balance
• Closing balance
• Transaction entries with descriptions
• Running balance
• Counterparty names

Export Formats: CSV, HTML

---

Monitoring and Alerts

Severity	Alert Method
LOW	Log only
MEDIUM	Email to admin
HIGH	Email + Slack
CRITICAL	Email + Slack + Phone

---

Best Practices

1. Run daily reconciliation at 2 AM (low traffic time)
2. Auto-correct small discrepancies (< E1.00) to reduce noise
3. Alert on medium/high discrepancies immediately
4. Freeze accounts with critical discrepancies
5. Investigate thoroughly before manual corrections
6. Document corrections in audit trail with reasons

---

Related Documentation

• Integration Guide
• Troubleshooting
• Ledger Service