Airtel Retailer & Merchant API Documentation
Active Host: https://airtel.gurupaygateway.com/
📖 System Architecture & Overview
This API suite provides 100% native Pure PHP integration with Airtel Payments Bank's Retailer & Merchant backend (https://retailerapp.airtelpayments.bank.in/RetailerPortal/), completely reverse-engineered from the official com.apbl.merchant Android APK (v26.9.4 / v26.10.5).
🔒 Pure PHP Cryptography
AES-192-GCM body encryption combined with RSA-2048 / ECB / OAEP-SHA256 MGF1 key encapsulation. Runs entirely on OpenSSL with zero Python or external CLI binaries.
🚀 cPanel Shared Hosting Ready
Designed to run seamlessly on Linux, Windows, or cPanel shared hosting without root access, terminal python packages, or cron bottlenecks.
💳 Complete UPI & Passbook Suite
Full support for Merchant Login OTP, MPIN authentication, QR string generation, real-time transaction passbook history, and on-demand instant settlements.
⚡ Session Persistence
Secure local state caching in session.json keeps active tokens, merchant VPAs, shop names, and device identifiers in persistent sync.
Triggers SMS OTP delivery to the registered merchant or retailer mobile number. Dispatches an encrypted payload matching APK API v1/onboarding/otp with channel RAPP and version 2.0.
| Parameter | Type | Required | Description |
|---|---|---|---|
| mobile_number | string | YES | 10-digit registered Indian merchant mobile number (e.g. XXXXXXXXXX). |
curl -X POST "https://airtel.gurupaygateway.com/request-otp.php" \
-H "Content-Type: application/json" \
-d '{"mobile_number": "XXXXXXXXXX"}'
{
"status": "success",
"message": "sms sent",
"verification_token": "f46ad814-aa84-409d-a2b0-ffc72765fecc",
"fe_session_id": "AN261107175647340",
"data": {
"fesessionid": "AN261107175647340",
"verificationToken": "f46ad814-aa84-409d-a2b0-ffc72765fecc"
},
"meta": {
"code": "000",
"description": "sms sent",
"status": 0
}
}
Verifies the 6-digit SMS OTP received on merchant's phone alongside the verification_token. On success, returns the session JWT token and persists it in session.json.
| Parameter | Type | Required | Description |
|---|---|---|---|
| mobile_number | string | YES | 10-digit registered merchant mobile number. |
| otp | string | YES | 6-digit numeric OTP code received via SMS. |
| verification_token | string | OPTIONAL | Verification token from Step 1 (auto-retrieved from session if omitted). |
curl -X POST "https://airtel.gurupaygateway.com/validate-otp.php" \
-H "Content-Type: application/json" \
-d '{
"mobile_number": "XXXXXXXXXX",
"otp": "123456",
"verification_token": "f46ad814-aa84-409d-a2b0-ffc72765fecc"
}'
{
"status": "success",
"message": "OTP verified successfully. Merchant authenticated.",
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
"mobile_number": "XXXXXXXXXX",
"meta": {
"status": "0",
"code": "0000",
"description": "Success"
}
}
Retrieves full merchant profile details including Shop Name, settlement bank account number, IFSC code, and account holder name.
| Parameter | Type | Required | Description |
|---|---|---|---|
| token | string | OPTIONAL | Active JWT Token (auto-loaded from session if omitted). |
| mpin | string | OPTIONAL | 4-digit MPIN if profile is MPIN-locked. |
curl -X POST "https://airtel.gurupaygateway.com/profile.php" \
-H "Content-Type: application/json" \
-d '{"mpin": "1234"}'
Fetches the official merchant UPI QR code payload string, VPAs (e.g. airtel.pay.xxx@airtel), and renders a real-time QR image.
curl -X GET "https://airtel.gurupaygateway.com/get-qr.php"
{
"status": "success",
"message": "Merchant UPI QR Code retrieved successfully.",
"merchant_id": "AIRTEL123456",
"shop_name": "Demo Merchant Store",
"qr_string": "upi://pay?pa=merchant.mer@airtel&pn=Demo%20Store&cu=INR",
"qr_image_url": "https://api.qrserver.com/v1/create-qr-code/?size=300x300&data=...",
"vpas": ["merchant.mer@airtel"]
}
Fetches the comprehensive list of incoming merchant collections, transaction UTR numbers, amounts, customer VPAs, and timestamps across customized date ranges.
| Parameter | Type | Required | Description |
|---|---|---|---|
| fromDate | string | OPTIONAL | Start date in YYYY-MM-DD format (defaults to -30 days). |
| toDate | string | OPTIONAL | End date in YYYY-MM-DD format (defaults to current date). |
| page | int | OPTIONAL | Page index (0-based, default 0). |
| records | int | OPTIONAL | Number of records per page (default 50). |
curl -X POST "https://airtel.gurupaygateway.com/transactions.php" \
-H "Content-Type: application/json" \
-d '{
"fromDate": "2026-11-01",
"toDate": "2026-11-08",
"page": 0,
"records": 50
}'
Checks status and details of the latest payout / settlement dispatched to merchant's registered bank account.
curl -X POST "https://airtel.gurupaygateway.com/settlements.php" \
-H "Content-Type: application/json" \
-d '{"mobile_number": "XXXXXXXXXX"}'
Triggers instant on-demand settlement of current collected merchant balance into the registered bank account via IMPS/NEFT.
curl -X POST "https://airtel.gurupaygateway.com/settle-now.php" \
-H "Content-Type: application/json" \
-d '{"mobile_number": "XXXXXXXXXX"}'
Automated background script for scheduled polling. Syncs latest transactions, records daily collections, and optionally triggers auto-settlement. Configure in cPanel Cron Jobs.
*/5 * * * * /usr/bin/php /home/u870336084/domains/gurupaygateway.com/public_html/RetailerPortal/cron.php >/dev/null 2>&1