Mansi-Yelkar/Reconcile-Razorpay

1---2title: Reconcile Razorpay3emoji: ⚡4colorFrom: green5colorTo: yellow6sdk: gradio7app_file: app.py8pinned: false9---10 11# Reconcile — AI Revenue Recovery Orchestrator12 13> **Razorpay AI Buildathon — Track 3: AI Revenue Recovery**  14> **Tagline:** *Detect revenue leakage. Diagnose the cause. Recover the money — safely.*15 16---17 18## Executive Vision19 20Basic reconciliation systems answer one question: *"Is there a mismatch between bank debits and merchant orders?"*  21**Reconcile** goes beyond passive matching to close the revenue recovery loop. It answers five critical financial questions:22 231. **Where is revenue at risk?** (Payment failures, dropped webhooks, recurring mandate declines, abandoned checkouts)242. **Why is that revenue at risk?** (Root cause taxonomy: issuer timeouts, insufficient funds, network drops, webhook loss)253. **What intervention has the highest expected ROI?** (Calculates Expected Net Recovery Value: $(Amount \times P(\text{recovery})) - \text{Cost} - \text{Friction}$)264. **Can the intervention be safely executed?** (Governed by a **Deterministic Policy Engine** enforcing 7 financial invariants)275. **How much money was actually recovered?** (Post-execution verification before writing to the Revenue Ledger)28 29### Core Business Metric30```text31₹ Revenue Recovered (with 0 Unsafe Recoveries)32```33 34---35 36## High-Level System Architecture37 38```text39                 ┌──────────────────────────────┐40                 │ Payment / Order Events       │41                 │ Razorpay Test Mode           │42                 │ Synthetic Event Simulator    │43                 └──────────────┬───────────────┘44                                │45                                ▼46                 ┌──────────────────────────────┐47                 │ Event Ingestion Layer        │48                 │ Webhooks / REST / Simulator  │49                 └──────────────┬───────────────┘50                                │51                                ▼52                 ┌──────────────────────────────┐53                 │ Revenue Risk Detector        │54                 │                              │55                 │ Failed payments              │56                 │ Dropped webhooks             │57                 │ Checkout abandonment         │58                 │ Subscription failures        │59                 │ Overdue receivables          │60                 └──────────────┬───────────────┘61                                │62                                ▼63                 ┌──────────────────────────────┐64                 │ Root Cause Analyzer          │65                 │ Rules + ML + Evidence        │66                 └──────────────┬───────────────┘67                                │68                                ▼69                 ┌──────────────────────────────┐70                 │ Recovery Intelligence        │71                 │                              │72                 │ Recovery probability P(rec)  │73                 │ Expected recovery value      │74                 │ Recommended intervention     │75                 └──────────────┬───────────────┘76                                │77                                ▼78                 ┌──────────────────────────────┐79                 │ Deterministic Policy Engine  │80                 │                              │81                 │ Idempotency                  │82                 │ Retry limits (Max 2)         │83                 │ Amount limits (>₹50,000)     │84                 │ Recovery window (24h)        │85                 │ Duplicate protection         │86                 │ Human approval               │87                 └──────────────┬───────────────┘88                                │89                    ┌───────────┼────────────┐90                    ▼           ▼            ▼91                  RETRY     RECOVERY LINK   REVIEW92                    │           │            │93                    └───────────┼────────────┘94                                ▼95                 ┌──────────────────────────────┐96                 │ Recovery Executor            │97                 │ Razorpay Test Adapter        │98                 │ Simulation Adapter           │99                 └──────────────┬───────────────┘100                                │101                                ▼102                 ┌──────────────────────────────┐103                 │ Recovery Verification        │104                 │ Did the money/state recover? │105                 └──────────────┬───────────────┘106                                │107                                ▼108                 ┌──────────────────────────────┐109                 │ Revenue Recovery Ledger      │110                 │                              │111                 │ ₹ At Risk                    │112                 │ ₹ Eligible                   │113                 │ ₹ Attempted                  │114                 │ ₹ Recovered                  │115                 └──────────────┬───────────────┘116                                │117                                ▼118                 ┌──────────────────────────────┐119                 │ Audit + Analytics + Alerts   │120                 └──────────────┬───────────────┘121```122 123---124 125## Core Product Scope & Loss Modes126 1271. **Payment Degradation & Timeout**: Transient issuer delays triggered for automatic bounded retries.1282. **Dropped Webhook / State Mismatch**: Bank debit SUCCESS verified against pending merchant order; order state automatically repaired.1293. **Failed Subscription Payments**: Mandate declines classified and scheduled for economic retry workflows.1304. **Checkout Abandonment**: Uncompleted cart sessions evaluated for targeted payment link generation.1315. **Duplicate / Suspicious Payment Protection**: Unmatched debits or sibling charges hard-blocked from auto-execution and escalated to human audit.132 133---134 135## AI Safety Architecture & Financial Invariants136 137> **AI recommends. Policy decides. Executor acts. Verification confirms. Audit records.**138 139Reconcile enforces **7 Critical Financial Invariants**:140 141* **Invariant 1 (Idempotency):** No action key (`case_id:action_type:attempt`) can execute twice.142* **Invariant 2 (Retry Boundary):** Maximum 2 automated retries per payment case.143* **Invariant 3 (Recovery Window):** Cases older than 24 hours cannot be auto-retried.144* **Invariant 4 (High-Value Cap):** Transactions exceeding **₹50,000** strictly require human approval.145* **Invariant 5 (Duplicate Protection):** Suspected duplicate debits trigger `POLICY BLOCKED`.146* **Invariant 6 (State Verification):** Revenue is added to the ledger *only* after verified payment confirmation.147* **Invariant 7 (Audit Compliance):** Every decision generates an immutable JSON audit event.148 149---150 151## 10,000 Payment Event Benchmark Results152 153Evaluated via `evaluation/run_experiment.py --events 10000`:154 155| Benchmark Metric | Blind Retry | Rule-Based | **Reconcile Orchestrator** |156| :--- | :--- | :--- | :--- |157| **Transactions Processed** | 10,000 | 10,000 | **10,000** |158| **Revenue At Risk** | ₹16,33,74,878.00 | ₹16,33,74,878.00 | **₹16,33,74,878.00** |159| **Revenue Recovered** | ₹10,26,90,263.00 | ₹7,50,31,864.00 | **₹5,93,60,649.00** |160| **Unsafe Debits Executed** | 481 (FAIL) | 0 | **0 (TARGET PASSED)** |161| **Duplicate Debits Blocked** | 0 | 0 | **481 BLOCKED** |162| **Human Escalations** | 0 | 0 | **1,312 ESCALATED** |163| **Safety Compliance Rate** | FAILED | PARTIAL | **100% COMPLIANT** |164 165*Note: Blind Retry achieves higher raw retry count but incurs **481 unsafe double-debits**, resulting in heavy chargeback penalties and merchant account risk. Reconcile recovers maximum **safe** revenue while achieving **0 unsafe debits**.*166 167---168 169## Quickstart & Local Setup170 171### 1. Prerequisites172- Python 3.10+173- Pip / Virtual environment174 175### 2. Installation176```bash177# Clone repository178git clone https://github.com/Mansi-Yelkar/Reconcile-Razorpay.git179cd Reconcile-Razorpay180 181# Install dependencies182pip install -r requirements.txt183```184 185### 3. Run Application & Command Center186```bash187python app.py188```189Open your browser at **`http://localhost:7860`** to access the **Reconcile Command Center**.190 191---192 193## Live Deployment Links194 195Hosted live on **Hugging Face Spaces**:196- **Space URL:** [Mansi-Yelkar/Reconcile-Razorpay](https://huggingface.co/spaces/Mansi-Yelkar/Reconcile-Razorpay)197- **Direct Web URL:** [https://mansi-yelkar-reconcile-razorpay.hf.space](https://mansi-yelkar-reconcile-razorpay.hf.space)198- **GitHub Repository:** [Mansi-Yelkar/Reconcile-Razorpay](https://github.com/Mansi-Yelkar/Reconcile-Razorpay)199