Query order

Merchant-initiated lookups. The existence of this endpoint is part of the design: a callback is "we notify you", and it can fail or be missed — your URL went down, you were mid-deploy, or you simply want to reconcile.

http

GET {API_BASE}/api/pay/open/queryOrder?merchantOrderNo=SHOP-2026-0001
X-Pay-Api-Key: <your API KEY>

Query parameters

Parameter	Type	Required	Description
`merchantOrderNo`	string	No	Your own order number
`orderNo`	string	No	The platform order number

Passing both filters by AND; passing neither fails to locate an order. Prefer merchantOrderNo — it is the number you already have in your system, so reconciliation needs no mapping table.

bash

curl "$API_BASE/api/pay/open/queryOrder?merchantOrderNo=SHOP-2026-0001" \
  -H "X-Pay-Api-Key: $PAY_API_KEY"

You can only query your own orders

The authorization boundary is the merchant filter in the server-side query: no order number you pass can cross it. Query someone else's order number and you get "not found", not their data.

Response

The order view matches the one returned at creation:

json

{
  "code": 0,
  "data": {
    "orderNo": "PO20261011XXXXXXXXXXXX",
    "merchantOrderNo": "SHOP-2026-0001",
    "merchantNo": "M00000XXXX",
    "status": 3,
    "statusText": "已确认",
    "orderType": 1,
    "amountMinimal": "100500000",
    "payAmountMinimal": "100500123",
    "payAmountDisplay": "100.500123",
    "receivedAmountMinimal": "100500123",
    "chainId": 2,
    "chainKey": "tron",
    "tokenId": 1,
    "tokenSymbol": "USDT",
    "payAddress": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "txHash": "0x...on-chain tx hash",
    "confirmations": 19,
    "requiredConfirmations": 19,
    "paidAt": "2026-10-11T09:58:12Z",
    "confirmedAt": "2026-10-11T09:58:41Z",
    "identify": { "mode": 1, "orderNo": "PO20261011XXXXXXXXXXXX", "calldataSuffix": "0x..." }
  },
  "msg": "获取成功"
}

Status values

Value	Name	What your system should do
1	Pending	Wait, or check whether the buyer has paid yet
2	Submitted	The payment is on-chain; wait for confirmations. Do not ship in this state
3	Confirmed	Confirmations met; safe to process the order (the callback also fires at this point)
4	Finished	Callback succeeded; final state
5	Expired	The order is void — stop waiting
6	Manual	The on-chain payment is ambiguous and needs a human; contact the platform

Do not use numeric size to decide "paid"

The values are not ordered by degree of payment: Expired (5) and Manual (6) are numerically greater than Confirmed (3). Treat only 3 and 4 as paid.

What to use it for

Cover a missed callback

When a callback never arrived or failed to process, query the real state and bring the order up to date.

Scheduled reconciliation

Walk your order list day by day and surface any order whose state disagrees.

Re-check before shipping

For important orders, query once more before shipping instead of trusting a single notification that may be forged or stale.

Query results are authoritative

A callback may be delayed, repeated, or never delivered because your URL was unreachable. Before any critical action, treat the query result as the source of truth and use callbacks only as change triggers.

Create order
Callbacks and verification — why callbacks alone are not enough
Errors

Query order ​

Query parameters ​

You can only query your own orders ​

Response ​

Status values ​

What to use it for ​