Online payments payments
Start an online recharge: creates an unpaid order, pre-orders it at the payment gateway and returns the payment URL.
Pick an endpoint to see its example call on the right.
Authentication
Send the X-API-Key header (create a key on the API Keys page; the key is shown only once at creation). An Authorization: Bearer token obtained by logging in also works.
X-API-Key
Authentication failures return 401; forbidden returns 403 (code such as insufficient_scope).
Conventions
Paging uses page (from 1) and page_size; sort with sort=field or sort=-field.
Times are RFC 3339 (UTC); amounts are in cents.
Writes return 200/201/204 on success; duplicates of a unique key return 409.
/api/v2/payments/usdt/orders/{id}Get USDT order
Authentication: User
/api/v2/payments/usdt/orders/{id}/checkCheck USDT payment now
Authentication: User
/api/v2/payments/{provider}/ordersCreate online payment
Authentication: User
Request body application/json
| Field | Type | Description |
|---|---|---|
amount_centsRequired | integer | Recharge amount in cents, 1 to 1000000000000 (per-order cap, same as the backend account.MaxAmount). USDT has its own per-order cap: the converted amount may not exceed 2^40 units of 0.0001 USDT (about 109 million USDT); beyond that it returns 422 (/amount_cents range, with a message naming the USDT cap). |
intent | PaymentIntent | Fulfilment intent (paying the shortfall online): once the payment is credited to the balance, the server fulfils it (calls the buy/renew/change/add-on API with the same key) without needing the browser open. On order creation the original request body is dry-run first; a failing dry run returns that error unchanged. The quoted amount and currency are snapshotted; if the price changed, the quote expired (paid more than 2 hours after a gateway order / after a USDT order expired) or fulfilment failed, nothing is fulfilled, the money stays in the balance, the order gets data.intent.state=failed with code/reason, and an inbox message is sent. The result is in the order's data.intent. |
Online payments object
| Field | Type | Description |
|---|---|---|
address | string | Receiving address (TRC20). |
amount | string | USDT amount to pay (4 decimals, including the tail that identifies the order); must be transferred exactly. |
amount_centsRequired | integer | Recharge amount in cents, 1 to 1000000000000 (per-order cap, same as the backend account.MaxAmount). USDT has its own per-order cap: the converted amount may not exceed 2^40 units of 0.0001 USDT (about 109 million USDT); beyond that it returns 422 (/amount_cents range, with a message naming the USDT cap). |
chain_error | string | Known reason the chain was not queried this time (only possible when checked=false); auth = the chain query service rejected the platform API key and an administrator must fix it. Absent = queried, throttled or a transient failure. |
checked | boolean | Whether the chain was actually queried this time; false = throttled (15 s per tenant, 5 s per address) or the query failed, status unchanged. |
created_at | string | Order creation time; together with expires_at it gives the full validity period for the progress bar. |
credited_order_id | integer | ID of the paid recharge order created when the transfer was credited manually (manual credit only); when present the credited amount follows the balance history and may differ from the ordered amount. |
currency | string | Account currency. |
expires_at | string | Expiry time; transfers after it are not credited automatically and go to the transfer list for admins. |
gateway | string | The payment gateway the order was placed with. |
intent | PaymentIntent | Fulfilment intent (paying the shortfall online): once the payment is credited to the balance, the server fulfils it (calls the buy/renew/change/add-on API with the same key) without needing the browser open. On order creation the original request body is dry-run first; a failing dry run returns that error unchanged. The quoted amount and currency are snapshotted; if the price changed, the quote expired (paid more than 2 hours after a gateway order / after a USDT order expired) or fulfilment failed, nothing is fulfilled, the money stays in the balance, the order gets data.intent.state=failed with code/reason, and an inbox message is sent. The result is in the order's data.intent. |
mch_order_no | string | Recharge order number. |
order_id | integer | Recharge order ID. |
pay_url | string | Payment address: a redirect URL, or a QR code string for weixin:// and Alipay face-to-face payment; tron:<address> for USDT. |
rate | string | Rate locked at order time: 1 USDT = rate units of the account currency. |
server_time | string | Current server time; the panel derives the countdown and expiry from its offset to the browser clock instead of trusting the browser clock. |
status | string | unpaid = awaiting transfer; paid = received and credited; expired = expired. |
txid | string | On-chain transaction ID that was credited (paid orders only). |
usdt | UsdtPay | Payment details of a USDT order. |
Responses and errors
Success returns the resource JSON directly (HTTP 2xx); failures return application/problem+json (code, detail, plus errors on validation failures); lists carry items + total.
{
"id": 1,
"name": "example"
}{
"items": [
{
"id": 1
}
],
"page": 1,
"page_size": 20,
"total": 1
}{
"code": "validation_failed",
"detail": "Invalid request parameters",
"errors": [
{
"code": "required",
"field": "/name",
"message": "name is required"
}
],
"request_id": "0123456789abcdef",
"status": 422,
"title": "Unprocessable Entity",
"type": "about:blank"
}