Recover payments. Reconnect trust. Grow revenue.
Grabit is an AI-powered Revenue Recovery Agent.
It automatically detects failed payments and Autopay failures, diagnoses why they failed, and takes the smartest next action to recover the money — with personalized messages, perfect timing, and clear stopping rules.
Every day, merchants lose revenue because of:
- Soft declines (low balance, temporary issues)
- Hard declines
- UPI Autopay failures
- Mandate cancellations
Most systems just send a generic “Payment failed” message and stop.
Customers get confused, merchants lose money, and recovery rates stay low.
Grabit closes the loop:
- Detects payment & Autopay failures in real time
- Diagnoses the failure type (Hard / Soft / Autopay Failed / Autopay Cancelled)
- Decides the right action using AI + business rules
- Acts with personalized one-click recovery messages
- Times the message intelligently (salary windows, quiet hours, retry gaps)
- Stops cleanly when it should (max attempts, human escalation, etc.)
- Measures everything in a Recovery Ledger + Dashboard
- Smart failure classification
- Personalized GenZ/Hinglish explanations + one-click recovery
- Smart Timing Intelligence (salary cycle aware)
- Human-in-the-Loop (HITL) for high-value or unclear cases
- Strict Stopping Rules
- Full audit trail
- Clear recovery metrics for merchants
The architecture is built around an event-driven, decoupled pipeline designed for high-throughput webhook ingestion, deterministic rule evaluation, AI-driven recovery messaging, and recovery ledger + audit logging.
The end-to-end recovery lifecycle follows an automated 6-step state transition:
[ Razorpay Failure Event ]
|
v
+----------------------+
| 1. Ingest & Verify | ---> Validate Signature -> Paise-to-INR Conversion -> Idempotently create `failed_payments`; ignore duplicate webhooks
+----------+-----------+
|
v
+----------------------+
| 2. Stopping Rules & | ---> Checks: Already paid? Max follow-ups? Hard decline? Stale (>24h)?
| Timing Filter |
+----------+-----------+
|
+-----+----------------------------------+
| Passes Rules | Rule Triggered
v v
+----------------------+ +----------------------------------------------------------+
| 3. AI Agent Decision | | - High Value (>=10k) / Low Confidence -> HITL Escalation |
| & Copy Generation | | - Quiet Hours (21:00-08:00 IST) / Salary Gap -> Delay |
+----------+-----------+ | - Hard Decline / Max Follow-ups -> Mark Unrecovered |
| +----------------------------------------------------------+
v
+----------------------+
| 4. WhatsApp Outreach | ---> Sends personalized one-click recovery message via WhatsApp API
+----------+-----------+
|
v
+----------------------+
| 5. Customer Action | ---> Customer clicks one-click link or updates mandate via Razorpay
+----------+-----------+
|
v
+----------------------+
| 6. Reconciliation | ---> Payment Webhook -> Mark `recovered` -> Record in `recovery_ledger`
+----------------------+
The database model is strictly relational with foreign key integrity, audit logging, and normalized Decimal money handling (stored in INR Rupees).
Comprehensive engineering specifications, state machines, and data models are available in the /documentation directory:
- System Architecture & Event Flow
- Stopping Rules & Smart-Timing Engine
- Worker Pipeline & Queue Processing
- Database Models & Schema Invariants
| Layer | Choice |
|---|---|
| Main API | TypeScript + Hono |
| Background Jobs | BullMQ + Redis |
| Database | PostgreSQL + Prisma |
| AI Agent | Python + Agno + FastAPI |
| Monorepo | pnpm workspaces |
grabit/
├── apps/
│ ├── api/ # Hono API
│ ├── worker/ # BullMQ workers
│ ├── web/ # Command View dashboard (Vite + React + TS)
│ └── ai-agent/ # Python + Agno service
├── packages/
│ ├── db/ # Prisma schema & client
│ ├── queue/ # BullMQ helpers
│ ├── core/ # Shared business logic
│ └── config/
├── scripts/ # demo:batch harness + db:seed
├── infra/
└── docs/ # Architecture diagrams & screenshots
- Command View dashboard — live recovery KPIs + jobs table (
apps/web, issue #32) - Recovery Ledger, sample recovery message, HITL queue — coming soon
- Node.js 22+ (repo scripts use
node --env-file-if-exists, added in Node 22.9) - pnpm (
npm i -g pnpm) - Docker (for Postgres + Redis)
docker compose -f infra/docker-compose.yml up -dBrings up:
| Service | Port |
|---|---|
| Postgres | 5433 |
| Redis | 6380 |
| AI Agent | 8001 |
Ports differ from the usual 5432/6379 to avoid conflicts with other local projects.
pnpm install
pnpm --filter @grabit/db exec prisma generateDATABASE_URL="postgresql://grabit:grabit@localhost:5433/grabit" \
pnpm --filter @grabit/db exec prisma db push(Or copy .env.example to .env and skip the inline DATABASE_URL.)
pnpm db:seedCreates 4 representative recovery jobs (one-click recovered ₹1,499, a hard
stopped case with no message, a high-value HITL pending case, and an active
waiting follow-up) so an empty database shows meaningful dashboard numbers
immediately. Uses deterministic IDs + upserts — re-running never duplicates
rows. Refuses to run against a non-local DATABASE_URL.
DATABASE_URL="postgresql://grabit:grabit@localhost:5433/grabit" pnpm dev:apipnpm --filter @grabit/web devOpens at http://localhost:5173. Reads the API at VITE_API_URL (default
http://localhost:3100) and polls /dashboard/summary + /jobs every 3s
while the tab is visible, so numbers move live after pnpm demo:batch or a
payment.captured webhook — no refresh needed.
curl http://localhost:3100/healthExpected:
{"status":"ok","service":"grabit-api","database":"connected"}# API: Ctrl+C in its terminal
docker compose -f infra/docker-compose.yml down # stop containers
docker compose -f infra/docker-compose.yml down -v # also wipe Postgres dataCurrently in active development