Two KHQR rails. One payment contract.

Obtain a key

Log in, open the API keys page, create a key, and copy it.

Store the copied value in your server's .env file, for example BONGLUY_API_KEY=sk_live_.... Keep it on the server and never expose it in browser code.

Key facts worth knowing up front

Scope

Keys belong to the account, not to one store. A key reaches every store the account owns.

Lifetime

90 days. Rotate before the deadline; an expired key fails as 401, the same as an invalid one.

Name

Up to 32 characters. It is a label for you and carries no meaning to the API.

Recovery

None. Only the hash is kept, so a lost key must be replaced rather than looked up.

Use one store per destination you collect into: a branch, an outlet, a brand, or a separate business line. Registering several is normal, and there is no limit to plan around. Your single API key already reaches all of them, so switching destinations is a matter of naming a different store on the request, not of holding a second credential.

Send one identifier or the other. A request with neither fails validation; if both are present, storeId wins. Register merchantStoreId when you create the store and you never have to store Bongluy'sstoreId at all — your own id addresses the store everywhere it is accepted.

Omitting merchantStoreId is valid, and stores without one do not collide with each other. Those stores can only be addressed with Bongluy's storeId, which is the mapping supplying your own id avoids.

{
  "id": "76e0cdea-ab74-455d-b46e-3b9e50f679a2",
  "userId": "c1f0...",
  "name": "Tykea Coffee",
  "merchantStoreId": "branch-2",
  "paywayLink": "https://link.payway.com.kh/aba?id=usd...",
  "khrPaywayLink": "https://link.payway.com.kh/aba?id=khr...",
  "bakongAccountId": "your_name@aclb",
  "webhookUrl": null,
  "active": true,
  "createdAt": "2026-08-14T03:11:22.418Z",
  "updatedAt": "2026-08-14T03:11:22.418Z"
}

webhookSecret is accepted on writes but never returned.

curl https://api.bongluy.com/stores \
  -H 'authorization: Bearer sk_live_...'

curl -X POST https://api.bongluy.com/stores/detail \
  -H 'authorization: Bearer sk_live_...' \
  -H 'content-type: application/json' \
  -d '{"merchantStoreId":"branch-2"}'

curl -X POST https://api.bongluy.com/stores \
  -H 'authorization: Bearer sk_live_...' \
  -H 'content-type: application/json' \
  -d '{"name":"Tykea Coffee","merchantStoreId":"branch-2","paywayLink":"https://link.payway.com.kh/aba?id=usd...","khrPaywayLink":"https://link.payway.com.kh/aba?id=khr...","bakongAccountId":"your_name@aclb"}'

curl -X POST https://api.bongluy.com/stores/update \
  -H 'authorization: Bearer sk_live_...' \
  -H 'content-type: application/json' \
  -d '{"merchantStoreId":"branch-2","changes":{"active":false}}'

curl -X POST https://api.bongluy.com/payment \
  -H 'authorization: Bearer sk_live_...' \
  -H 'content-type: application/json' \
  -d '{"merchantStoreId":"branch-2","amount":"12500","currency":"KHR","provider":"BAKONG","tranId":"INV-1042"}'

{
  "id": "8435481a-48a8-4bb2-91d2-bcd1e604fb17",
  "storeId": "76e0cdea-ab74-455d-b46e-3b9e50f679a2",
  "status": "PENDING",
  "amount": "12500",
  "currency": "KHR",
  "paywayLink": null,
  "khqrMd5": "e0f3d55c4ca178f4d2c45e99d4d9d7f8",
  "checkoutUrl": "https://www.bongluy.com/payment/8435481a-48a8-4bb2-91d2-bcd1e604fb17",
  "expireAt": "2026-08-14T03:14:22.418Z",
  "settledTranId": null,
  "receiptUrl": null,
  "tranId": "INV-1042",
  "lastError": null,
  "createdAt": "2026-08-14T03:11:22.418Z",
  "updatedAt": "2026-08-14T03:11:22.418Z",
  "settledAt": null,
  "qrString": "00020101021230...",
  "deeplink": null
}

Money on the wire

amount is a string because decimal money should not pass through JSON floating-point values. It must match^\d+(\.\d{1,2})?$. The currency-specific minimums are 0.01 USD and 100 KHR.

currency selects USD or KHR. On ABA it also selects the matching PayWay link. On Bakong no link is involved; KHR amounts must be whole numbers because the KHQR carries no riel decimals.

Use tranId for safe retries

tranId is unique within a store. Repeating a create request with an existing tranId returns the original payment verbatim, without a second upstream call. This makes a timed-out create safe to retry. Both payment read routes also accept tranId, so your system can work entirely with its own store and transaction identifiers.

The original response also wins if a retry changes amount, currency, or provider. Treat tranId as the identity of one payment intent, not as a request-deduplication header.

Payments without tranId do not collide, but a lost create response cannot then be recovered through your own identifier, which leaves Bongluy's UUID as the only way back to the payment. Send a tranId on every create and that case disappears.

You do not need to store Bongluy's ids

Integrating requires no new table, no migration, and no new columns for id or storeId. Every route can be addressed with identifiers your system already owns, so Bongluy's UUIDs never have to be persisted.

Register merchantStoreId when the store is created and send a tranId on every payment. That pair then addresses the payment for the rest of its life — status, detail, and retries alike. Bongluy stays the system of record for payment state; read it back with the pair rather than mirroring it locally.

Provider clocks are part of the response

Read expireAt from every payment response. ABA payments are normally payable for 24 hours even though automatic status checks pause sooner. A dynamic Bakong KHQR normally expires in about three minutes, and its QR actually dies at that instant.

An inactive, missing, or foreign store returns404 "unknown store". The response deliberately does not reveal which condition applied.

curl 'https://api.bongluy.com/payment?merchantStoreId=branch-2&status=SUCCESS&per_page=50' \
  -H 'authorization: Bearer sk_live_...'

{
  "data": [
    {
      "id": "8435481a-48a8-4bb2-91d2-bcd1e604fb17",
      "status": "SUCCESS",
      "amount": "12.50",
      "tranId": "INV-1042"
    }
  ],
  "page": 1,
  "per_page": 50,
  "total": 137,
  "total_pages": 3
}

Render qrString

Encode qrString with any QR library and show the result with the payment amount and expiry. On desktop it is the primary path; on mobile it remains the fallback if the banking app cannot open.

Offer the ABA Mobile deeplink when present

deeplink.scheme opens ABA Mobile on iOS.deeplink.android is an intent URL that can fall through to the Play Store. The iOS scheme silently does nothing when the app is absent.

if (payment.deeplink) {
  const isAndroid = /android/i.test(navigator.userAgent);
  const href = isAndroid
    ? payment.deeplink.android
    : payment.deeplink.scheme;
}

deeplink is null whenever qrString is null, and it is always null for Bakong payments. Guard it before choosing a platform URL.

Hosted checkout uses two clocks

The public payment routes return pollUntil andexpireAt. Count down to pollUntil. On ABA,POST /public/payment/:id/retry can reopen status checks while the QR remains payable. On Bakong both clocks are the same, so retry can re-check status but cannot extend the dead QR.

curl -X POST https://api.bongluy.com/payment/status \
  -H 'authorization: Bearer sk_live_...' \
  -H 'content-type: application/json' \
  -d '{"merchantStoreId":"branch-2","tranId":"INV-1042"}'

{
  "paymentId": "8435481a-48a8-4bb2-91d2-bcd1e604fb17",
  "status": "SUCCESS",
  "expireAt": 1786763662418,
  "settledTranId": "1234567890",
  "receipt": "https://...",
  "at": 1786763501992
}

Bound your own wait, not the payment verdict

Poll every two or three seconds until status leavesPENDING or your checkout stops waiting. There is no streaming or long-polling endpoint.

async function waitForPayment({ merchantStoreId, tranId, giveUpAfterMs = 10 * 60_000 }) {
  const deadline = Date.now() + giveUpAfterMs;

  while (Date.now() < deadline) {
    const response = await fetch("https://api.bongluy.com/payment/status", {
      method: "POST",
      headers: {
        authorization: `Bearer ${process.env.BONGLUY_API_KEY}`,
        "content-type": "application/json",
      },
      body: JSON.stringify({ merchantStoreId, tranId }),
    });
    const { status } = await response.json();

    if (status !== "PENDING") return status;
    await new Promise((resolve) => setTimeout(resolve, 2500));
  }

  // Still undecided, not unpaid. Reconcile later.
  return "PENDING";
}

At 2.5-second intervals, one three-minute polling session consumes about 72 calls. Roughly eight concurrent checkouts can saturate a 600-request-per-minute key. Poll once per payment, not from every open browser tab.

curl -X POST https://api.bongluy.com/payment/detail \
  -H 'authorization: Bearer sk_live_...' \
  -H 'content-type: application/json' \
  -d '{"merchantStoreId":"branch-2","tranId":"INV-1042"}'

A store that is absent or belongs to another account returns404 "unknown store". A payment that is absent from a store you own returns404 "unknown payment". Foreign resources are deliberately indistinguishable from missing ones.

{
  "statusCode": 400,
  "message": [
    "amount must be a positive decimal",
    "storeId must be a UUID"
  ],
  "error": "Bad Request"
}

Either/or identifier pairs can produce several messages for one omission. If neither store identifier is present, validation may complain about both storeId andmerchantStoreId; supplying either resolves the group.

PayWay failures from POST /payment currently appear as 500, not 502 or 503. Retry with the same tranId so a request that actually succeeded upstream cannot create a duplicate payment.

Rate limits

Authenticated API

600 requests per minute, per API key. The 429 response has no Retry-After header; back off for the rest of the minute.

Store writes

20 per minute, per account. Creating and updating stores is setup work, not per-sale work.

Checkout page, per payment

20 requests per second. This governs the hosted checkout a payer has open, not your server's polling.

Checkout page, overall

200 requests per second across all payments.

Better Auth key-management endpoints use their own envelope,{ "code": "...", "message": "..." }. Store and payment routes use the standard status-code shape above.

Turn on deliveries per store

Set webhookUrl and webhookSecret when creating a store or under changes onPOST /stores/update. Mint the secret yourself withopenssl rand -hex 32 and keep it like a password. It is write-only: losing it means replacing it.

curl -X POST https://api.bongluy.com/stores/update \
  -H 'authorization: Bearer sk_live_...' \
  -H 'content-type: application/json' \
  -d '{"merchantStoreId":"branch-2","changes":{"webhookUrl":"https://yourshop.com/hooks/bongluy","webhookSecret":"whsec_..."}}'

The payload is deliberately small

A PENDING payment produces no webhook. Exactly one delivery is queued when either rail reachesSUCCESS or EXPIRED; retries can redeliver that same body. Optional fields are absent rather than null.

{
  "paymentId": "8435481a-48a8-4bb2-91d2-bcd1e604fb17",
  "tranId": "INV-1042",
  "status": "SUCCESS",
  "settledTranId": "aba-tran-1",
  "receipt": "https://...",
  "at": 1786763501992
}

Verify the raw body before parsing

X-Signature is sha256= followed by the hex HMAC-SHA256 of the raw request bytes, keyed by the store's secret. Do not hash re-serialized JSON. In Express, mountexpress.raw on this route before any JSON parser and compare equal-length buffers with timingSafeEqual.

Secret rotation applies to the next attempt, including a retry already in flight. There is no overlap where both secrets work, so rotate during quiet traffic when possible.

Respond first, then fulfil once

Return any 2xx within 10 seconds. Every other status, connection failure, or timeout is retried 10 times with exponential backoff from roughly 2 seconds through 512 seconds, spanning about 17 minutes. After that, the delivery is abandoned without a delivery log or manual replay.

Acknowledge

Return 2xx before slow fulfilment work.

Deduplicate

Make repeated arrivals a no-op keyed by paymentId or a per-store unique tranId.

Reconcile

Use POST /payment/status or POST /payment/detail for an expected result that never arrives.

Coordinate

If polling wins the race, the later webhook must use the same idempotency key and do no work twice.

Exercise both terminal paths

There is no inspector, test-fire action, or replay. Point the store URL at a local tunnel such as cloudflared orngrok, then take a small Bakong payment. Its short QR lifetime makes both SUCCESS andEXPIRED practical to test.