A self-hosted UPI & COD payment gateway with zero per-transaction platform fees, universal JavaScript checkout integration, dynamic QR payments, WhatsApp OTP authentication, and automated payment verification.
Android Payment Observer Mobile App — Engineering & Deployment Guide
1. Overview & Architectural Role
The YOUPI Android Payment Observer is a native Android Kotlin application designed to run on a dedicated merchant phone receiving UPI incoming payments via banking and UPI applications (PhonePe, Google Pay, Paytm, BHIM, HDFC, ICICI, SBI, Axis, etc.).
Critical Architectural Boundaries
- The Mobile App Is An Observer, NOT a Decision-Maker:
- The app's job is strictly: $$\text{Notification Arrived} \to \text{Extract Amount & UTR} \to \text{Sign Payload} \to \text{Dispatch to Backend}$$
- The mobile application never determines whether a payment succeeded. It reports: "I observed a status bar notification representing an incoming credit of ₹200.00."
- The central self-hosted backend decides attribution based on the active queue slot, expected amount, and server timestamps.
- Cryptographic Device Enrollment:
- The app does not contain hardcoded API keys or master secrets.
- It pairs with the merchant's gateway via an ephemeral enrollment token (scanned via QR code in the Merchant Admin).
- Upon pairing, the gateway assigns a permanent
deviceIdand unique 256-bitsigningKeystored in Android'sEncryptedSharedPreferences(backed by the hardware Android Keystore). - Every observation submission is signed using
HMAC-SHA256(signingKey, body + ":" + timestamp)with headersX-Device-Id,X-Timestamp, andX-Signature. Replay attacks are rejected if timestamp drift exceeds 60 seconds.
2. Directory Structure & Source Code Layout
apps/android-observer-app/
├── build.gradle.kts # Root Gradle build script
├── settings.gradle.kts # Gradle project settings
├── driver.js # Headless Node.js Driver / Simulator for automated CI/CD testing
├── simulate-notification.js # Interactive CLI simulator for pushing test notifications
├── app/
│ ├── build.gradle.kts # App-level dependencies (OkHttp, Security Crypto, AndroidX)
│ └── src/
│ └── main/
│ ├── AndroidManifest.xml # Manifest with permissions and service registrations
│ ├── res/
│ │ └── xml/
│ │ └── network_security_config.xml
│ └── java/com/youpi/observer/
│ ├── MainActivity.kt # Setup, pairing UI & permission prompt
│ ├── PaymentNotificationListenerService.kt # Core NotificationListenerService
│ ├── NotificationParser.kt # Regex parser for PhonePe, GPay, Paytm, Bank SMS
│ ├── ApiClient.kt # OkHttp client with HMAC-SHA256 signing
│ ├── ForegroundService.kt # Sticky foreground service preventing OS kill
│ ├── HeartbeatWorker.kt # 60-second liveness heartbeat scheduler
│ └── BootReceiver.kt # Auto-restart upon device boot
3. How to Build the APK
Prerequisites
- JDK 17+ (e.g. OpenJDK 17)
- Android SDK (API Level 34)
Building via Gradle CLI
From the apps/android-observer-app directory:
# Debug Build (for testing & development):
./gradlew assembleDebug
# Output APK located at:
# app/build/outputs/apk/debug/app-debug.apk
# Production Release Build:
./gradlew assembleRelease
4. Installation & Device Setup
Step 1: Install APK onto Android Device
Connect your Android phone via USB with USB Debugging enabled:
adb install -r app/build/outputs/apk/debug/app-debug.apk
(Or transfer app-debug.apk directly to your phone via USB/WhatsApp/Drive and install).
Step 2: Grant Notification Listener Permission
- Open the app YOUPI Observer.
- Tap Grant Notification Listener Access.
- Android System Settings will open. Toggle YOUPI Observer to Allowed.
- Confirm the system warning dialog.
Step 3: Exempt from Battery Optimization (Crucial for 24/7 Uptime)
To ensure Android OEMs (Xiaomi MIUI, Samsung OneUI, OnePlus OxygenOS, Realme/Oppo ColorOS) do not put the observer to sleep:
- Open phone Settings > Apps > YOUPI Observer.
- Tap Battery > Select Unrestricted (or "Don't optimize").
- Enable Autostart / Allow background activity.
Step 4: Pair with Gateway
- Open your Merchant Admin (
http://localhost:6001). - Go to Observers & Pairing tab -> Click + Pair Android Device.
- In the mobile app, enter the Gateway URL and the Enrollment Token.
- Emulator (Android Studio):
http://10.0.2.2:6100 - Physical device on the same LAN:
https://<gateway-host>:6100(see the cleartext note below) - Physical device via a tunnel:
https://<your-public-host>
- Emulator (Android Studio):
- Tap Pair with Merchant Gateway.
- The status badge will change to Status: CONNECTED (Active Observer) with a green indicator.
Cleartext HTTP is disabled by default. The observer app now refuses plain
http://traffic app-wide (and no longer trusts user-installed CAs), so a bank-notification client cannot be intercepted on an untrusted network. Cleartext is still permitted for the loopback/emulator hosts10.0.2.2,localhostand127.0.0.1.If you must reach a gateway over plain HTTP on a private LAN address, add that exact host to
apps/android-observer-app/app/src/main/res/xml/network_security_config.xml:<domain-config cleartextTrafficPermitted="true"> <domain includeSubdomains="true">192.168.1.50</domain> </domain-config>The preferred fix is to terminate TLS in front of the gateway (a Cloudflare Tunnel or a reverse proxy with a valid certificate) and pair over
https://.
5. Testing with ADB Notifications (Simulation on Real Phone)
You can simulate real incoming UPI notifications directly on a connected physical phone without spending real money:
# Simulate PhonePe UPI Payment Received Notification:
adb shell cmd notification post -S bigtext -t "PhonePe" "Payment Received" "Payment of Rs 200.00 received from customer@paytm on PhonePe. UTR: 998877665544"
# Simulate Google Pay Payment Received Notification:
adb shell cmd notification post -S bigtext -t "Google Pay" "Payment Received" "Rs 450.00 received from payer@upi via GPay. Ref: UTR12345678"
# Simulate Paytm UPI Notification:
adb shell cmd notification post -S bigtext -t "Paytm" "Money Received" "Received Rs 1,200 from 9876543210@paytm. UPI Ref: 5544332211"
The app's PaymentNotificationListenerService will instantly catch the notification, extract the amount and UTR, compute the HMAC-SHA256 signature, and transmit the observation to your backend.
6. Testing via Terminal Simulator (Without Phone)
If developing locally without a physical Android phone connected:
node apps/android-observer-app/simulate-notification.js
This simulator:
- Pairs with your local gateway API.
- Emits a liveness heartbeat.
- Transmits an authentic signed PhonePe notification observation.
- Outputs the response status and attribution result in color on the terminal.