ThuruvanPay Developer API

Integrate lightning-fast UPI payment collections into any website, mobile application, or billing portal. Our REST API generates Dynamic NPCI-compliant UPI QR codes and app-to-app UPI intent triggers that settle funds directly to your verified UPI VPA.

Base URL: http://localhost:5000/api (In production, replace with your live domain: https://pay.yourdomain.com/api).

Authentication

All API requests must include your merchant credentials in the HTTP request headers:


            x-api-key: key_your_unique_merchant_api_key

            x-api-secret: sec_your_unique_merchant_api_secret

            Content-Type: application/json

You can find your API credentials directly in your Merchant Dashboard.

POST /api/create-order

Create Payment Order

Initiates a transaction and returns dynamic QR code data alongside direct UPI app intent URLs.

Request Body (JSON)

Field	Type	Required	Description
amount	Number	Yes	Amount in Indian Rupees (e.g., 299.00)
customer_name	String	Optional	Name of the paying customer
customer_mobile	String	Optional	10-digit mobile number
redirect_url	String	Optional	URL to redirect customer upon payment completion
webhook_url	String	Optional	Custom webhook listener for this specific order

Integration Examples

// 1. PHP cURL Example (Just like MugavaiGroups / ZapUPI)

<?php
$apiKey = "YOUR_API_KEY";
$apiSecret = "YOUR_API_SECRET";

$data = [
    "amount" => 500,
    "customer_name" => "Ramesh Kumar",
    "customer_mobile" => "9876543210",
    "redirect_url" => "https://yoursite.com/order-success.php"
];

$ch = curl_init("http://localhost:5000/api/create-order");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "x-api-key: " . $apiKey,
    "x-api-secret: " . $apiSecret
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
if ($result["status"]) {
    // Redirect user to payment checkout page:
    header("Location: " . $result["data"]["payment_url"]);
    exit;
}
?>

Response Sample

{
  "status": true,
  "message": "Order created successfully",
  "data": {
    "order_id": "ORD_1728471928_4921",
    "amount": 500,
    "currency": "INR",
    "upi_vpa": "mybusiness@paytm",
    "payment_url": "http://localhost:5000/checkout.html?order_id=ORD_1728471928_4921",
    "upi_intent": "upi://pay?pa=mybusiness@paytm&pn=Store&am=500.00&cu=INR&tr=ORD_1728471928_4921",
    "qr_code": "data:image/png;base64,iVBORw0KGgo...",
    "created_at": "2026-10-09T18:50:00.000Z"
  }
}

POST /api/check-order-status

Check Order Status

Query transaction status programmatically using Order ID.

curl -X POST http://localhost:5000/api/check-order-status \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET" \
  -d '{"order_id": "ORD_1728471928_4921"}'

Webhook Callbacks

When a customer pays, our gateway triggers an HTTP POST request to your webhook URL. The request contains the signature in the X-Gateway-Signature header.

// PHP Webhook Listener (`webhook.php` on your website)

<?php
$apiSecret = "YOUR_API_SECRET";
$input = file_get_contents("php://input");
$receivedSig = $_SERVER["HTTP_X_GATEWAY_SIGNATURE"] ?? "";

// Verify authenticity with HMAC-SHA256
$computedSig = hash_hmac("sha256", $input, $apiSecret);

if (hash_equals($computedSig, $receivedSig)) {
    $data = json_decode($input, true);
    if ($data["status"] === "SUCCESS") {
        $orderId = $data["order_id"];
        $amount = $data["amount"];
        $utr = $data["utr"]; // 12-digit Bank UTR

        // Update your database here!
    }
    http_response_code(200);
    echo json_encode(["status" => "ok"]);
} else {
    http_response_code(403);
    echo "Invalid Signature";
}
?>

Interactive Live API Tester

Test the API directly from this browser page!