Create Order

Place a new top-up order.

Submit a new top-up order. Orders are processed asynchronously. This endpoint guarantees sub-50ms ingestion latency and atomic idempotency.

Endpoint

POST/api/v1/order

Request Headers

Headers

ParameterTypeRequiredDescription
Content-TypeStringYesMust be application/json.
X-Api-KeyStringYesYour API key. See Authentication.

Request Body

200Request Body
json
{
"ref_id": "R-12345",
"product_code": "MLBB-86",
"target": "12345678",
"zone": "1234",
"price": 725
}

Body Parameters

ParameterTypeRequiredDescription
ref_idStringYesYour unique reference ID (max 64 chars). Used for idempotency.
product_codeStringYesProduct code from GET /products (max 128 chars).
targetStringYesGame User ID, phone number, or — for a "via link" game — the publisher payment link (max 1024 bytes). A link must be https:// with no spaces or quotes; any other scheme is rejected.
zoneStringNoGame Zone/Server ID if required (max 32 chars).
priceNumber | StringNoOptional safety check. Accepts a number (725) or its numeric-string form ("725"). If provided, must equal the exact price from GET /products or the order is rejected (PRICE_NOT_MATCH) — this protects you from stale prices. To skip the check, omit the field entirely (charged at the current price). Sending it as null or "" is a validation error, not an omission.
testBoolean | StringNoOptional. true simulates a successful order, "failed" a failed one: the order is validated and priced but nothing is stored, no balance is checked or deducted, and no supplier is called. Any other value is a 400 VALIDATION_ERROR. Omit it for a real order. See Test orders below.

price is optional (recommended for safety)

You do not have to send price. It is an optional confirmation token, not an authority — we always charge the current server price for your tier, whether or not you send it.

  • Send price (recommended): the order is rejected with PRICE_NOT_MATCH if your value doesn’t match the current price. This guarantees you never get charged more than the price you showed your customer. Pair it with GET /products to fetch the live price first.
  • Omit price: the order proceeds at the current price with no confirmation step. Simpler to integrate, but if the price changed since you last synced, you absorb the difference.

Existing integrations that send price are unaffected — behaviour is identical. The response always echoes the actual price charged so you can reconcile.

Format: price may be sent as a JSON number (725) or a numeric string ("725") — many platforms serialize numbers as strings, and both are accepted. To waive the check, leave the field out of the body entirely; sending null or "" is rejected as a validation error (it is not treated as omission).

Mapping Form Fields to target & zone

The form array returned by GET /categories tells you what to collect from your customer and how to validate it. Each field carries a role that maps it to this endpoint — no guessing by field name:

  • the field with role: "account_id" → send its value as target
  • the field with role: "server" → send its value as zone

The order body accepts exactly those two routing fields (plus ref_id, product_code, price and the optional test). A server field may be type: "select" — send the chosen option’s value.

target is always required

Whatever single account identifier the game needs — uid, user_id, player_id, userId, playerId, riotId, etc. — collapse it into the target string. If you omit target you will get 400 VALIDATION_ERROR (“target is required (non-blank string)”). Only ref_id, product_code, target, zone, price and test are accepted — any other field is rejected as Unknown field.

Game shape Example form fields How to send it
Single identifier (Free Fire, Honor of Kings, etc.) user_id → 123456789 target: "123456789" — no zone.
Identifier + server/zone (Mobile Legends, etc.) user_id → 12345678, zone_id → 1234 target: "12345678", zone: "1234". The server/zone value is the only thing that goes in zone.
Composite identifier (Valorant Riot ID, etc.) riotId + tagline, placeholder VALOUSERNAME#1234 Join into one string → target: "VALOUSERNAME#1234". Do not split the tagline into zone.
Voucher (type: "voucher", e.g. STEAM VOUCHER PHP) none from us — build your own form The code is delivered back to you, so target is just a delivery/reference label. Pass any value you control, e.g. your customer’s email or your own reseller email as a placeholder → target: "[email protected]". No zone.

When is zone required?

Send zone only when the game’s form includes a field with role: "server" (Mobile Legends, Genshin, etc.) — that field’s value is the zone. If no field has role: "server", omit zone entirely; sending it for a single-identifier or voucher product has no effect.

Response

200OK
json
{
"success": true,
"data": {
  "order_id": "d7e8f9a0-b1c2-3d4e-5f6a-7b8c9d0e1f2a",
  "ref_id": "R-12345",
  "product_name": "Mobile Legends 86 Diamonds",
  "price": 725,
  "status": "processing",
  "message": "Order received and is being processed",
  "quantity": 1,
  "units": []
}
}

A 200 means ACCEPTED, not DELIVERED

This response is returned as soon as the order is booked and your coins are deducted — before we contact the upstream provider. status is therefore always processing on a successful call; it is never success here, and a 200 is not a delivery confirmation.

There are exactly two ways to learn the final outcome:

  1. Register a callback URL (recommended) — we POST the terminal result to you. See Callbacks.
  2. Poll GET /api/v1/order-status?ref_id=… — poll every 5–10 seconds, and stop as soon as status is success, failed, or refunded. Most orders settle within seconds; a few supplier routes take longer.

If an order fails, order-status tells you why via failure_code and failure_reason, and confirms the coin refund via refunded_amount.

Retrying safely

ref_id is your idempotency key. Re-sending the same ref_id returns DUPLICATE_REF_ID (409) and never places a second order — so a network timeout on your side is always safe to retry with the identical body.

A 503 ORDER_FAILED_SUPPLIER_GATE means no coins were deducted, so that one is safe to retry on the same ref_id. To genuinely re-attempt an order that already reached a terminal failed, use a new ref_id.

Example cURL

# KAYBS_API_KEY comes from your environment / secret store.
curl -s -X POST https://[kaybs-domain]/api/v1/order \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${KAYBS_API_KEY}" \
  -d '{"ref_id":"R-12345","product_code":"MLBB-86","target":"12345678","zone":"1234","price":725}'

Example (Node.js)

// Node 18+ (ESM). fetch sets Content-Length for a string body.
const res = await fetch('https://[kaybs-domain]/api/v1/order', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': process.env.KAYBS_API_KEY,
  },
  body: JSON.stringify({
    ref_id: 'R-12345',
    product_code: 'MLBB-86',
    target: '12345678',
    zone: '1234',
    price: 725,
  }),
});
const data = await res.json();

Test orders

Add "test": true to rehearse a successful order, or "test": "failed" to rehearse a failed one, without spending anything. A test order goes through everything a real order does up to the charge — authentication, IP whitelist, field validation, product lookup and the price check (a wrong price still returns PRICE_NOT_MATCH) — and then stops:

  • Nothing is stored and no balance is checked or deducted, so INSUFFICIENT_BALANCE cannot occur.
  • No supplier is called.
  • It counts against your tier rate limit, so it can return 429 RATE_LIMIT_EXCEEDED (real orders are exempt).
  • Any value other than true or "failed" — including false, null and "true" — is a 400 VALIDATION_ERROR, so a typo can never place a real, charged order.
200Request Body (test)
json
{
"ref_id": "TEST-0001",
"product_code": "MLBB-86",
"target": "12345678",
"zone": "1234",
"price": 725,
"test": true
}
200OK (test)
json
{
"success": true,
"data": {
  "order_id": "3f1c9a52-7d0e-4b8a-9c61-2e5f80a4d7b3",
  "ref_id": "TEST-0001",
  "product_name": "Mobile Legends 86 Diamonds",
  "price": 725,
  "status": "processing",
  "message": "Test order accepted — nothing stored, no balance deducted",
  "quantity": 1,
  "units": [],
  "test": true
}
}

If you have a Callback URL set, we send one callback (no retries) shortly after, signed exactly like a real one and marked "test": true:

  • "test": true → "status": "success" with a fake "serial_number" such as "TEST-4K9QZ2M7XA".
  • "test": "failed" → "status": "failed", "serial_number": null, "failure_code": "TEST_FAILURE", "failure_reason": "Simulated failure (test order)".

See Test callbacks for the full payload.

A test order leaves no trace

Because nothing is stored, GET /api/v1/order-status for a test ref_id returns 404 PRODUCT_NOT_FOUND (“Order not found”), test orders never appear in GET /api/v1/orders, and the order_id in the response cannot be looked up. For the same reason a test order does not reserve its ref_id: you can reuse it, and it does not collide with a real order.

# Rehearse a failure
curl -s -X POST https://[kaybs-domain]/api/v1/order \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${KAYBS_API_KEY}" \
  -d '{"ref_id":"TEST-0002","product_code":"MLBB-86","target":"12345678","zone":"1234","test":"failed"}'

Recommended path to go live

  1. GET /api/v1/balance — proves your key and IP whitelist.
  2. POST /api/v1/order with "test": true — proves ordering and your callback signature check.
  3. POST /api/v1/order with "test": "failed" — proves your failure handling.
  4. Go live: send the same request without test.

Idempotency

Duplicate Protection

If you send the exact same ref_id twice, the second request will be rejected with a 409 DUPLICATE_REF_ID error. No balance will be deducted twice. This is your safeguard against network retries.

Error Responses

Possible Errors

ParameterTypeRequiredDescription
DUPLICATE_REF_ID409NoAn order with this ref_id already exists.
INSUFFICIENT_BALANCE402NoNot enough balance.
PRODUCT_NOT_FOUND404NoInvalid or inactive product_code.
PRICE_NOT_MATCH409NoPrice changed since you fetched products.
VALIDATION_ERROR400NoMissing/invalid fields, an unknown field, or a test value other than true / "failed".
ORDER_FAILED_SUPPLIER_GATE503NoNo supplier could accept the order. Nothing was deducted; safe to retry with the same ref_id.
RATE_LIMIT_EXCEEDED429NoTest orders only: too many requests for your tier. Real orders are not rate-limited.
PreviousProductsNextOrder Status