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.
X-TimestampStringYesCurrent Unix timestamp in ms.
X-SignatureStringYesHMAC-SHA256 of JSON body + timestamp.

Request Body

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

Body Parameters

ParameterTypeRequiredDescription
ref_idStringYesYour unique reference ID (max 64 chars). Used for idempotency.
product_codeStringYesAlgan product code from GET /products (max 128 chars).
targetStringYesGame 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.
zoneStringNoGame 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".
priceNumber | StringNoOptional 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.
testBoolean | StringNoOptional. 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 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 (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 as target
  • the field with role: "server" → send its value as zone
  • two or more role: "server" fields (a region and a server, e.g. Once Human) → join their values into the single zone string with a pipe |, in the form’s field order (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

200OK
json
{
"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_id is 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 AG number.
  • Treat order_id as opaque text of up to 36 characters. Do not validate it as a UUID or store it in a UUID-typed column. A VARCHAR(36) or TEXT column holds both shapes.
  • Quote it to our support as is. We find an order by its AG number or its UUID.
  • Try it on the sandbox first. dev.algan.id returns 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.

200Test order accepted
json
{
"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": true as the last key. order_id is a fresh identifier that is never stored: GET /order-status for this ref_id answers 404 as for an unknown order.
  • If a callback URL is set, one callback follows, signed exactly like a real one, with "test": true after every other key. "test": true sends status: "success" with a serial that starts with TEST-; "test": "failed" sends status: "failed", message: "Order failed", failure_code: "TEST_FAILURE" and refunded_amount equal 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. Use ref_id values you will never use for a real order, for example a TEST- 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:

400Refused (no order created)
json
{
"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

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.
ORDER_FAILED_SUPPLIER_GATE503NoRefused 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_LIMIT400NoRefused before charge: the account already used its allowance for this limit-gated product. No order created; ref_id reusable.
REGION_LOCK400NoRefused before charge: the account's verified region cannot receive this product. No order created; ref_id reusable.
INVALID_ID400NoRefused 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.

PreviousProductsNextOrder Status