SentinelPay

Real-time AI fraud detection for UPI payments

Flutter frontend showcasing real-time risk scoring, audit log integrity, and fraud analytics dashboard

Why This Matters

UPI processes over 18 billion transactions monthly in India. Fraud detection in most systems happens after a transaction completes — too late to stop the damage. SentinelPay scores every transaction in real time, before it clears, using an ML ensemble trained on UPI transaction patterns.

Built for a hackathon but designed with production security principles: cryptographically signed requests, tamper-evident audit logs, and adversarial attack detection baked in from the start.

---

What It Does

A user submits a UPI payment through the Flutter app. Before the transaction goes through, SentinelPay:

1. Collects a device fingerprint — hardware ID, OS version, model, location
2. Signs the request with HMAC-SHA256 and sends it to the FastAPI backend
3. Runs the transaction through an XGBoost + Isolation Forest ensemble
4. Returns a risk score from 0–100 in under 100ms
5. Logs every event to a hash-chained audit trail that detects tampering

The result is shown instantly — green for safe, amber for suspicious, red for high risk — with a recommended action.

---

Key Engineering Highlights

Machine Learning Ensemble

• XGBoost (supervised) trained on labeled UPI fraud data with SMOTE to handle class imbalance
• Isolation Forest (unsupervised) trained only on legitimate transactions — catches novel attack patterns the supervised model has never seen
• Combined with a 70/30 weighted ensemble for a single 0–100 risk score

Security Architecture

• HMAC-SHA256 request signing — every API call is signed with a shared secret; the backend rejects any request where the signature does not match
• Replay attack prevention — requests with a timestamp older than 30 seconds are rejected outright
• Hash-chained audit log — every fraud event is stored with a SHA-256 hash of the previous entry; modifying any past record breaks the chain and is detected immediately
• Adversarial probe detection — identifies when someone is systematically testing transaction amounts to reverse-engineer the fraud threshold
• Client-side rate limiting — maximum 5 transactions per minute before the UI locks

Device Fingerprinting

Hardware-level signals — device ID, OS version, manufacturer model — are collected automatically and included as ML features. No user action required.

---

Example: What Happens on a Suspicious Transaction

A user submits ₹12,000 to an unknown UPI ID at 2:30 AM, categorised as Travel, from a device that has never transacted before.

• amount_log feature pushes the base score up
• is_night flag adds further weight
• is_high_risk_merchant (Travel) compounds the signal
• Device ID hash has no prior transaction history
• Ensemble output: score 88 → HIGH RISK
• Alert displayed, transaction flagged, audit entry written

---

Architecture

Flutter App
    │
    ├── Device fingerprint collected
    ├── Input sanitised + rate limit checked
    ├── Adversarial probe detection
    ├── HMAC-SHA256 signature applied
    │
    └──▶  POST /analyze-transaction
                │
                ├── Security middleware (API key + signature + timestamp)
                ├── Pydantic schema validation
                ├── XGBoost + Isolation Forest inference
                ├── Result written to PostgreSQL
                └── Audit log entry appended (hash-chained)
                │
                └──▶  { risk_score: 88, classification: "HIGH_RISK" }
                            │
                            └── Flutter displays animated risk gauge
                                Dashboard updates live
                                Audit chain verified

---

Tech Stack

Layer	Technology
Mobile Frontend	Flutter 3.x + Riverpod
HTTP Client	Dio (with HMAC interceptor)
Backend API	FastAPI + Uvicorn
ML Models	XGBoost + Isolation Forest (scikit-learn)
Imbalance Handling	SMOTE (imbalanced-learn)
Database	PostgreSQL + SQLAlchemy
Security	HMAC-SHA256, SHA-256 hash chain
Charts	fl_chart
Device Info	device_info_plus, geolocator

---

Screens

Screen	Purpose
Login	Demo authentication
Transaction	UPI payment simulation with full security pipeline
Risk Result	Animated 0–100 risk gauge, risk level, recommended action
Dashboard	Live transaction feed, fraud rate, pie chart, histogram
History	Filterable transaction log by risk level
Audit Log	Hash-chained event log with live chain integrity verification

---

Quick Start

Frontend (Flutter)

cd sentinelpay_app
flutter pub get
flutter run

Runs in mock mode by default — no backend needed. Demo credentials: user@sentinelpay / demo1234

To connect to a real backend, open lib/config/environment.dart and set:

static bool get useMockApi => false;
// Set baseUrl to your machine's LAN IP

Backend (FastAPI)

cd sentinelpay_backend
pip install -r requirements.txt   # requires Python 3.11
python train.py                    # generates model .pkl files
uvicorn main:app --host 0.0.0.0 --port 8000 --reload

Full setup details, API contract, and team integration guide are in DEVELOPER_GUIDE.md

---

Demo: Tamper Detection (Live)

One of the most demonstrable features is the hash-chain tamper detection:

1. Submit a transaction — audit log populates, chain shows green
2. Open pgAdmin and edit any value in the audit_log table
3. Within 5 seconds the Flutter app detects the broken chain automatically
4. A breach alert fires on the phone with the exact compromised entry
5. Navigate to the Audit Log screen to see the full chain integrity report

This works because the app polls GET /audit/verify every 5 seconds.

---

What We Would Build Next

• JWT authentication to replace the static API key in production
• Redis-based server-side rate limiting to complement client-side limits
• Model versioning with SHA-256 checksum verification at server startup — prevents model substitution attacks
• Geolocation velocity checks — flag transactions from two cities in an impossible time window
• Federated learning — allow multiple banks to improve the shared model without sharing raw transaction data
• Push notifications for high-risk alerts sent to the account holder's device

---

👥 Team

Built during the Secure AI Software and Systems Hackathon
(BITS Goa × IIT Madras × ISEA)

Contributor	Role	Responsibilities
Shaurya Naik	Frontend + Security	Flutter app, UI/UX, HMAC signing, audit log chain, device fingerprinting, adversarial detection
Siddhant Kerkar	Backend + ML	FastAPI backend, database integration, ML model training (XGBoost + Isolation Forest), inference pipeline

---

SentinelPay is a hackathon prototype. It is not a production payment system.