Authentication
Base URL: https://qrconfirm-api.superiorgems.workers.dev. Send your secret API key from the dashboard in every request. Keep it on your server; never put it in a web page or app.
Authorization: Bearer sk_live_your_keyAmounts in requests are rupees (whole or two decimals). Times are Unix milliseconds.
POST/v1/orders
Creates an order and holds a unique paise amount on your UPI ID for 30 minutes.
| Field | Type | Notes |
|---|---|---|
amount | number | Required. Rupees, e.g. 500 or 499.50. |
ref | string | Required. Your own order ID. |
return_url | string | Optional. Where the buyer goes after “Paid”. |
customer | object | Optional. {name, email, phone}. Email is used for the receipt. |
curl -X POST https://qrconfirm-api.superiorgems.workers.dev/v1/orders \
-H "Authorization: Bearer sk_live_your_key" \
-H "Content-Type: application/json" \
-d '{"amount": 500, "ref": "A-1042", "return_url": "https://shop.example/thanks",
"customer": {"name": "Rahul", "email": "rahul@example.com"}}'Response 201:
{
"id": "ord_8f2k1x",
"status": "open",
"amount_requested": "500.00",
"amount_exact": "500.37",
"amount_paise": 50037,
"pay_url": "https://qrconfirm-api.superiorgems.workers.dev/pay/ord_8f2k1x",
"upi_uri": "upi://pay?pa=yourshop@ybl&am=500.37&tn=A-1042",
"expires_at": 1763715121000
}Send the buyer to pay_url, or show amount_exact and your own QR. If all 99 paise slots for that rupee amount are busy, you get 409 {"error": "slots_full"}; try again shortly or change the amount by a rupee.
GET/v1/orders/:id
Returns the order. status is open, paid, expired or cancelled. Paid orders also carry paid_via (notification, email or manual) and the bank utr.
curl https://qrconfirm-api.superiorgems.workers.dev/v1/orders/ord_8f2k1x \
-H "Authorization: Bearer sk_live_your_key"POST/v1/orders/:id/cancel
Cancels an open order and frees its paise slot. A payment that arrives later for that amount goes to your unmatched list.
Webhook: order.paid
When an order is paid we POST to the webhook URL you set in the dashboard. Reply with any 2xx. If you don't, we retry later, so handle the same order ID arriving twice.
POST /your/webhook
Content-Type: application/json
X-QRC-Signature: t=1763713321000,v1=5f0c…e91a
{"event": "order.paid", "order": {"id": "ord_8f2k1x", "ref": "A-1042", "status": "paid",
"amount_exact": "500.37", "paid_via": "notification", "utr": "432112345678"}}Verify the signature
v1 is the hex HMAC-SHA256 of t + "." + rawBody, keyed with your webhook secret. Use the raw request body exactly as received. Do not parse and re-serialise the JSON first. We suggest rejecting timestamps older than 5 minutes.
import crypto from "node:crypto";
export function verifyQrc(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const expected = crypto.createHmac("sha256", secret)
.update(parts.t + "." + rawBody).digest("hex");
const given = String(parts.v1 || "");
const same = given.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
const fresh = Math.abs(Date.now() - Number(parts.t)) < 5 * 60 * 1000;
return same && fresh;
}Pay button
No server code? Drop this where the pay button should appear. It opens the payment page for that amount and reference.
<script src="https://qrconfirm-api.superiorgems.workers.dev/qrc.js"
data-amount="500"
data-ref="A-1042"
async></script>Button setup for your account is shown in the dashboard.
Errors
Errors return a plain message: {"error": "…"}.
| Status | Meaning |
|---|---|
400 | Something in the request is missing or wrong. |
401 | API key missing or not valid. |
404 | No such order on your account. |
409 | slots_full: 99 orders for that rupee amount are already open. |
Stuck? Email business@oias.in with the order ID.