From PayWay link to settled payment.

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=...",
  "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=..."}'

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":"12.50","tranId":"INV-1042"}'

{
  "id": "8435481a-48a8-4bb2-91d2-bcd1e604fb17",
  "storeId": "76e0cdea-ab74-455d-b46e-3b9e50f679a2",
  "status": "PENDING",
  "amount": "12.50",
  "currency": "USD",
  "paywayLink": "https://link.payway.com.kh/aba?id=...",
  "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": {
    "scheme": "abamobilebank://ababank.com?type=payway&qrcode=...",
    "android": "intent://ababank.com?type=payway&qrcode=...#Intent;package=com.paygo24.ibank;..."
  }
}

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 API currently accepts "0" and "0.00", so enforce your own minimum before calling it.

currency labels the record; it does not instruct PayWay or convert funds. The actual charge follows the store's PayWay link. A mismatched value only mislabels your own data.

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.

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.

Expiry is part of the response

ABA supplies the lifetime; Bongluy falls back to 180 seconds only when ABA omits it. Read expireAt from every payment response instead of hardcoding three minutes. A payment past that timestamp cannot be paid upstream.

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.

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

deeplink is null whenever qrString is null.

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
}

Stop at the deadline

Poll every two or three seconds until status leavesPENDING or the returned expiry time passes. There is no streaming or long-polling endpoint.

async function waitForPayment({ merchantStoreId, tranId, expireAt }) {
  const deadline = new Date(expireAt).getTime();

  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));
  }

  return "EXPIRED";
}

At 2.5-second intervals, one three-minute checkout 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.

Per-store webhooks and a signed payload are planned, but the payload and signature scheme are deliberately undocumented until they ship. Polling remains the supported integration contract.

A server-configured global delivery endpoint may exist in some deployments, but it is not exposed to merchants and is not part of this API contract.