# UPI Auto Payment System Documentation

## Introduction

This document describes the implementation and usage of the **UPI Auto Payment Detection System** used for automatically crediting user wallets after successful UPI payments.

The system is designed for applications such as gaming platforms where users need to deposit money into their wallet before joining games.

The system works without a traditional payment gateway by detecting UPI payment notifications on an Android device and sending the payment data to the backend server.

---

# System Components

The system consists of three main components:

1. **Android Notification Listener App (Java)**
2. **PHP Backend API**
3. **Supabase PostgreSQL Database**

Each component works together to detect payments and update user balances automatically.

---

# Android Notification Listener App

## Purpose

The Android application monitors notifications from UPI applications and extracts payment information when a payment is received.

## Supported UPI Apps

* Google Pay
* PhonePe
* Paytm
* BHIM

## Data Extracted

The listener extracts the following details from the notification message:

* Payment Amount
* UTR (Transaction Reference Number)
* Sender Name
* Timestamp

## Responsibilities

* Monitor notifications from supported UPI apps
* Identify successful payment notifications
* Extract transaction data
* Send payment information to the backend server

---

# Backend API (PHP)

## Purpose

The backend API receives payment data from the Android listener and processes the transaction.

## Endpoint Example

/api/payment.php

## Request Parameters

* user_id
* amount
* utr

## Backend Processing

When the backend receives a request:

1. Validate the request parameters
2. Check if the UTR already exists in the database
3. Insert the transaction record
4. Update the user's wallet balance
5. Return a success response

---

# Database (Supabase PostgreSQL)

Supabase PostgreSQL is used to store user accounts and transaction data.

## Users Table

Fields:

* id
* username
* wallet_balance

## Transactions Table

Fields:

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

---

# Payment Flow

Step 1
User clicks the **Pay ₹100** button on the website.

Step 2
The website opens the UPI payment link.

Step 3
The user completes the payment in their UPI app.

Step 4
The Android device receives a payment notification.

Step 5
The notification listener reads the message.

Step 6
The application extracts the amount and UTR.

Step 7
Payment details are sent to the backend API.

Step 8
The backend verifies and stores the transaction.

Step 9
The user's wallet balance is updated.

Step 10
The game platform detects the updated balance and allows the user to join the game.

---

# Security Measures

To ensure the system works reliably and securely, the following protections are implemented.

## Duplicate Transaction Protection

Each transaction uses a unique UTR number to prevent duplicate credits.

## Notification Source Filtering

Only notifications from supported UPI apps are processed.

## Amount Validation

The backend checks that the payment amount matches the expected deposit amount.

## API Protection

The backend API should require authentication or API keys to prevent unauthorized requests.

---

# Deployment

## Server

* VPS or Cloud server running PHP

## Database

* Supabase PostgreSQL

## Mobile Service

* Android device running the Notification Listener application

---

# Limitations

* The Android listener device must remain online.
* Notification access must be enabled.
* Some UPI apps may change notification formats.

---

# Future Enhancements

Possible improvements for the system:

* Admin dashboard for monitoring payments
* Real-time wallet updates
* Fraud detection system
* Multiple notification listener devices
* Dynamic payment requests
* Transaction analytics

---

# Conclusion

The UPI Auto Payment Detection System provides a simple and effective way to automatically credit wallet balances without using a traditional payment gateway. By combining an Android notification listener, a PHP backend API, and a Supabase database, the system enables seamless payment integration for gaming platforms and wallet-based services.
