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. |
X-Timestamp | String | Yes | Current Unix timestamp in ms. |
X-Signature | String | Yes | HMAC-SHA256 of JSON body + timestamp. |
Request Body
{
"ref_id": "R-12345",
"product_code": "ALGAN-MLBB-86",
"target": "12345678",
"zone": "1234",
"price": 25000
}Body Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
ref_id | String | Yes | Your unique reference ID (max 64 chars). Used for idempotency. |
product_code | String | Yes | Algan product code from GET /products (max 128 chars). |
target | String | Yes | Game User ID, phone number, or (for "via link" games) the https:// payment link. Max 1024 bytes UTF-8 (was 128 characters; every value that fitted before still fits). A value starting with http: or https: must be a valid https:// link; see "Payment-link targets" below. |
zone | String | No | Game Zone/Server ID if required (max 64 chars). For games with a region AND a server, join them with a pipe: "Europe|Manibus(Novice)-00558". |
price | Number | String | No | Optional safety check. Accepts a number (25000) or its numeric-string form ("25000"). 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 places a TEST order that simulates success, "failed" one that simulates a failure. Nothing is stored or charged; see "Test Orders" below. Any other value is a validation error. Omit it for a real order. |
price is optional (recommended for safety)
You do not have to send price. It is an optional confirmation token, not an authority; Algan always charges 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 (25000) or a numeric string ("25000"); 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).
Changelog, 2026-10-31. Prices set by a margin no longer round up one extra rupiah on some values (a float rounding fix): for example 100,000 at 12% is now 112,000, not 112,001. A few prices on GET /products are Rp 1 lower. If you send price from a list cached before the change, that one order answers PRICE_NOT_MATCH; re-read GET /products, as after any price change.
Signature for POST
For POST requests, the HMAC message is JSON.stringify(body) + timestamp. Make sure you sign the exact JSON string you send in the body.
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 - two or more
role: "server"fields (a region and a server, e.g. Once Human) → join their values into the singlezonestring with a pipe|, in the form’s fieldorder(region first). See the multi-part callout below.
The order body accepts exactly those two routing fields (plus ref_id, product_code, price). 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 target is required (string), and because target is part of the signed body, a malformed body also surfaces as INVALID_SIGNATURE. Only ref_id, product_code, target, zone, and price 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. |
| Identifier + region + server (Once Human, etc.) | userId → 158149791, regionId (select) → Europe, serverId → Manibus(Novice)-00558 |
target: "158149791", zone: "Europe|Manibus(Novice)-00558". Join region and server into zone with a pipe |, region first. |
| 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.
Games with a region AND a server (multi-part zone)
A few games (Once Human is the current example) collect two server-type values, a region and a server name, so their form returns two fields with role: "server". The order body still has a single zone slot, so join the two values into zone with a pipe |, in the form’s field order (region first): zone: "Europe|Manibus(Novice)-00558". Send the region field’s option value (not its label). zone accepts up to 64 characters, which covers every current combination.
Payment-link targets (via-link games)
Some products (for example Ragnarok Origin Classic and RF Online Next “via link”) have no account ID: your customer generates a payment link at the publisher’s checkout and that link is the target. Send it verbatim as target (up to 1024 bytes UTF-8, typically 100 to 600 characters). Each link is single-use, so never reuse one from an earlier order.
Changelog, 2026-10-03. target grew from 128 characters to 1024 bytes (additive). One narrowing came with it, and it only affects values that look like a link, which no game account ID does: a target or zone that starts with http: or https: must be a valid https:// link with no spaces, quotes, <, >, backticks, backslashes or control characters (http:// is refused). It answers 400 VALIDATION_ERROR before any balance is debited. Every value that does not start with http: or https: is accepted exactly as before. zone keeps its 64-character limit.
Response
{
"success": true,
"data": {
"order_id": "AG2026100648291057",
"ref_id": "R-12345",
"product_name": "Mobile Legends 86 Diamonds",
"price": 25000,
"status": "processing",
"message": "Order received and is being processed",
"quantity": 1,
"units": [],
"refunded_amount": null
}
}quantity, units, refunded_amount: new, additive
Three keys were added after every existing one. For an ordinary product they are always
quantity: 1, units: [] and refunded_amount: null. For a combo product (one code that
delivers several items) quantity is the item count and units already lists every item at
placement, each with status: "pending", serial_number: null and refund_amount: null.
Follow each item on Order Status; the
callback fires once, when the whole order is done. A combo is charged once, at its listed price.
order_id: short order numbers (changelog, 2026-10)
New orders get a short order number as their order_id: AG, then the order date
(YYYYMMDD, Asia/Jakarta), then 8 digits, for example AG2026100648291057 (18 characters).
It rolls out in 2026-10, so you will see both shapes during the switch.
- Same field, same type.
order_idis still a string in every response. Nothing was renamed, retyped or removed. - An order never changes its id. Every order placed before the switch keeps its UUID
forever, on every read; only orders placed after it get the
AGnumber. - Treat
order_idas opaque text of up to 36 characters. Do not validate it as a UUID or store it in a UUID-typed column. AVARCHAR(36)orTEXTcolumn holds both shapes. - Quote it to our support as is. We find an order by its
AGnumber or its UUID. - Try it on the sandbox first.
dev.algan.idreturns the new format already.
ref_id stays the only key we deduplicate on, and GET /order-status still looks orders up
by ref_id. Keep sending and matching your own ref_id exactly as you do now.
order_code: removed (changelog, 2026-10)
The order_code field (AGN- + 12 characters) is no longer returned, on any endpoint or in any
callback. It was a short alias for the old 36-character order_id; now that new orders get a
short order_id of their own, it is redundant. If you stored order_code for older orders,
quote it to our support as before: we still find an order by it. Use order_id from now on.
Which id should you store?
Store order_id as text. It is short for every new order, it fits a VARCHAR(36) column in
both shapes, and it is the number our support team searches by. Keep sending your own ref_id
and matching callbacks on ref_id, exactly as you do now.
Example cURL
API_KEY="algan_live_..."
API_SECRET="sk_live_..."
TIMESTAMP=$(python3 -c "import time; print(int(time.time() * 1000))")
BODY='{"ref_id":"R-12345","product_code":"ALGAN-MLBB-86","target":"12345678","zone":"1234","price":25000}'
SIGNATURE=$(echo -n "${BODY}${TIMESTAMP}" | \
openssl dgst -sha256 -hmac "${API_SECRET}" | awk '{print $2}')
curl -s -X POST https://algan.id/api/v1/order \
-H "Content-Type: application/json" \
-H "X-Api-Key: ${API_KEY}" \
-H "X-Timestamp: ${TIMESTAMP}" \
-H "X-Signature: ${SIGNATURE}" \
-d "${BODY}"
Example (Node.js)
const crypto = require('crypto');
const API_KEY = 'algan_live_...';
const API_SECRET = 'sk_live_...';
const timestamp = Date.now().toString();
const body = {
ref_id: 'R-12345',
product_code: 'ALGAN-MLBB-86',
target: '12345678',
zone: '1234',
price: 25000,
};
const payloadString = JSON.stringify(body);
const signature = crypto.createHmac('sha256', API_SECRET)
.update(payloadString + timestamp).digest('hex');
const res = await fetch('https://algan.id/api/v1/order', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-Api-Key': API_KEY,
'X-Timestamp': timestamp,
'X-Signature': signature,
},
body: payloadString,
});
const data = await res.json();
Test Orders
Send "test": true (simulate success) or "test": "failed" (simulate a failure) to check your integration on the live API without spending balance. A test order goes through everything a real one does up to the charge: the same headers and HMAC signature, the IP whitelist, the field validation, and the same product, catalog, price (price token included) and availability checks, with the same refusal codes. Then it stops: no order is stored, no balance is read or deducted, nothing is sent to a supplier.
{
"success": true,
"data": {
"order_id": "3f6c2a8e-0b1d-4e7a-9c55-8d2f7a1b4e90",
"ref_id": "TEST-0001",
"product_name": "Mobile Legends 86 Diamonds",
"price": 25000,
"status": "processing",
"message": "Test order accepted. Nothing was stored and no balance was deducted.",
"quantity": 1,
"units": [],
"refunded_amount": null,
"test": true
}
}- The response is the real success shape plus
"test": trueas the last key.order_idis a fresh identifier that is never stored:GET /order-statusfor thisref_idanswers404as for an unknown order. - If a callback URL is set, one callback follows, signed exactly like a real one, with
"test": trueafter every other key."test": truesendsstatus: "success"with a serial that starts withTEST-;"test": "failed"sendsstatus: "failed",message: "Order failed",failure_code: "TEST_FAILURE"andrefunded_amountequal to the price. It is sent once and never retried. A combo product answers and calls back with its items, as a real combo does. - A test order counts against your tier’s per-minute rate limit (a real order does not, because your balance bounds it). The ID checker refusals (
PURCHASE_LIMIT,REGION_LOCK,INVALID_ID) are not run for a test order. - A test order does not reserve its
ref_id. Useref_idvalues you will never use for a real order, for example aTEST-prefix.
Changelog, 2026-10-31: test orders
The optional test field is new. Until now the API refused any body carrying test with 400 VALIDATION_ERROR (“Unknown field: test”), so no existing integration can have placed a real order with it. Requests without test behave exactly as before. The sandbox at dev.algan.id is unchanged and still refuses the field.
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.
Pre-charge Checker Refusals
For games with the ID checker enabled, the order is validated before any charge. When the checker has a definitive answer that the order cannot be delivered, the request is refused instantly instead of being accepted and failing after dispatch:
{
"success": false,
"error": "PURCHASE_LIMIT",
"message": "The account has already used its purchase allowance for this product.",
"request_id": "a1b2c3d4-e5f6-..."
}Three refusal codes exist: PURCHASE_LIMIT (a limit-gated product — first top-up tier or
weekly/monthly pass — the account has already consumed), REGION_LOCK (the account’s
verified region cannot receive this product), and INVALID_ID (the checker explicitly
confirmed the account does not exist).
A refusal creates NO order
Nothing is inserted, no balance moves, no callback fires, and GET /order-status for that
ref_id returns not-found. A refusal is not a failed order — it is the failure you would
have received after dispatch, delivered before payment instead.
A refused ref_id is NOT consumed — you may reuse it
ref_id idempotency is claimed only when an order row is created. Because a refusal
creates no order, the same ref_id stays free: retrying the identical request is refused
again (deterministically, at no cost), and retrying the SAME ref_id with a corrected
target/product_code proceeds normally. This is different from a failed order,
which does exist — its ref_id is consumed and a reuse returns 409 DUPLICATE_REF_ID.
Do not blind-retry a refusal
All three refusal codes describe a fact about the target account, not a transient
condition. Retrying unchanged just repeats the refusal. Surface the error code to your
flow (or call POST /validation first — it exposes the same verdicts before
you order). If the checker cannot reach a definitive answer, your order proceeds
normally — an outage on our side never blocks you.
Weekly Diamond Pass: limit check adds no wait (changelog, 2026-10)
A Mobile Legends account can hold a limited number of Weekly Diamond Passes. When a WDP
product is limit-gated, its order is judged only from a measurement we already hold for that
account from the last 3 minutes: your own POST /validation call with
“checks”: [“wdp_limit”], our checker, or an earlier order for the same account.
If that measurement says the account is at its limit, the order is refused with
PURCHASE_LIMIT before any charge. Without a fresh measurement the order proceeds
exactly as before, so this check never slows your order down. To be refused before charge
instead of failing after dispatch, call POST /validation with
wdp_limit right before you order.
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. |
ORDER_FAILED_SUPPLIER_GATE | 503 | No | Refused before charge: no supply route can deliver this product right now (it reads "inactive" on GET /products). No order created, no balance moved. Retry later with the SAME ref_id. |
PURCHASE_LIMIT | 400 | No | Refused before charge: the account already used its allowance for this limit-gated product. No order created; ref_id reusable. |
REGION_LOCK | 400 | No | Refused before charge: the account's verified region cannot receive this product. No order created; ref_id reusable. |
INVALID_ID | 400 | No | Refused before charge: the checker confirmed the account does not exist. No order created; ref_id reusable. |
Changelog, 2026-10-04: more refusals happen before the charge
A product with no live supply route (no supplier linked, every linked supplier switched
off, or an empty voucher stock) is now refused before any balance is debited, with the
existing 503 ORDER_FAILED_SUPPLIER_GATE. It used to be accepted, debited, failed and
refunded, with a failed callback. Nothing is debited now and no callback fires, because no
order exists. The same product already reads "inactive" on GET /products.
The availability check runs before the optional price check. So a product that is
unavailable AND sent with a stale price answers 503 ORDER_FAILED_SUPPLIER_GATE (it used
to answer 409 PRICE_NOT_MATCH). Both codes are pre-charge and both were already documented
in Error Codes.