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 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_KEY
4. Compute MD5 hash in lowercase.
sign = strtolower(md5("amount=100.00&currency=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:

FieldTypeRequiredDescription
mchNoStringYesAssigned Merchant ID (e.g. 100333084)
mchOrderNoStringYesUnique Order Reference ID generated by your system
amountStringYesAmount in INR (e.g. 100.00)
currencyStringYesINR
versionStringYesV3
notifyUrlStringYesWebhook callback URL to receive instant payment alerts
returnUrlStringNoUser redirection URL after checkout
signStringYesMD5 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 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:

FieldTypeRequiredDescription
mchNoStringYesMerchant ID (e.g. 100333084)
mchOrderNoStringYesYour Merchant Order Reference ID
versionStringYesV1
signStringYesMD5 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)

FieldTypeRequiredDescription
mchNoStringYesMerchant ID
mchOrderNoStringYesOrder Reference ID
utrStringYes12-digit numeric banking transaction reference
versionStringYesV1
signStringYesMD5 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:

  1. Verify Signature: Compute MD5 hash of payload using your Secret Key and compare with sign.
  2. Validate Merchant ID: Verify mchNo matches your account.
  3. Check Order Existence: Query your database to ensure mchOrderNo exists.
  4. Verify Exact Amount: Ensure amount matches the order value stored in your database.
  5. Verify Currency: Ensure currency === 'INR'.
  6. Idempotency Check: If order is already marked SUCCESS, return HTTP 200 success without double-crediting.
  7. Duplicate Guard: Reject duplicate webhook transaction IDs.
  8. 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()
🔒

Protected API Documentation

Enter Developer Access Key to view integration manual

❌ Incorrect Access Key! Please check and retry.