Response format

The envelope

Every response, on success or failure, is a JSON object with three fields:

JSON

{ "code": "SUCCESS", "message": "Order created", "data": { "orderId": "acme-1042" } }

Field	Meaning
code	A string. SUCCESS when the call worked; otherwise one of the error codes.
message	Human-readable English. Show it or log it.
data	The payload on success. null on error.

Branch on code

code is the stable part of the contract. message is prose written for a human and may be reworded — branch on the code, log the message. The HTTP status follows from code but is less specific: several different errors share HTTP 400.

JavaScript

const {code, message, data} = await res.json();

switch (code) {
  case 'SUCCESS':
    return data;
  case 'PARTNER_INSUFFICIENT_BALANCE':
    return topUpFundAndRetry();
  case 'DUPLICATE_TRANSACTION_ID':
    return existingOrder(orderId);   // already created — not an error for you
  default:
    throw new Error(`${code}: ${message}`);
}

HTTP status semantics

Status	Meaning
200 / 201	Success — writes and submissions return 201. Treat any 2xx as success and read code.
400	The request was invalid, or a business rule rejected it. This is the default for business errors.
401	Missing or invalid identity.
402	Your fund balance is insufficient.
403	Your partner account is locked, or the caller IP is not allowlisted.
404	The requested resource — order, partner, KYC profile — was not found.
409	Duplicate orderId.
500	Unexpected server error — or an order was created but its payout failed.
503	The service is disabled, under maintenance, or temporarily unavailable.

Amounts

• Fiat amounts are decimals in the currency's major unit — dollars, not cents; đồng, not hundredths of a đồng — each rounded to that currency's standard precision.
• A fiatAmount you send has a maximum number of decimal places per currency; see Amount precision.
• Crypto amounts are decimals in the token's native precision.

Timestamps

• Order createdAt and expiresAt are ISO-8601 in UTC: 2026-07-06T05:00:00.000Z.
• The access token's expiresAt is a number — a Unix timestamp in seconds, the one place a timestamp is not ISO-8601.