API Reference

X-Api-Key: key_live_placeholder
X-Api-Secret: sec_live_placeholder
Accept: application/json
Content-Type: application/json

X-Api-Key: test_key_placeholder
X-Api-Secret: test_sec_placeholder
Accept: application/json
Content-Type: application/json

curl -X POST https://gateway.example.com/api/v1/orders \
  -H "X-Api-Key: key_live_placeholder" \
  -H "X-Api-Secret: sec_live_placeholder" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"amount": 199, "client_order_id": "INV1001", "redirect_url": "https://yoursite.com/thanks"}'

{
  "success": true,
  "data": {
    "order_id": "ORDAB12CD34EF56GH78",
    "client_order_id": "INV1001",
    "amount": "199.00",
    "currency": "INR",
    "status": "pending",
    "environment": "live",
    "test": false,
    "utr": null,
    "submitted_utr": null,
    "payment_url": "https://gateway.example.com/pay/ORDAB12CD34EF56GH78",
    "upi_intent": "upi://pay?pa=merchant@upi&am=199.00&tr=ORDAB12CD34EF56GH78",
    "customer": {"name": null, "email": null, "mobile": null},
    "paid_at": null,
    "expires_at": "2026-11-07T12:15:00+05:30",
    "created_at": "2026-11-07T12:00:00+05:30"
  }
}

curl https://gateway.example.com/api/v1/orders/INV1001 \
  -H "X-Api-Key: key_live_placeholder" \
  -H "X-Api-Secret: sec_live_placeholder" \
  -H "Accept: application/json"

{
  "success": true,
  "data": {
    "order_id": "ORDAB12CD34EF56GH78",
    "client_order_id": "INV1001",
    "amount": "199.00",
    "currency": "INR",
    "status": "paid",
    "environment": "live",
    "test": false,
    "utr": "427123456789",
    "submitted_utr": null,
    "payment_url": "https://gateway.example.com/pay/ORDAB12CD34EF56GH78",
    "upi_intent": "upi://pay?pa=merchant@upi&am=199.00&tr=ORDAB12CD34EF56GH78",
    "customer": {"name": null, "email": null, "mobile": null},
    "paid_at": "2026-11-07T12:10:00+05:30",
    "expires_at": "2026-11-07T12:15:00+05:30",
    "created_at": "2026-11-07T12:00:00+05:30"
  }
}

{
  "success": true,
  "environment": "live",
  "rotation_mode": "random",
  "data": [
    {
      "id": 3,
      "label": "Shop 1",
      "upi_id": "merchant@paytm",
      "provider": "paytm_business",
      "is_active": true,
      "is_default": true,
      "daily_limit": "100000.00",
      "used_today": "42500.00",
      "remaining_today": "57500.00"
    }
  ]
}

{
  "event": "order.paid",
  "event_id": "00000000-0000-4000-8000-000000000001",
  "event_sequence": 2,
  "occurred_at": "2026-11-07T12:10:00+05:30",
  "data": {
    "order_id": "ORDAB12CD34EF56GH78",
    "client_order_id": "INV1001",
    "amount": "199.00",
    "currency": "INR",
    "status": "paid",
    "environment": "live",
    "test": false,
    "utr": "4271234567890",
    "submitted_utr": null,
    "payment_url": "https://gateway.example.com/pay/ORDAB12CD34EF56GH78",
    "upi_intent": "upi://pay?pa=merchant@upi&am=199.00&tr=ORDAB12CD34EF56GH78",
    "customer": {"name": null, "email": null, "mobile": null},
    "paid_at": "2026-11-07T12:10:00+05:30",
    "expires_at": "2026-11-07T12:15:00+05:30",
    "created_at": "2026-11-07T12:00:00+05:30"
  }
}

<?php
$body      = file_get_contents("php://input");
$secret    = getenv("PAYMENT_WEBHOOK_SECRET");
$header    = $_SERVER["HTTP_X_SIGNATURE"] ?? "";

// Parse t=timestamp,v1=signature
$params = [];
foreach (explode(",", $header) as $pair) {
    $p = explode("=", trim($pair), 2);
    if (count($p) === 2) { $params[trim($p[0])] = trim($p[1]); }
}

$timestamp = isset($params["t"]) ? (int) $params["t"] : 0;
$signature = $params["v1"] ?? "";

// 1. Replay defense: 5-minute tolerance (300 seconds)
if (abs(time() - $timestamp) > 300) {
    http_response_code(401);
    exit("Webhook timestamp expired or invalid");
}

// 2. Verify signature: HMAC-SHA256 of timestamp + "." + body
$expected = hash_hmac("sha256", "{$timestamp}.{$body}", $secret);
if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit("Invalid signature");
}

// 3. Deduplicate event transactionally and process
$event = json_decode($body, true);
// Check your database: if event_id already processed, return 200 OK without double-fulfilling.
if ($event["event"] === "order.paid") {
    // Fulfil $event["data"]["client_order_id"] idempotently
}
http_response_code(200);

const crypto = require("crypto");

app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("X-Signature") || "";
  const secret = process.env.PAYMENT_WEBHOOK_SECRET;

  // Parse t=timestamp,v1=signature
  const params = Object.fromEntries(header.split(",").map(p => p.split("=")));
  const timestamp = parseInt(params.t, 10);
  const signature = params.v1 || "";

  // 1. Replay defense: 5-minute tolerance (300 seconds)
  const now = Math.floor(Date.now() / 1000);
  if (isNaN(timestamp) || Math.abs(now - timestamp) > 300) {
    return res.status(401).send("Webhook timestamp expired or invalid");
  }

  // 2. Verify signature
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${req.body}`)
    .digest("hex");

  if (signature.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
    return res.status(401).send("Invalid signature");
  }

  // 3. Deduplicate event_id and process
  const event = JSON.parse(req.body);
  if (event.event === "order.paid") {
    // Fulfil event.data.client_order_id (idempotently)
  }
  res.sendStatus(200);
});

{
  "message": "The amount field must be at least 1.",
  "errors": {
    "amount": ["The amount field must be at least 1."]
  }
}

const response = await fetch("https://gateway.example.com/api/v1/orders", {
  method: "POST",
  headers: {
    "X-Api-Key": process.env.PAYMENT_API_KEY,
    "X-Api-Secret": process.env.PAYMENT_API_SECRET,
    "Accept": "application/json",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ amount: 199, client_order_id: "INV1001" }),
});
if (!response.ok) throw new Error(`API error ${response.status}`);
const { data } = await response.json();
console.log(data.payment_url);

<?php
$client = new GuzzleHttp\Client(["base_uri" => "https://gateway.example.com/api/v1"]);

$res = $client->post("/orders", [
    "headers" => [
        "X-Api-Key"    => getenv("PAYMENT_API_KEY"),
        "X-Api-Secret" => getenv("PAYMENT_API_SECRET"),
        "Accept"       => "application/json",
    ],
    "json" => ["amount" => 199, "client_order_id" => "INV1001"],
]);

$data = json_decode($res->getBody(), true);
$paymentUrl = $data["data"]["payment_url"];