EasyPaisa Auto Payment Gateway & 3737 SMS / App Push Verification Module for WHMCS

# ⚡ EasyPaisa Auto Payment & Real-Time SMS/Push Verification Gateway for WHMCS
### Enterprise Edition • Modern Electric Royal Blue (#1769FF) Standard • Strict Anti-Fraud Engine

Transform your Pakistani WHMCS hosting business with the most reliable, fully automated EasyPaisa payment solution. Say goodbye to manual bank statement checks and fraudulent transaction submissions!

This module instantly catches incoming 3737 SMS alerts and Android mobile app push notifications, automatically verifies the transaction ID and amount, and marks client invoices as PAID in real-time — all within 3.5 seconds.

---

## 🌟 Why This Module Is Built Different

### 🛡️ 1. Bulletproof Anti-Fraud Engine (Zero Fake Approvals)
Most generic EasyPaisa modules suffer from a critical loophole where a customer entering a fake TID twice gets auto-approved. Our proprietary ledger strictly enforces **Verified Bank Sources Only** (`sms_3737`, `app_notification`, `webhook`). Unverified manual client entries remain strictly pending and can NEVER settle an invoice without confirmed bank verification.

### 🚀 2. Dedicated Zero-Clutter Pay Portal (`pay.php`)
Invoices remain spotless! No oversized white boxes or duplicate pricing cards on your invoice page. Customers click a sleek `#1769FF` "Continue to Pay ➔" button and are securely redirected to a dedicated, mobile-optimized payment portal protected by HMAC-SHA256 cryptographic tokens.

### 🔄 3. Live 3.5s Background Auto-Poller
Customers never have to manually refresh the invoice! The dedicated pay page polls invoice status every 3.5 seconds in the background. As soon as payment is confirmed, an instant green "Payment Received!" modal pops up and automatically redirects the customer to their paid receipt.

### 📱 4. Built-In MacroDroid / Tasker Webhook Standards
Fully compatible with free Android automation apps (MacroDroid/Tasker). Includes an intelligent **Test Ping Interceptor** that turns MacroDroid's test action `[sms_body]` placeholder into an immediate HTTP 200 OK — eliminating the annoying 422 error permanently!

---

## ⚡ Complete Feature List

- **Real-Time 3737 SMS Parser:** High-accuracy regex engine extracts TID, sender name, mobile number, and PKR amount effortlessly.
- **EasyPaisa App Push Notification Listener:** Captures modern mobile app notifications when payments are received directly through the app.
- **Dedicated Admin Ledger Dashboard:** Full management portal under WHMCS Addons with search, status filters, and event logs.
- **Native SQL Pagination (10/25/50/100 Per Page):** Built with native offset/limit queries — permanently fixes the fatal `Illuminate\Pagination\Paginator Not Found` error in WHMCS.
- **Select All & 1-Click Bulk Delete:** Easily clean up 10 records per page with a single click to keep your database lean.
- **Auto-Cleanup / Purge Utility:** Automatically prune old records (older than 7, 30, 90, or 365 days) to eliminate database clutter.
- **Single-Source Webhook Secret Synchronizer:** Manage and rotate your webhook secret key directly from the admin dashboard with 100% sync across gateway, callbacks, and pay page.
- **Built-in Webhook Simulator:** Test MacroDroid pings, simulated 3737 SMS messages, and simulated push notifications directly from admin UI with 1-click.
- **Multi-Currency Auto-Conversion:** Invoices in USD, EUR, GBP, or AED are automatically converted to PKR using WHMCS live exchange rates with configurable fallback rate.
- **Sender Account Details:** Dedicated fields on checkout for Sender Account Name and Sender Mobile Number for transparent audit trails.
- **Timing-Safe & PDO Parameterized:** 100% protected against SQL Injection, XSS, CSRF attacks, and cryptographic timing attacks via `hash_equals()`.
- **PHP 8.1 / 8.2 / 8.3 & WHMCS 8.11+ Ready:** Zero deprecation warnings, type-safe null coalescing, and `\Throwable` safety.

---

## 💻 Technical Specifications & Requirements

- **WHMCS Compatibility:** WHMCS 7.x, 8.0, 8.5, 8.8, 8.10, and 8.11+
- **PHP Versions:** PHP 7.4, 8.0, 8.1, 8.2, and 8.3+
- **PHP Extensions:** cURL, JSON, OpenSSL, PDO / MySQLi
- **Android Phone Requirements:** Any Android phone with SIM receiving 3737 SMS or EasyPaisa App with MacroDroid or Tasker installed.

---

## 📦 What's Included in the Package?

1. `modules/gateways/easypaisa.php` — WHMCS Gateway Core Configuration
2. `modules/gateways/callback/easypaisa.php` — High-Performance Webhook & Poller Listener
3. `modules/gateways/easypaisa/pay.php` — Dedicated Clean Mobile-First Payment Portal
4. `modules/gateways/easypaisa/helpers.php` — Core Parsing, Currency & Security Engine
5. `modules/addons/easypaisa_manager/` — Admin Ledger, Simulator & Database Tools
6. Step-by-Step MacroDroid Android Setup Configuration Guide
7. Lifetime updates and technical documentation

---

## 🛠️ Easy 3-Step Setup

1. **Upload Files:** Upload the `modules/` folder directly into your WHMCS root directory.
2. **Activate Gateway:** In WHMCS Admin, go to **Setup > Payments > Payment Gateways**, activate EasyPaisa, and enter your account title, account number, and secret key.
3. **Configure MacroDroid:** Follow the in-app guide to forward incoming 3737 SMS / App notifications to your webhook URL. You are ready to accept automated payments!