ReCoup

ReCoup is a closed-loop AI revenue recovery agent for Razorpay-shaped UPI Autopay mandate failures. It diagnoses decline codes, picks one bounded intervention, executes via a simulator-backed world, and reports incremental recovered GMV vs a dumb baseline.

North-star metric

Incremental ₹ recovered on a frozen synthetic merchant batch (seed 42) vs a Stripe-style baseline (fixed 24h retry, technical immediate retry, static hard-decline deny list, no customer repair).

Quick start

npm install
cd console && npm install && cd ..
npm test
npm run eval
npm run validate:external
npm run dev          # API on :3000
npm run dev:console  # Merchant UI on :5173 (proxies /api → :3000)

Or run both together:

npm run start:project

Windows PowerShell:

.\scripts\start.ps1

This installs dependencies (if missing), starts the API on :3000 and console on :5173.

Options:

npm run start:project -- --skip-install   # skip npm install check
npm run start:project:eval                # run eval first, then start

Or run both manually:

npm run dev:all

Build everything (API + console for single-port deploy):

npm run build:all
npm start            # serves console at / when console/dist exists

• Eval report: eval/report.json and eval/report.md
• Merchant console: http://localhost:5173 (dev) or http://localhost:3000 (after build)

Architecture

CSV / Webhook → Normalizer → Diagnoser → Policy Gate → Decider → Executors → Simulator / Razorpay
                                                                    ↓
                                                              Audit Ledger (JSON store)

API endpoints

Method	Path	Description
GET	/health	Health check
POST	/api/ingest/csv	Ingest batch
POST	/api/ingest/adapters	Ingest checkout / invoice / PTP / voice fixtures
POST	/api/webhooks/razorpay	Razorpay test-mode webhook ingest
GET	/api/cases	List cases
GET	/api/cases/:id	Case detail + audit trail
POST	/api/cases/:id/run-to-completion	Run ReCoup orchestrator
POST	/api/cases/:id/retry/live	Live retry (Razorpay if configured)
POST	/api/eval/run	Run ReCoup vs BASELINE eval
GET	/api/eval/latest	Latest eval metrics
GET	/api/metrics	Recovered ₹ dashboard
GET	/api/catalog/failures	Failure gallery by mapped class
GET	/api/adapters/razorpay	Razorpay adapter status

Legacy routes without /api prefix remain for backward compatibility.

Razorpay test-mode (optional)

Set env vars to enable live retries instead of simulator-only:

RAZORPAY_KEY_ID=rzp_test_...
RAZORPAY_KEY_SECRET=...

Without keys, all scoring runs on the simulator — no production access required.

External diagnoser validation (optional)

Validates decline-code mapping against public UPI failure labels — not incremental ₹ recovery.

npm run validate:external          # fetches HF mock-upi-txn-data (cached under data/external/)
npm run validate:external:offline  # uses committed sample in data/samples/

Reports: data/external/diagnoser-validation.json and .md

Source dataset: deepakjoshi1606/mock-upi-txn-data (not committed — cache is gitignored).

Merchant console

• Tabs by feature: Dashboard · Autopay · Checkout · Invoice · PTP & Voice · Feature gallery · Failure gallery
• Dashboard: seed-42 north-star vs live store; recovered ₹ by rail / decline class; feature-gallery scoreboard
• Each feature tab shows only that rail’s cases (with diagnosis + audit)
• Actions: ingest batch → Autopay; load adapters → Checkout/Invoice/PTP; load feature gallery; run eval

Rails in scope

UPI Autopay mandate debit is the scored rail (seed 42 eval). Checkout drop-off, B2B invoices, Hinglish voice, and promise-to-pay plug into the same diagnose → decide → policy → execute loop as adapters. They do not mix into the north-star eval.

• Checkout — SEND_PAYMENT_LINK, never SILENT_RETRY
• Invoice — dunning notify, never a UPI debit
• Voice — channel + hi-en copy on the existing repair action
• Promise-to-pay — promisedAt case state; early debit/chase denied

Load demo fixtures from the console (Load feature gallery, Load adapter fixtures) or POST /api/ingest/features / POST /api/ingest/adapters.

Compliance

• Hard declines never retried
• Attempt and contact caps enforced by policy gate
• Idempotent executors (no double-debit)
• Append-only audit ledger per case

License

MIT