# System Design Document

## UPI Auto Payment Wallet System

---

# 1. Introduction

This document describes the **system design** for the UPI Auto Payment Wallet System.

The system allows users to deposit money into their wallet using **UPI payments**, and the wallet is credited automatically when a successful payment notification is detected.

The design focuses on:

* Simple architecture
* Automatic payment detection
* Secure transaction handling
* Scalable backend structure

---

# 2. System Architecture Overview

The system consists of four main layers:

1. **Frontend (Website)**
2. **Payment Layer (UPI Apps)**
3. **Notification Listener (Android App)**
4. **Backend API + Database**

High level architecture:

User → Website → UPI Payment → Android Notification → Listener App → Backend API → Database → Wallet Credit

---

# 3. Component Design

## 3.1 Frontend (PHP Website)

Purpose:

The frontend allows users to interact with the platform.

Key Responsibilities:

* User authentication
* Wallet display
* Deposit request creation
* Game entry management

Main Pages:

* Login / Register
* Dashboard
* Wallet page
* Deposit page
* Transaction history

Example Deposit Flow:

1. User enters deposit amount.
2. System generates UPI payment link.
3. UPI app opens.
4. User completes payment.

---

# 3.2 Payment Layer (UPI Apps)

Supported UPI Apps:

* Google Pay
* PhonePe
* Paytm
* BHIM

Responsibilities:

* Process user payments
* Send payment notifications to the device

Example Notification:

"₹100 received from Rahul. UPI Ref No: 324567891234"

---

# 3.3 Android Notification Listener

The Android application listens for payment notifications.

Technology:

* Java
* Android NotificationListenerService

Responsibilities:

* Monitor notifications
* Filter notifications from UPI apps
* Extract payment data
* Send transaction details to backend

Extracted Data:

* Payment Amount
* UTR (Transaction Reference)
* Sender Name
* Time of transaction

---

# 3.4 Backend API (PHP)

The backend processes payment information received from the Android listener.

Responsibilities:

* Receive payment data
* Validate transaction
* Prevent duplicate payments
* Update wallet balance
* Store transaction records

API Endpoint Example:

/api/payment.php

Request Parameters:

* user_id
* amount
* utr

Response Example:

{
"status": "success",
"message": "Wallet credited"
}

---

# 3.5 Database Design (Supabase PostgreSQL)

Supabase PostgreSQL stores all persistent data.

Key Tables:

### Users

Fields:

* id
* username
* email
* wallet_balance
* created_at

---

### Transactions

Fields:

* id
* user_id
* amount
* utr
* status
* created_at

---

# 4. Data Flow Design

Step-by-step system data flow:

1. User initiates deposit from website.
2. System generates UPI payment link.
3. User completes payment using UPI app.
4. Payment notification appears.
5. Android listener reads notification.
6. Application extracts payment details.
7. Data sent to backend API.
8. Backend validates transaction.
9. Transaction stored in database.
10. Wallet balance updated.

---

# 5. Security Design

### Duplicate Transaction Protection

Each UPI transaction reference number must be unique.

Database constraint prevents duplicate entries.

---

### API Authentication

Backend API should require:

* API key
* Request validation
* Secure HTTPS communication

---

### Notification Source Validation

The system should only process notifications from trusted UPI apps.

Example package filters:

* com.google.android.apps.nbu.paisa.user
* com.phonepe.app
* net.one97.paytm

---

# 6. Error Handling

Common error cases:

Invalid Payment Data
If notification parsing fails, the payment is ignored.

Duplicate UTR
If the same UTR is detected again, the transaction is rejected.

API Failure
If backend API fails, the listener retries sending the data.

---

# 7. Deployment Design

Recommended deployment architecture:

Frontend Server
PHP website hosted on VPS or shared hosting.

Backend API
PHP backend running on same or separate server.

Database
Supabase PostgreSQL cloud database.

Mobile Service
Android device running the notification listener app.

---

# 8. Scalability Considerations

Future scalability improvements may include:

* Multiple Android listener devices
* Load-balanced backend servers
* Queue-based transaction processing
* Real-time wallet updates
* Distributed logging

---

# 9. Future Design Enhancements

Planned improvements:

* Admin dashboard
* Payment analytics
* Fraud detection system
* Dynamic payment request generation
* Payment reconciliation system
* Real-time monitoring system

---

# 10. Conclusion

The design provides a lightweight and efficient solution for automatic wallet deposits using UPI payments.

By combining:

* PHP web platform
* Android notification detection
* Supabase database

the system enables automatic wallet updates without requiring a traditional payment gateway.
