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
Request Headers
Headers
| Parameter | Type | Required | Description |
|---|---|---|---|
Content-Type | String | Yes | Must be application/json. |
X-Api-Key | String | Yes | Your API key. See Authentication. |
Request Body
{
"ref_id": "R-12345",
"product_code": "MLBB-86",
"target": "12345678",
"zone": "1234",
"price": 725
}Body Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
ref_id | String | Yes | Your unique reference ID (max 64 chars). Used for idempotency. |
product_code | String | Yes | Product code from GET /products (max 128 chars). |
target | String | Yes | Game 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. |
zone | String | No | Game Zone/Server ID if required (max 32 chars). |
price | Number | String | No | Optional 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. |
test | Boolean | String | No | Optional. 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 withPRICE_NOT_MATCHif your value doesn’t match the current price. This guarantees you never get charged more than the price you showed your customer. Pair it withGET /productsto 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 astarget - the field with
role: "server"→ send its value aszone
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
{
"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:
- Register a callback URL (recommended) — we POST the terminal result to you. See Callbacks.
- Poll
GET /api/v1/order-status?ref_id=…— poll every 5–10 seconds, and stop as soon asstatusissuccess,failed, orrefunded. 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_BALANCEcannot 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
trueor"failed"— includingfalse,nulland"true"— is a400 VALIDATION_ERROR, so a typo can never place a real, charged order.
{
"ref_id": "TEST-0001",
"product_code": "MLBB-86",
"target": "12345678",
"zone": "1234",
"price": 725,
"test": true
}{
"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
GET /api/v1/balance— proves your key and IP whitelist.POST /api/v1/orderwith"test": true— proves ordering and your callback signature check.POST /api/v1/orderwith"test": "failed"— proves your failure handling.- 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
| Parameter | Type | Required | Description |
|---|---|---|---|
DUPLICATE_REF_ID | 409 | No | An order with this ref_id already exists. |
INSUFFICIENT_BALANCE | 402 | No | Not enough balance. |
PRODUCT_NOT_FOUND | 404 | No | Invalid or inactive product_code. |
PRICE_NOT_MATCH | 409 | No | Price changed since you fetched products. |
VALIDATION_ERROR | 400 | No | Missing/invalid fields, an unknown field, or a test value other than true / "failed". |
ORDER_FAILED_SUPPLIER_GATE | 503 | No | No supplier could accept the order. Nothing was deducted; safe to retry with the same ref_id. |
RATE_LIMIT_EXCEEDED | 429 | No | Test orders only: too many requests for your tier. Real orders are not rate-limited. |