SadaPay WHMCS Payment Gateway — MacroDroid SMS Auto-Clearance + Admin Manager

SadaPay WHMCS Payment Gateway is a production-ready, security-hardened payment module that lets your clients pay invoices via SadaPay bank transfer. The moment a payment SMS or app notification arrives on your phone, MacroDroid automatically fires a webhook to WHMCS — and the invoice gets marked PAID instantly, without any manual work.

━━━━━━━━━━━━━━━━━━━━━
🚀 KEY FEATURES
━━━━━━━━━━━━━━━━━━━━━

✅ Dedicated Checkout Portal (pay.php)
A beautiful, fully responsive #1769FF royal blue checkout page is displayed to customers — shows your SadaPay account details, amount in PKR, and a Transaction ID (TID) submission form with Sender Name & Account Number fields.

✅ Live Auto-Poller (3.5s Background Check)
Once the customer submits their TID, the page polls every 3.5 seconds in the background. As soon as the bank SMS webhook arrives, a "Payment Received!" success popup appears and auto-redirects to the invoice — no page refresh needed!

✅ MacroDroid SMS & App Notification Webhook
Works with 2 MacroDroid macros (SMS + App Notification). Supports the standard SadaPay SMS format (Rs. X received from NAME, Trx ID: XXXXXXX) and app notification format out of the box.

✅ Anti-Spoof Security Ledger
All transactions are tagged with a source column: 'sms', 'app_notification', 'webhook', 'email', 'simulator', or 'client_manual'. Only verified bank-origin transactions can auto-settle invoices — customers cannot fake a TID to self-approve their own invoice.

✅ HMAC-SHA256 Checkout Security
The pay.php URL is protected with a cryptographic hash token (hash_hmac SHA-256). No customer can tamper with the invoice ID in the URL.

✅ Underpayment Guard
If the bank SMS amount is less than the invoice total (tolerance: PKR 1.00), the invoice is NOT auto-approved — it is flagged as "underpaid" for admin review.

✅ Double-Spend & Replay Attack Protection
Before approving any payment, the system checks both WHMCS tblaccounts and the mod_sadapay_logs table to ensure the same TID has never been used before.

✅ MacroDroid Test Ping Compatibility (HTTP 200 Fix)
When MacroDroid's "Test Action" is triggered (with empty [sms_body]), the webhook returns HTTP 200 OK instead of 422, so your macro setup never shows an error.

✅ Admin Addon — SadaPay Manager
A full-featured WHMCS Addon Module with:
- KPI Dashboard: Total Volume, Approved Invoices, Pending count, Total logs
- Searchable Transaction Table (10/25/50/100 per page)
- Bulk Select & Delete (master checkbox + page-level selection)
- Purge Old Logs (7d / 15d / 30d / 60d / Wipe All)
- 1-Click Test Webhook Simulator (SMS, App Notification, MacroDroid Test Ping)
- Single Approve Modal with Sender Name & Account Number display
- Reject & Delete per-row actions

✅ Currency Auto-Conversion to PKR
Automatically converts any WHMCS invoice currency (USD, EUR, GBP, AED, etc.) to PKR using live WHMCS exchange rates, with fallback static rates.

✅ Sender Account Name & Number Fields
Customers provide their SadaPay account name and mobile number at checkout — stored in the transaction log for admin verification.

✅ CSRF Protection on All Admin Actions
Every admin POST action (approve, delete, bulk-delete, purge) is protected with WHMCS native token validation (generate_token('plain') + check_token()).

✅ PHP 7.4 – 8.3 & WHMCS 7.x – 8.11+ Compatible
Zero external Composer dependencies. Works on shared hosting.

━━━━━━━━━━━━━━━━━━━━━
📁 MODULE STRUCTURE (4 Files + Addon)
━━━━━━━━━━━━━━━━━━━━━

modules/
├── gateways/
│ ├── sadapay.php → Gateway config + checkout button
│ ├── callback/sadapay.php → Webhook listener (SMS/Notification parser)
│ └── sadapay/
│ ├── pay.php → Responsive checkout portal + Live Poller
│ └── helpers.php → DB setup, currency converter, HMAC, SMS parser
└── addons/
└── sadapay_manager/
└── sadapay_manager.php → Admin KPI dashboard + transaction manager

━━━━━━━━━━━━━━━━━━━━━
📱 MACRODROID SETUP (2 Macros)
━━━━━━━━━━━━━━━━━━━━━

SMS Macro JSON:
{
"secret": "YOUR_SECRET_KEY",
"sender": "[sms_number]",
"sms_body": "[sms_body]"
}

App Notification Macro JSON:
{
"secret": "YOUR_SECRET_KEY",
"sender": "SadaPay App",
"notification_title": "[not_title]",
"notification_body": "[not_body]"
}

━━━━━━━━━━━━━━━━━━━━━
⚙️ SETUP INSTRUCTIONS
━━━━━━━━━━━━━━━━━━━━━

1. Upload all files to your WHMCS root (maintain folder structure).
2. In WHMCS Admin → Setup → Payments → Payment Gateways → Activate SadaPay.
3. Enter your SadaPay mobile number, account title, and set a Webhook Secret Key.
4. Enter your CodeStar License Key to unlock the gateway.
5. In WHMCS Admin → Addons → SadaPay Manager → Activate.
6. Set up 2 MacroDroid macros on your phone pointing to:
https://yourdomain.com/modules/gateways/callback/sadapay.php
7. Use the built-in Test Simulator in SadaPay Manager to verify end-to-end flow.

━━━━━━━━━━━━━━━━━━━━━
🔒 REQUIREMENTS
━━━━━━━━━━━━━━━━━━━━━

- WHMCS 7.x or higher (tested up to 8.11+)
- PHP 7.4 – 8.3
- cURL extension enabled
- MacroDroid app on Android phone with SadaPay
- Active CodeStar License (domain-locked, auto-verified)