KHQR Pay API Documentation

1. Create an account — your API key is generated automatically.
2. Save your Merchant ID and Merchant Name in the dashboard.
3. Call POST /qr to generate a KHQR.
4. Poll POST /transaction/check to see when it's paid.

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer khqr_live_xxxxxxxxxxxxxxxxxxxxxxxx

Get your key from the dashboard — it's generated automatically on signup. All requests and responses use Content-Type: application/json.

For a real customer checkout, keep your KHQR API key on your own server. Your website calls your backend, then your backend calls KHQR Pay. This prevents visitors from copying your live API key from browser devtools.

<button id="pay">Pay with KHQR</button>
<pre id="result"></pre>

<script>
document.getElementById("pay").addEventListener("click", async () => {
  const res = await fetch("/api/create-khqr", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      amount: 5,
      currency: "USD",
      order_id: "ORDER-" + Date.now()
    })
  });

  const data = await res.json();
  document.getElementById("result").textContent = JSON.stringify(data, null, 2);

  // Render data.qr with any QR library, then poll your backend with data.md5.
});
</script>

// Node.js / Express example
app.post("/api/create-khqr", async (req, res) => {
  const r = await fetch("https://apikhqr.kesor.cam/api/v1/qr", {
    method: "POST",
    headers: {
      "Authorization": "Bearer " + process.env.KHQR_API_KEY,
      "Content-Type": "application/json"
    },
    body: JSON.stringify(req.body)
  });

  res.status(r.status).json(await r.json());
});

app.post("/api/check-khqr", async (req, res) => {
  const r = await fetch("https://apikhqr.kesor.cam/api/v1/transaction/check", {
    method: "POST",
    headers: {
      "Authorization": "Bearer " + process.env.KHQR_API_KEY,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ md5: req.body.md5 })
  });

  res.status(r.status).json(await r.json());
});

Direct browser calls to https://apikhqr.kesor.cam/api/v1 are CORS-enabled for testing, but production websites should proxy through a backend so the API key stays private.

Every error response has this shape. Branch on HTTP status, never on the human message.

{
  "error": "bad_request",
  "message": "amount must be a positive number"
}

Pass an order_id when generating a QR. If the same order_id is sent again, the existing QR + md5 are returned (with idempotent_replay: true) instead of generating a new one — safe for client retries.

Each API key is limited per minute, in addition to your plan's daily quota:

• POST /qr — 60 req/min
• POST /transaction/check — 120 req/min
• POST /transaction/by-order — 120 req/min

When exceeded you get 429 with Retry-After + X-RateLimit-Limit / X-RateLimit-Remaining headers.

Add an endpoint URL in the dashboard. We POST a JSON event whenever a transaction transitions to paid. Failed deliveries retry with exponential backoff (up to 5 attempts).

POST https://your.app/webhook
X-KHQR-Signature: t=1715600000,v1=<hmac_sha256_hex>
X-KHQR-Timestamp: 1715600000
X-KHQR-Delivery-Id: <uuid>
X-KHQR-Event: transaction.paid
Content-Type: application/json

{
  "event": "transaction.paid",
  "md5": "a1b2c3...",
  "amount": 5.00,
  "currency": "USD",
  "bill_number": "INV-001",
  "paid_at": "2026-05-13T14:00:00.000Z",
  "transaction_id": "uuid",
  "external_order_id": "ORDER-1042"
}

Verifying signatures (Node.js):

import crypto from "crypto";

function verify(rawBody, headers, secret) {
  const sigHeader = headers["x-khqr-signature"]; // "t=...,v1=..."
  const ts = Number(headers["x-khqr-timestamp"]);
  if (!sigHeader || !ts) return false;

  // 1. Reject stale requests (replay protection)
  if (Math.abs(Date.now() / 1000 - ts) > 300) return false;

  // 2. Recompute HMAC over "<ts>.<raw_body>" using the RAW body (do not re-serialize JSON)
  const v1 = sigHeader.split(",").find(p => p.startsWith("v1="))?.slice(3);
  const expected = crypto.createHmac("sha256", secret)
    .update(`${ts}.${rawBody}`).digest("hex");

  // 3. Constant-time compare
  if (!v1 || v1.length !== expected.length) return false;
  return crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));

  // 4. Also dedupe by X-KHQR-Delivery-Id in your DB to guard against replays.
}

KHQR Pay generates payment QR codes that conform to the National Bank of Cambodia's KHQR EMV standard, scannable by ABA, Wing, ACLEDA, and any Bakong-enabled bank app. Configure your Merchant ID (Bakong account ID, e.g. name@aclb) and Merchant Name in the dashboard once — the API uses them automatically.

1. Customer clicks Pay on your store.
2. Your server calls POST /qr with the amount.
3. Render the returned qr string as a QR image.
4. Poll POST /transaction/check with the md5 every ~3s.
5. When status is paid, fulfill the order.

const r = await fetch("https://apikhqr.kesor.cam/api/v1/qr", {
  method: "POST",
  headers: {
    "Authorization": "Bearer khqr_live_xxxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ amount: 25.00, currency: "USD", bill_number: "ORDER-1042" }),
}).then(r => r.json());

console.log(r.qr, r.md5);

// Poll for payment
const poll = async () => {
  const s = await fetch("https://apikhqr.kesor.cam/api/v1/transaction/check", {
    method: "POST",
    headers: { "Authorization": "Bearer khqr_live_xxx", "Content-Type": "application/json" },
    body: JSON.stringify({ md5: r.md5 }),
  }).then(r => r.json());
  if (s.status === "paid") return console.log("PAID");
  setTimeout(poll, 3000);
};
poll();