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

GET/api/v1/order-status?ref_id=R-12345

Request Headers

Headers

ParameterTypeRequiredDescription
X-Api-KeyStringYesYour API key. See Authentication.

Query Parameters

Query Params

ParameterTypeRequiredDescription
ref_idStringYesYour unique transaction reference ID (max 100 characters).

Response (Success)

200OK
json
{
"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)

404Not Found
json
{
"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

ParameterTypeRequiredDescription
instant / directKAYBS-XXXXXXXXXXNoA 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.
voucherKAYBS-XXXXXXXXXX/[ALG-REF/]CODE[/PART2]NoThe 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.

200Voucher Example
json
{
"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.

200OK
json
{
"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

ParameterRequiredDescription
serial_numberNoOnly returned when status is "success". Null for all other statuses. Format depends on product type — see Serial Number Format above.
completed_atNoOnly set for terminal statuses (success, failed, refunded). Null while processing.
zone_idNoNull if the game does not require a Zone ID.
failure_codeNoStable machine code. Null unless status is "failed" or "refunded". Also null for orders that failed before this field existed.
failure_reasonNoHuman-readable cause, e.g. "Region Lock". Display it; do not parse it. Never names our upstream supplier.
refunded_amountNoCoins 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

  1. Every 15–30 seconds, call GET /api/v1/orders?status=processing&limit=100.
  2. Reconcile each ref_id you are tracking against that list.
  3. A ref_id you are tracking that is no longer in the list has reached a terminal state — fetch it once with order-status, or read it from ?status=success / ?status=failed.
  4. 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" | ...
PreviousCreate OrderNextOrder History