Order Status
Check the current status of a single order by reference ID.
Query the current status of a specific order using your ref_id. Use this as a fallback when your webhook callback was missed or if you did not configure one.
Replaces POST /check-status
This GET endpoint replaces the deprecated POST /api/v1/check-status. No request body needed — just pass ref_id as a query parameter.
Endpoint
Request Headers
Headers
| Parameter | Type | Required | Description |
|---|---|---|---|
X-Api-Key | String | Yes | Your API key. See Authentication. |
Query Parameters
Query Params
| Parameter | Type | Required | Description |
|---|---|---|---|
ref_id | String | Yes | Your unique transaction reference ID (max 100 characters). |
Response (Success)
{
"success": true,
"data": {
"order_id": "d7e8f9a0-b1c2-3d4e-5f6a-7b8c9d0e1f2a",
"ref_id": "R-12345",
"product_code": "MLBB-86",
"product_name": "Mobile Legends 86 Diamonds",
"target_id": "12345678",
"zone_id": "1234",
"price": 725,
"status": "success",
"serial_number": "KAYBS-A7B2C3D4EF",
"created_at": "2026-05-14T10:30:00.000Z",
"completed_at": "2026-05-14T10:30:05.123Z"
}
}Response (Not Found)
{
"success": false,
"error": "PRODUCT_NOT_FOUND",
"message": "Order not found",
"request_id": "a1b2c3d4-e5f6-..."
}Test orders are not found here
A test order stores nothing, so its ref_id returns this same
404 PRODUCT_NOT_FOUND (“Order not found”).
Serial Number Format
The serial_number is always branded with our KAYBS- reference (KAYBS- plus 10 characters). What follows depends on the product type:
serial_number by Type
| Parameter | Type | Required | Description |
|---|---|---|---|
instant / direct | KAYBS-XXXXXXXXXX | No | A branded reference token only (e.g. KAYBS-A7B2C3D4EF). There is no code to redeem — the top-up has already been delivered to the target account. Use it as your proof-of-fulfillment reference. |
voucher | KAYBS-XXXXXXXXXX/[ALG-REF/]CODE[/PART2] | No | The redeemable code follows our reference after a "/". A supplier reference starting with ALG- may sit in between, and some vouchers come in two parts (e.g. PIN and password). Give the customer every segment after our reference and any ALG- reference. |
Parsing voucher codes
Split serial_number on /, drop the first segment (our KAYBS- reference) and a leading
ALG- supplier reference, and give your customer every remaining segment — taking only the
last one hands a two-part voucher’s buyer half a credential. A ready-made snippet is in
Callbacks → Serial Number Format. For instant/direct
products there is no / — the whole value is just a reference token.
{
"success": true,
"data": {
"order_id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
"ref_id": "R-99001",
"product_code": "STEAM-PHP-500",
"product_name": "Steam Voucher PHP 500",
"target_id": "[email protected]",
"zone_id": null,
"price": 520,
"status": "success",
"serial_number": "KAYBS-A7B2C3D4EF/STEAMPH-9XQ2-K7MP-44TZ",
"failure_code": null,
"failure_reason": null,
"refunded_amount": null,
"created_at": "2026-05-14T10:30:00.000Z",
"completed_at": "2026-05-14T10:30:05.123Z"
}
}Response — failed order
When an order fails, failure_code and failure_reason tell you why, and
refunded_amount confirms the coins that were returned. You do not need to contact support
to find out what happened.
{
"success": true,
"data": {
"order_id": "d7e8f9a0-b1c2-3d4e-5f6a-7b8c9d0e1f2a",
"ref_id": "R-12345",
"product_code": "MLBB-86",
"product_name": "Mobile Legends 86 Diamonds",
"target_id": "12345678",
"zone_id": "1234",
"price": 725,
"status": "failed",
"serial_number": null,
"failure_code": "REGION_LOCKED",
"failure_reason": "Region Lock",
"refunded_amount": 725,
"created_at": "2026-05-14T10:30:00.000Z",
"completed_at": "2026-05-14T10:30:05.123Z"
}
}Failure Codes
failure_code is a stable machine-readable value — switch on it in your code. failure_reason
is the human-readable detail and may change wording; show it to your customer, do not parse it.
REGION_LOCKEDThe target account cannot receive this product in its region.TARGET_INVALIDThe publisher rejected the target ID or zone as invalid. Re-check the account details before retrying.PURCHASE_LIMITThe target account already used this product's per-account allowance. Retrying will fail again.PRODUCT_UNAVAILABLEThe product is delisted or out of stock upstream. Re-sync your catalog — it will now report status "inactive".SUPPLIER_MAINTENANCEThe game is under maintenance. Safe to retry later with a NEW ref_id.NO_SUPPLIER_AVAILABLENo route could fulfil this product right now. Safe to retry later with a NEW ref_id.SUPPLIER_REJECTEDRejected for a reason outside the list above. Read failure_reason for the detail.New codes may appear
Treat this list as open-ended. Handle any unrecognised failure_code the same way you handle
SUPPLIER_REJECTED — display failure_reason and do not retry automatically. New codes are
added as we classify new upstream causes, and a new code is never a breaking change.
Important Notes
Field Behavior
| Parameter | Required | Description |
|---|---|---|
serial_number | No | Only returned when status is "success". Null for all other statuses. Format depends on product type — see Serial Number Format above. |
completed_at | No | Only set for terminal statuses (success, failed, refunded). Null while processing. |
zone_id | No | Null if the game does not require a Zone ID. |
failure_code | No | Stable machine code. Null unless status is "failed" or "refunded". Also null for orders that failed before this field existed. |
failure_reason | No | Human-readable cause, e.g. "Region Lock". Display it; do not parse it. Never names our upstream supplier. |
refunded_amount | No | Coins returned to your wallet, or null if nothing was refunded. Can be set on a "success" order too, when a bundle product delivered only part of its units. |
Polling efficiently
If you reconcile by polling rather than callbacks, do not call this endpoint once per open
order. Each call costs one request against your tier’s rate limit, so a Bronze reseller
(30 req/min) with 40 open orders exhausts their entire budget in a single sweep and starts
receiving 429.
Use GET /api/v1/orders?status=processing instead — it returns every
in-flight order in ONE request, with the same failure_code / failure_reason /
refunded_amount fields this endpoint provides.
Recommended polling loop
- Every 15–30 seconds, call
GET /api/v1/orders?status=processing&limit=100. - Reconcile each
ref_idyou are tracking against that list. - A
ref_idyou are tracking that is no longer in the list has reached a terminal state — fetch it once withorder-status, or read it from?status=success/?status=failed. - Reserve this single-order endpoint for spot checks and support lookups.
That is 2–4 requests per minute regardless of how many orders you have open, instead of one per order.
Measuring fulfilment time
created_at is when we accepted the order and deducted your coins. completed_at is when it
reached a terminal state. Fulfilment time is simply the difference:
const seconds = (new Date(o.completed_at) - new Date(o.created_at)) / 1000;
completed_at is exact, and does not move
completed_at is stamped once, at the moment the order becomes terminal, and is never
updated afterwards — callback delivery attempts, retries, and internal bookkeeping do not
disturb it. It is null while the order is still processing.
Orders completed before 2026-07-30 carry an approximate value accurate to within about 30 seconds; orders completed after that are exact.
Status Enum
The status field can return one of the following values:
processingThe order is currently being asynchronously processed by us.successThe order was successfully completed. serial_number is available.failedThe order failed. Read failure_code / failure_reason for the cause. Coins are refunded automatically — refunded_amount confirms the credit.refundedThe order was cancelled and the balance has been refunded manually by an admin.Example cURL
curl -s "https://[kaybs-domain]/api/v1/order-status?ref_id=R-12345" \
-H "X-Api-Key: ${KAYBS_API_KEY}"
Example (Node.js)
// Node 18+ (ESM)
const refId = 'R-12345';
const response = await fetch(
`https://[kaybs-domain]/api/v1/order-status?ref_id=${encodeURIComponent(refId)}`,
{ headers: { 'X-Api-Key': process.env.KAYBS_API_KEY } },
);
const result = await response.json();
console.log(result.data.status); // "success" | "processing" | ...