VardhanPay API Specification
The VardhanPay API enables high-throughput digital payments via dynamic UPI QR codes, direct app intent deep-links (Paytm, PhonePe, Google Pay, BHIM), and automated webhook reconciliation.
1. Environment & Base URLs
| Endpoint Role | Standard RESTful Route | Alias Route |
|---|---|---|
| Create Payin | https://api.vardhanpay.com/api/v1/payin/create |
https://api.vardhanpay.com/findRealChannel |
| Query Order | https://api.vardhanpay.com/api/v1/payin/query |
https://api.vardhanpay.com/findOrderStatus |
| Submit UTR | https://api.vardhanpay.com/api/v1/payin/utr/submit |
https://api.vardhanpay.com/uploadUtr |
2. Signature Algorithm (MD5 HMAC)
All API requests must include a cryptographic signature calculated using your Merchant Secret Key:
Signature Formula:
1. Remove
2. Sort remaining keys in case-insensitive ASCII alphabetical order (
3. Form URL query string:
4. Compute MD5 hash in lowercase.
1. Remove
sign, deepLinks, and empty/null parameters.2. Sort remaining keys in case-insensitive ASCII alphabetical order (
uksort($data, 'strcasecmp')).3. Form URL query string:
key1=val1&key2=val2&...&key=YOUR_SECRET_KEY4. Compute MD5 hash in lowercase.
sign = strtolower(md5("amount=100.00¤cy=INR&mchNo=100333084&mchOrderNo=ORD_101&version=V3&key=YOUR_SECRET_KEY"));
3. Create Payin Order
POST /api/v1/payin/create (or /findRealChannel)
Request Headers:
Content-Type: application/json
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
mchNo | String | Yes | Assigned Merchant ID (e.g. 100333084) |
mchOrderNo | String | Yes | Unique Order Reference ID generated by your system |
amount | String | Yes | Amount in INR (e.g. 100.00) |
currency | String | Yes | INR |
version | String | Yes | V3 |
notifyUrl | String | Yes | Webhook callback URL to receive instant payment alerts |
returnUrl | String | No | User redirection URL after checkout |
sign | String | Yes | MD5 signature calculated with your secret key |
🔒 High-Security Architecture (Mandatory Redirection):
VardhanPay enforces a strict Hosted Redirection Architecture. Merchants must redirect the end-user to the returned
VardhanPay enforces a strict Hosted Redirection Architecture. Merchants must redirect the end-user to the returned
payUrl. Raw UPI ID / Headless extraction is permanently blocked for anti-fraud banking compliance and dynamic anti-tampering protection.
Success Response (code: 0):
{
"code": 0,
"msg": "Success",
"retCode": "SUCCESS",
"retMsg": "Order Created Successfully",
"data": {
"orderId": "VP2026082603150012",
"mchOrderNo": "ORD_101",
"amount": "100.00",
"currency": "INR",
"payUrl": "https://api.vardhanpay.com/ORD_101",
"status": "0"
}
}
4. Query Order Status
POST /api/v1/payin/query (or /findOrderStatus)
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
mchNo | String | Yes | Merchant ID (e.g. 100333084) |
mchOrderNo | String | Yes | Your Merchant Order Reference ID |
version | String | Yes | V1 |
sign | String | Yes | MD5 signature |
Response (code: 0):
{
"code": 0,
"msg": "Success",
"data": {
"status": 2, // 1: PENDING, 2: SUCCESS, 3: FAILED
"payinState": 2, // 1: PENDING, 2: SUCCESS, 3: FAILED
"amount": "100.00",
"mchOrderNo": "ORD_101"
}
}
5. Submit Banking UTR
POST /api/v1/payin/utr/submit (or /uploadUtr)
| Field | Type | Required | Description |
|---|---|---|---|
mchNo | String | Yes | Merchant ID |
mchOrderNo | String | Yes | Order Reference ID |
utr | String | Yes | 12-digit numeric banking transaction reference |
version | String | Yes | V1 |
sign | String | Yes | MD5 signature |
6. Bank-Grade 8-Point Webhook Verification
When a customer pays, VardhanPay sends an HTTP POST webhook to your notifyUrl. For maximum financial security, your server must implement all 8 verification checks:
- Verify Signature: Compute MD5 hash of payload using your Secret Key and compare with
sign. - Validate Merchant ID: Verify
mchNomatches your account. - Check Order Existence: Query your database to ensure
mchOrderNoexists. - Verify Exact Amount: Ensure
amountmatches the order value stored in your database. - Verify Currency: Ensure
currency === 'INR'. - Idempotency Check: If order is already marked
SUCCESS, return HTTP 200successwithout double-crediting. - Duplicate Guard: Reject duplicate webhook transaction IDs.
- Atomic DB Transaction: Execute order update & wallet balance credit inside an atomic SQL transaction (
beginTransaction/commit).
Expected Callback Response:
Respond with HTTP Status 200 OK and plain text string:
success
7. Production PHP 7.4+ SDK
<?php
class VardhanPayClient {
private $mchNo;
private $secretKey;
private $baseUrl = 'https://api.vardhanpay.com';
public function __construct($mchNo, $secretKey) {
$this->mchNo = $mchNo;
$this->secretKey = $secretKey;
}
public function createPayin($orderNo, $amount, $notifyUrl) {
$params = [
'mchNo' => $this->mchNo,
'mchOrderNo' => $orderNo,
'amount' => number_format((float)$amount, 2, '.', ''),
'currency' => 'INR',
'version' => 'V3',
'notifyUrl' => $notifyUrl
];
$params['sign'] = $this->generateSign($params);
return $this->httpPost('/api/v1/payin/create', $params);
}
public function queryOrder($orderNo) {
$params = [
'mchNo' => $this->mchNo,
'mchOrderNo' => $orderNo,
'version' => 'V1'
];
$params['sign'] = $this->generateSign($params);
return $this->httpPost('/api/v1/payin/query', $params);
}
private function generateSign($data) {
unset($data['sign'], $data['deepLinks']);
uksort($data, 'strcasecmp');
$str = urldecode(http_build_query($data)) . '&key=' . $this->secretKey;
return strtolower(md5($str));
}
private function httpPost($endpoint, $payload) {
$ch = curl_init($this->baseUrl . $endpoint);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
$resp = curl_exec($ch);
curl_close($ch);
return json_decode($resp, true);
}
}
8. Python Integration Example
import hashlib
import requests
import urllib.parse
def create_vardhanpay_order(mch_no, secret_key, order_no, amount, notify_url):
params = {
"mchNo": str(mch_no),
"mchOrderNo": str(order_no),
"amount": f"{float(amount):.2f}",
"currency": "INR",
"version": "V3",
"notifyUrl": notify_url
}
# Sort keys alphabetically
sorted_keys = sorted(params.keys(), key=lambda s: s.lower())
query_str = "&".join([f"{k}={params[k]}" for k in sorted_keys]) + f"&key={secret_key}"
params["sign"] = hashlib.md5(query_str.encode("utf-8")).hexdigest().lower()
res = requests.post("https://api.vardhanpay.com/api/v1/payin/create", json=params)
return res.json()