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_idstringrequiredYour internal order ID. Unique per workspace. Reuse returns the stored order and checkout URL.
order_amountstringrequiredFiat amount as a decimal string, greater than 0. Alias: amount.
order_currencystringoptionalDefault USD. Other values are stored uppercased; quotes are USD-based.
payer_idstringoptionalYour user id. Shown on Payments and grouped on Customers. Recommended.
payer_emailstringoptionalOptional. Stored on the order; not used for auth.
payer_namestringoptionalOptional display name on the dashboard list.
valid_timeintegeroptionalMinutes until expiry. Values outside 10–1440 are clamped to that range. If omitted, the Settings → Checkout timeout is used.
expires_inintegeroptionalAlias for valid_time. Ignored when valid_time is set.
success_urlstringoptionalOptional return URL after payment. Must start with http:// or https://. Overrides the checkout default.
cancel_urlstringoptionalOptional return URL after cancel. Same http(s) rule. This is not the webhook URL.
callback_urlstringoptionalPer-order webhook URL, http:// or https://. If omitted, the order keeps the Notifications webhook URL saved at the time it is created.
remarkstringoptionalInternal note. Not shown in the popup.
languagestringoptionalCheckout language. Default from Settings → Checkout (usually en).
Headers
AuthorizationheaderrequiredBearer pk_… from dashboard Settings → Developer.
Content-Typeheaderoptionalapplication/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.
idstringoptionalInternal row id. Prefer cid for CRM storage; this value is not used on query.
cidstringrequiredPublic payment id. Unique per order. Use it in query, webhooks, and support tickets.
tokenstringoptionalHosted checkout token. Already embedded in checkout_url as /pay/chk_….
order_idstringrequiredYour order id. Unique per workspace. Repeating it on create returns this same order.
payer_idstringoptionalYour user id. Grouped on the dashboard Customers page when present.
payer_emailstringoptionalOptional payer email. Stored only; not required to open checkout.
payer_namestringoptionalOptional payer display name on the payments list.
order_amountstringrequiredFiat amount as a decimal string (for example 50.00).
order_currencystringrequiredFiat currency. Send USD. Uppercased on store.
fiat_amountstringoptionalAlias of order_amount for older clients.
fiat_currencystringoptionalAlias of order_currency.
statusstringrequiredpending, awaiting_payment, paid_partial, paid, paid_over, review, expired, cancelled.
remarkstringoptionalFree-text note from create. Not shown to the payer.
languagestringoptionalCheckout UI language. Defaults to the workspace setting (usually en).
chain_idstringoptionalSet after the payer selects an asset. Null on a fresh create.
token_idstringoptionalAsset identifier on that network after quote lock.
asset_symbolstringoptionalQuoted ticker, for example USDT. Null before the payer picks an asset.
network_namestringoptionalQuoted network display name, for example Tron.
crypto_amountstringoptionalQuoted crypto amount as a decimal string, or null before lock.
source_deductionstringoptionalQuote minus crypto actually applied, when some funds have been applied. Informational. Null before that.
quote_ratestringoptionalUSD per unit of the asset at the market price when the payer chose it, or null before that. The quote keeps this rate.
payment_addressstringoptionalAddress shown in checkout after quote lock. Do not reuse it for a different order.
expires_atstringoptionalISO-8601 expiry. Open orders read after this become expired.
expire_timeintegeroptionalSame expiry as Unix milliseconds.
paid_atstringoptionalISO-8601 paid time when status is paid or paid_over, else null.
checkout_urlstringrequiredAbsolute URL for the 400×720 popup. Open it as returned — do not rewrite the host or token.
merchant_display_namestringoptionalWorkspace name shown in the popup (Settings → Merchant).
merchant_logo_urlstringoptionalLogo URL shown in the popup, or null.
demobooleanrequiredTrue when the order was created with a demo key. Its payment is simulated; never credit a customer for it.
Errors
Failures still return JSON. Read code, not only the HTTP status. Full table: Errors.
40000HTTP 400optionalValidation: missing order_id, amount ≤ 0, or success_url / cancel_url / callback_url not http(s).
40003HTTP 400optionalorder_amount is outside the minimum or maximum order set for your account.
40100HTTP 401optionalMissing or invalid API key, or the workspace is not active.