An autonomous payment-operations platform for Razorpay merchants.
From a signed payment signal to an evidence-backed, policy-bounded incident record.
PayScope turns raw Razorpay webhook events into a tenant-scoped, evidence-backed recovery loop. It correlates payment-failure signals into incident timelines, enriches allowlisted Razorpay payment fields and downtime signals, runs an AI Self-Learning Multi-Agent investigation (Supervisor, Risk Analyst, Recovery Planner), ranks deterministic recovery strategies using merchant-wise historical recovery statistics, enforces hard dispute/fraud safety guardrails, and—when direct execution is enabled—dispatches Razorpay Payment Links through SMTP. Every outcome is recorded into a merchant-level learning ledger (payscope_recovery_outcomes), continuously improving future decision confidence.
- Razorpay Telemetry Ingestion & Real-Time Push Stream: Uses allowlisted Razorpay fields (
error_source,error_step,error_reason, attempts, and acquirer data) plus bounded downtime signals. Broadcasts granular real-time progress events over SSE (/api/mvp/events/stream) with < 50ms latency. - AI Self-Learning Multi-Agent Engine: Supervisor, Risk Analyst, and Recovery Planner agents synthesize merchant-specific historical performance (
recoveryOutcomeStats), customer segment data, and failure attribution statistics directly in prompt context to autonomously choose the optimal recovery strategy and outreach copy. - AI-First Policy Safety Guardrails: Hard safety gates validate critical security boundaries (active customer disputes, confirmed fraud blocks, emergency pauses) while allowing the AI to autonomously structure and execute recovery options for standard transaction failures.
- Full Action Capability Matrix: Supports all core payment operational capabilities: 1-Click Payment Link Email Delivery (
deliver_recovery_link_email), Infrastructure Auto-Rerouting (resolve_infrastructure), Dispute Evidence Submission (submit_dispute_evidence), Risk Signal Recording (record_risk_signal), Authorization Capture (capture_authorized_payment), and Refund Processing (refund_payment). - Idempotent Execution & Durable Callback Reconciliation: Creates traceable recovery actions with unique references (
ps_...), reconciles ambiguous provider results before retry, marks expired recovery links terminal before adaptive replanning, and transactionally closes the learning ledger (payscope_record_recovery_outcome). - Zero-Config Runtime Environment Auto-Detection: Single-port Express architecture seamlessly auto-detects local vs VPS production runtimes (
window.location.origin), eliminating manual.envfile editing when switching between local testing and production deployment.
|
01 — Spatial Showcase Canvas An interactive spatial scrolling overview presenting system architecture, signal telemetry, and policy controls. 
|
02 — Real-Time Incident Feed Unified incident records sorted by risk tier, current status, and total monetary value at risk. 
|
|
03 — Evidence and Strategy Record Model evidence records are separated from the deterministic strategy and policy decision. 
|
04 — Autonomous Execution Ledger Provider commands, delivery receipts, and verified callback reconciliation tracked in an immutable audit trail. 
|
| Question | Answer |
|---|---|
| Track selection | AI agents for payment operations |
| Project name / title | PayScope — Autonomous Payment Operations Agent |
| GitHub repository | github.com/Drix10/payscope |
| Project objective | Ingest signed Razorpay events, enrich with Razorpay telemetry, analyze evidence using a structured multi-agent pipeline, execute authorized recovery actions, and verify outcomes via signed callbacks. |
| What it solves | Payment failures are noisy and hard to resolve manually. PayScope correlates webhooks into unified incidents, distinguishes bounded heuristic causes, executes only policy-permitted actions, and retains an auditable decision/receipt/callback chain. |
Razorpay Webhook (HMAC SHA-256 Signed)
│
▼
Allowlisted Razorpay Field Enrichment (Heuristic Attribution)
│
▼
Correlation & Deduplication Engine (Order ID, Customer Hash, Time Window)
│
▼
Structured Investigation (Supervisor → Risk Analyst → Recovery Planner)
│
▼
Deterministic Recovery Engine (strategy score and heuristic estimate, not calibrated probability)
│
▼
Deterministic Policy Engine (13 Safety Gates, Dispute Locks, Contact Ceilings)
│
▼
Transactional Outbox & Execution Worker (Razorpay Payment Links & Nodemailer SMTP)
│
▼
Callback Reconciliation & Append-Only Cryptographic Audit Trail
| Component | Function | Authority Boundary |
|---|---|---|
| Supervisor Agent | Synthesizes incident context, sets investigation objectives, and establishes risk constraints. | Analytical only; cannot execute commands or alter policies. |
| Risk Analyst Agent | Analyzes payment failure telemetry, merchant metrics, and causal factors. | Analytical only; reads tenant data without side effects. |
| Recovery Planner Agent | Supplies bounded recovery context and permitted email copy intent. | Cannot select the final action or execute commands. |
| Recovery Engine | Ranks untried recovery strategies from durable incident evidence and customer context. | Deterministic selector; no strategy means no action. |
| Deterministic Policy Engine | Evaluates 13 hard business rules, dispute blocks, and outreach ceilings. | Gatekeeper; holds final execution authority. |
| Execution Workers | Dispatches authorized provider commands from outbox and tracks receipts. | Executes approved actions idempotently. |
- Node.js 20+
- npm
- PostgreSQL / Supabase instance (SQL migrations located in
backend/supabase/migrations)
Required environment (see backend/.env.example): PAYSCOPE_CALLBACK_ENCRYPTION_KEY (base64 32-byte key — webhooks are refused without it), and PAYSCOPE_DASHBOARD_API_KEY (mandatory in production; the /api/mvp/* dashboard endpoints reject requests without it).
cd backend
cp .env.example .env
npm install
npm run build
npm run devcd frontend
cp .env.example .env
npm install
npm run build
npm run devA standalone local harness for triggering signed webhook payloads and inspecting live scenarios:
cd docs/demo-kit
npm startAccess the operator UI at http://127.0.0.1:3050.
To prepare a Razorpay Test order for checkout (this does not create a payment, Payment Link, or causal recovery reference):
node docs/demo-kit/scripts/generate-test-payments.mjs# Backend suites: integration scenarios (strategy selection/exhaustion, policy gates,
# adaptive replanning, webhook rotation, encrypted callback evidence, fail-closed DB reads)
# plus a real-HTTP suite that boots the actual server and posts signed webhooks over the wire
# plus deterministic learning tests (cold start, 1 paid, 10 expired, merchant/segment isolation,
# outcome idempotency, amount attribution, and the killer loop: outcomes change next decision)
cd backend && npm run test
# Frontend TypeScript compilation & production build check
cd frontend && npm run build
# Demo kit HMAC signature & replay test
node docs/demo-kit/scripts/self-test.mjs
# Live Supabase + Razorpay boundary checks (against deployed DB, test-mode Razorpay — no mocks)
# Proves: paid/expired reconciliation closes ledger exactly once, concurrent outbox claims are
# exactly-once, ambiguous dispatch never resends, and late verified webhooks reconcile monotonically.
# node backend/scripts/verify-provider-boundary.js # requires SUPABASE_ + RAZORPAY_ env