POST/v1/orders

Create Order

Create a payment order from your CRM. On success the API returns cid and checkout_url. The same order_id for a workspace returns the existing order (idempotent create).

Request body

order_idstringrequired

Your internal order ID. Unique per workspace. Reuse returns the stored order and checkout URL.

order_amountstringrequired

Fiat amount as a decimal string, greater than 0. Alias: amount.

order_currencystringoptional

Default USD. Other values are stored uppercased; quotes are USD-based.

payer_idstringoptional

Your user id. Shown on Payments and grouped on Customers. Recommended.

payer_emailstringoptional

Optional. Stored on the order; not used for auth.

payer_namestringoptional

Optional display name on the dashboard list.

valid_timeintegeroptional

Minutes until expiry, 10–1440. If omitted, Settings → Checkout timeout is used.

expires_inintegeroptional

Alias for valid_time. Ignored when valid_time is set.

success_urlstringoptional

Optional return URL after payment. Must start with http:// or https://. Overrides the checkout default.

cancel_urlstringoptional

Optional return URL after cancel. Same http(s) rule. This is not the webhook URL.

callback_urlstringoptional

Per-order webhook URL. Defaults to Settings → Notifications.

remarkstringoptional

Internal note. Not shown in the popup.

languagestringoptional

Checkout language. Default from Settings → Checkout (usually en).

Headers

Authorizationheaderrequired

Bearer pk_… from dashboard Settings → Developer.

Content-Typeheaderoptional

application/json on POST bodies. Not required on GET.

Response data

Wrapped as { code, msg, data }. HTTP 201 on a new order, 200 when order_id already exists. Envelope code is 00000 in both cases.

idstringoptional

Internal row id. Prefer cid for CRM storage; this value is not used on query.

cidstringrequired

Public payment id. Unique per order. Use it in query, webhooks, and support tickets.

tokenstringoptional

Hosted checkout token. Already embedded in checkout_url as /pay/chk_….

order_idstringrequired

Your order id. Unique per workspace. Repeating it on create returns this same order.

payer_idstringoptional

Your user id. Grouped on the dashboard Customers page when present.

payer_emailstringoptional

Optional payer email. Stored only; not required to open checkout.

payer_namestringoptional

Optional payer display name on the payments list.

order_amountstringrequired

Fiat amount as a decimal string (for example 50.00).

order_currencystringrequired

Fiat currency. Send USD. Uppercased on store.

fiat_amountstringoptional

Alias of order_amount for older clients.

fiat_currencystringoptional

Alias of order_currency.

statusstringrequired

pending, awaiting_payment, paid_partial, paid, paid_over, expired, cancelled, failed, refunded.

remarkstringoptional

Free-text note from create. Not shown to the payer.

languagestringoptional

Checkout UI language. Defaults to the workspace setting (usually en).

chain_idstringoptional

Set after the payer selects an asset. Null on a fresh create.

token_idstringoptional

Asset identifier on that network after quote lock.

asset_symbolstringoptional

Quoted ticker, for example USDT. Null before the payer picks an asset.

network_namestringoptional

Quoted network display name, for example Tron.

crypto_amountstringoptional

Quoted crypto amount as a decimal string, or null before lock.

quote_ratestringoptional

Exchange rate used for the quote, or null.

payment_addressstringoptional

Address shown in checkout after quote lock. Do not reuse it for a different order.

expires_atstringoptional

ISO-8601 expiry. Open orders read after this become expired.

expire_timeintegeroptional

Same expiry as Unix milliseconds.

paid_atstringoptional

ISO-8601 paid time when status is paid or paid_over, else null.

checkout_urlstringrequired

Absolute URL for the 400×720 popup. Open it as returned — do not rewrite the host or token.

merchant_display_namestringoptional

Workspace name shown in the popup (Settings → Merchant).

merchant_logo_urlstringoptional

Logo URL shown in the popup, or null.

Errors

Failures still return JSON. Read code, not only the HTTP status. Full table: Errors.

40000HTTP 400optional

Validation: missing order_id, amount ≤ 0, valid_time outside 10–1440, or URL not http(s).

40100HTTP 401optional

Missing or invalid API key, or the workspace is not active.

Example request

http://127.0.0.1:43120/v1/orders

json

{
  "order_id": "ord_123",
  "order_amount": "50.00",
  "order_currency": "USD",
  "payer_id": "user_1001",
  "valid_time": 30,
  "callback_url": "https://crm.example.com/webhooks/bytix"}

Response example

application/json

json

{
  "code": "00000",
  "msg": "ok",
  "data": {
    "id": "clxxxxxxxxxxxxxxxxxxxx",
    "cid": "po17895880118355c739c",
    "token": "chk_...",
    "order_id": "ord_123",
    "payer_id": "user_1001",
    "payer_email": null,
    "payer_name": null,
    "order_amount": "50",
    "order_currency": "USD",
    "fiat_amount": "50",
    "fiat_currency": "USD",
    "status": "pending",
    "remark": null,
    "language": "en",
    "chain_id": null,
    "token_id": null,
    "asset_symbol": null,
    "network_name": null,
    "crypto_amount": null,
    "quote_rate": null,
    "payment_address": null,
    "expires_at": "2026-09-16T21:30:00.000Z",
    "expire_time": 1789589811835,
    "paid_at": null,
    "checkout_url": "http://127.0.0.1:43123/pay/chk_...",
    "merchant_display_name": "Acme",
    "merchant_logo_url": null
  }
}

PreviousOverview Next Query Order