HISAB — Autonomous Payment Gateway Reconciliation & Finance Controller

HISAB (Hindi: हिसाब — Ledger & Account Reconciliation) is a production-grade Autonomous Finance Controller engineered for Indian merchants operating on payment gateways (e.g. Razorpay) and banking rails (NEFT / RTGS / IMPS).

It combines 4-tier deterministic matching, minor-unit integer arithmetic, seven financial assurance controls, forensic double-loss detection, interactive "Prove It" evidence graphs, a safe auto-resolution policy gate, and an immutable SHA-256 hash-chained audit ledger.

---

Key Highlights & Architectural Features

1. Deterministic Minor-Unit Arithmetic Engine (packages/domain/):

   • Zero floating-point rounding errors. All monetary math operates strictly in minor units (paise) with symmetric half-up rounding.
   • Built-in MDR fee calculator (2% Cards, 1.8% Netbanking, 0% UPI) and 18% GST invoices.
   • Non-reversible fee validation on refunds per standard acquiring gateway policy (RULE_REFUND_02).
   • Section 194-O TDS compliance amended to statutory 0.1% rate per Finance Act 2024.

2. The Four-Tier Matching Ladder (packages/matching/):

   • Tier 1 (Exact): Matches unique transaction primary keys and exact UTR references.
   • Tier 2 (Constraint-Based): Time-window proximity ($T \text{ to } T+3\text{ days}$) and fee-adjusted amount matching.
   • Tier 3 (Fuzzy String & Narration): Levenshtein distance and regex parsing on raw unformatted bank narrations (CMS/RAZORPAY/...).
   • Batch Reconstruction: Bounded subset-sum optimization that reconstructs unmapped transactions to resolve settlement batch deficits.

3. Signature Feature #1: Forensic Double-Loss Risk Detector (packages/controls/):

   • Detects compounded outflow risk when a merchant manually refunds a customer while an independent card chargeback dispute is filed simultaneously on the same commercial order.
   • Computes exact total outflow ($₹72\text{k refund} + ₹72.5\text{k dispute} = ₹144.5\text{k}$ total exposure on a ₹72k sale).
   • Enforces mandatory human escalation with an automated chronological timeline and representment defense pack.

4. Signature Feature #2: "Prove It" Interactive Evidence Graph (packages/controls/):

   • Generates interactive, clickable relationship graphs linking: $$\text{Order} \longrightarrow \text{Payment} \longrightarrow \text{Refund / Dispute} \longrightarrow \text{Settlement} \longrightarrow \text{Bank Credit}$$
   • Every edge carries verifiable invariant proof points (✓ UTR matches, ✓ fee schedule verified, ✓ 0 rail leakage).

5. Safe Auto-Resolution Policy Gate (packages/controls/policy_gate.py):

   • Enforces deterministic safety rules: auto-resolves allowlisted low-exposure discrepancies ($\le ₹5,000$) with $\ge 2$ proof signals.
   • Strictly blocks automated clearance of double-loss or active dispute cases.

6. Immutable Cryptographic Audit Ledger ($H_1 \to H_2 \to H_3$) (packages/domain/audit_ledger.py):

   • Tamper-evident non-repudiation ledger using SHA-256 hash chaining.
   • Includes real-time one-click cryptographic chain verification (POST /api/audit/verify).

7. Three-Way Comparative Evaluation Benchmark (packages/evaluation/):

   • Rigorously benchmarks Baseline A (Rules Only), Baseline B (Naive LLM), and Baseline C (HISAB) over identical ground-truth datasets.
   • Proves 100% Precision, 100% Recall, 100% Double-Loss Detection, 0 Hallucinations, 0 Math Errors, and 8.5ms latency.

8. Razorpay-Themed Fintech Control-Room UI (apps/web/):

   • Responsive Next.js 14 frontend with Razorpay Light Mode (Royal Blue & Pure White) and Razorpay Dark Mode (Midnight Navy).
   • Interactive settlement waterfall clearance chart, double-loss flow diagram, and live audit ledger verifier.

---

Quickstart & Installation

Prerequisites

• Python 3.12+ (or uv)
• Node.js 18+ & npm

1. Setup Python Backend Environment

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

2. Seed Demo Merchant Data

# Generate 500+ realistic records for Nova Commerce Pvt Ltd (₹49.54L turnover) with controlled anomalies
.venv/bin/python scripts/seed_data.py --records 500 --corrupt --seed-db --export-fixtures

3. Run Live Interactive Demo Walkthrough

.venv/bin/python scripts/demo_walkthrough.py

4. Run 3-Way Comparative Benchmark

.venv/bin/python scripts/run_benchmark.py --records 500 --seed 101

5. Run Automated Test Suite (101 Tests)

.venv/bin/pytest --cov=packages --cov=apps.api tests/ -v

---

Running the Web Application

Start FastAPI Backend Service (Port 8000)

.venv/bin/python -m uvicorn apps.api.main:app --host 0.0.0.0 --port 8000 --reload

API Documentation available at: http://localhost:8000/docs

Start Next.js Frontend Control Room (Port 3000)

npm --prefix apps/web run dev

Dashboard available at: http://localhost:3000

---

Core API Endpoints Overview

Endpoint	Method	Description
/healthz	GET	Service health check
/api/reconcile/summary	GET	Executive turnover & settlement metrics
/api/reconcile/run	POST	Executes full end-to-end reconciliation pipeline
/api/reconcile/settlements	GET	Paginated settlement batches with bank clearance status
/api/controls/summary	GET	Status matrix across all Seven Financial Controls
/api/controls/double-loss	GET	Active double-loss alerts with forensic timelines
/api/controls/exceptions	GET	Filterable exceptions list
/api/controls/exceptions/{id}/resolve	POST	Resolves exception with human / policy justification
/api/controls/exceptions/{id}/escalate	POST	Escalates exception to senior finance controller
/api/evidence/{payment_id}	GET	Returns "Prove It" interactive evidence graph dossier
/api/audit/entries	GET	Paginated immutable cryptographic audit entries
/api/audit/verify	POST	Cryptographically verifies SHA-256 audit hash chain
/api/benchmark/latest	GET	Latest 3-way comparative benchmark scorecard
/api/benchmark/run	POST	Triggers fresh live comparative benchmark run

---

Technical Documentation

• Hostile QA Defense & Invariants Guide: docs/HOSTILE_QA.md
• Technical Architecture Specification: docs/ARCHITECTURE.md
• Empirical Evaluation Benchmark Report: docs/EVALUATION.md
• Domain Accounting Rules: docs/DOMAIN_RULES.md

---

Project Structure

├── apps/
│   ├── api/                     # FastAPI backend application & REST routers
│   │   ├── main.py              # App entry point, CORS, lifespan handler
│   │   ├── dependencies.py      # Database session injection
│   │   └── routes/              # Reconciliation, controls, evidence, audit, benchmark routes
│   └── web/                     # Next.js 14 control-room frontend
│       ├── src/app/             # Layouts, globals.css, master dashboard page
│       └── src/components/      # Razorpay-themed interactive charts & viewers
├── packages/
│   ├── domain/                  # Minor-unit money math, fee models, DB schemas, audit ledger
│   ├── matching/                # Tier 1-3 tiered matchers & subset-sum batch reconstruction
│   ├── controls/                # The 7 controls, double-loss forensics, evidence graph, policy gate
│   ├── agent/                   # Tool-using AI Controller & deterministic fallback engine
│   └── evaluation/              # Synthetic generator, controlled corruptor, benchmark runner
├── scripts/
│   ├── seed_data.py             # Database seeding & Razorpay CSV exporter CLI
│   ├── demo_walkthrough.py      # Live interactive demo walkthrough CLI
│   └── run_benchmark.py         # 3-Way comparative evaluation benchmark CLI
├── docs/                        # Technical architecture, Hostile QA, domain rules, evaluation
└── tests/                       # 101 unit and end-to-end integration tests (97% coverage)