Crypto Order Inquiry

Overview

The order inquiry API actively retrieves the latest status, fee and on-chain details of a crypto pay-in or pay-out order. Pay-in and pay-out are separate endpoints that share the same request body but return different payloads.

Recommended usage

Use the Callback as the primary source of status changes and treat inquiry as a reconciliation fallback when a callback is lost. Avoid high-frequency polling (an interval of at least 5 seconds is recommended).

Common request headers (including the mandatory Nonce), common body fields and the unified response envelope are described in Crypto Integration Overview.

---

Request path

Domain: Prefer unified host openapi.toppayment.com (path unchanged); legacy crypto domain (global-digit-openapi.toppayment.com) remains available.

Scenario	Environment	URL
Pay-in inquiry	Sandbox	https://openapi.toppayment.com/crypto/sandbox/pay/query
Pay-in inquiry	Production	https://openapi.toppayment.com/crypto/pay/query
Pay-out inquiry	Sandbox	https://openapi.toppayment.com/crypto/sandbox/disbursement/query
Pay-out inquiry	Production	https://openapi.toppayment.com/crypto/disbursement/query

Request headers

Field	Required	Type	Description
Content-Type	M	String	Fixed value: application/json
Nonce	M	String(16-64)	Anti-replay random string, unique within 10 minutes, excluded from the signature

Request body

Pay-in and pay-out inquiries share the same request parameters.

Field	Required	Type	Description
mchNo	M	String(32)	Merchant number In sandbox use the SD-prefixed sandbox merchant number
timestamp	M	String(13)	Request timestamp (13-digit milliseconds), within ±5 minutes
sign	M	String	Signature, see Signature
orderNum	C	String(64)	Merchant order number
platOrderNum	C	String(64)	Platform order number
tenantCode	O	String(32)	Sub-tenant code, defaults to the default tenant
countryCode	O	String(16)	Country code, not needed for crypto

One of the two order numbers is required

At least one of orderNum and platOrderNum must be provided; omitting both returns 0001 (orderNum or platOrderNum required). When both are provided, platOrderNum takes precedence. A non-existent order returns 0006.

Request example

Content-Type: application/json
Nonce: 5d8b3f1c74a920e6b8c3

{
    "mchNo": "{{mchNo}}",
    "orderNum": "CR1788506800926",
    "timestamp": "1749451858772",
    "sign": "replace with generated signature"
}

{
    "mchNo": "{{mchNo}}",
    "platOrderNum": "CR20260904152640640",
    "timestamp": "1749451858772",
    "sign": "replace with generated signature"
}

---

Pay-in inquiry response

Response body

Field	Required	Type	Description
success	M	Boolean	Whether the request succeeded
code	M	String	Response code 9999: success; otherwise see Exception Codes
msg	O	String	Response message, null on success
timeStamp	M	Number	Server response time (milliseconds)
data	M	Object	Response payload
orderNum	M	String	Merchant order number
platOrderNum	M	String	Platform order number
payMoney	M	Number	Collection quantity
fee	O	Number	Fee null when no fee has been incurred yet (e.g. unpaid order)
currency	O	String	Coin null in cashier mode before the payer selects a coin
netWork	O	String	Chain network, same as above
inAddress	O	String	Deposit address null when not yet assigned
status	M	String	Order status, see the table below

Pay-in status values

status	Description	Final
WAITING	Awaiting payment (includes order processing and created-but-unpaid)	No
SUCCESS	Collected successfully, funds credited	Yes
FAILED	Order creation failed	Yes
EXPIRED	Order expired (unpaid beyond expiryPeriod)	Yes

Difference from the callback status

The inquiry endpoint returns the unified display status (WAITING / SUCCESS / FAILED / EXPIRED), whereas the pay-in callback returns the detailed order status (INIT_ORDER / NO_PAY / SUCCESS / PAY_ERROR, etc.). The two value sets differ, so handle them separately. See Callback.

Response example

{
    "success": true,
    "code": "9999",
    "msg": null,
    "timeStamp": 1767873172906,
    "data": {
        "orderNum": "CR1788506800926",
        "platOrderNum": "CR20260904152640640",
        "payMoney": 10.500000,
        "fee": 1.100000,
        "currency": "USDT",
        "netWork": "TRC20",
        "inAddress": "TP5wzCqNsJFNT83m1VXdF2Aj1ageFWgqW2",
        "status": "SUCCESS"
    }
}

{
    "success": true,
    "code": "9999",
    "msg": null,
    "timeStamp": 1767873172906,
    "data": {
        "orderNum": "CR1788506800927",
        "platOrderNum": "CR20260904152640641",
        "payMoney": 10.500000,
        "fee": null,
        "currency": null,
        "netWork": null,
        "inAddress": null,
        "status": "WAITING"
    }
}

{
    "success": false,
    "code": "0006",
    "msg": "[0006]the order does not exist!",
    "timeStamp": 1767873172906,
    "data": null
}

---

Pay-out inquiry response

Response body

Field	Required	Type	Description
success	M	Boolean	Whether the request succeeded
code	M	String	Response code 9999: success; otherwise see Exception Codes
msg	O	String	Response message, null on success
timeStamp	M	Number	Server response time (milliseconds)
data	M	Object	Response payload
orderNum	M	String	Merchant order number
platOrderNum	M	String	Platform order number
amount	M	Number	Payout quantity
fee	M	Number	Fee
feeType	M	Number	Fee bearer 0: deducted from the payout quantity; 1: charged separately
status	M	Number	Order status code, see Pay-out status codes
statusMsg	M	String	Unified display status PENDING / PROCESSING / SUCCESS / FAILED / CANCELLED
currency	M	String	Coin
netWork	M	String	Chain network

Response example

{
    "success": true,
    "code": "9999",
    "msg": null,
    "timeStamp": 1767873172906,
    "data": {
        "orderNum": "CW1788506801001",
        "platOrderNum": "CW20260825143024553",
        "amount": 10.500000,
        "fee": 0.700000,
        "feeType": 0,
        "status": 2,
        "statusMsg": "SUCCESS",
        "currency": "USDT",
        "netWork": "TRC20"
    }
}

{
    "success": true,
    "code": "9999",
    "msg": null,
    "timeStamp": 1767873172906,
    "data": {
        "orderNum": "CW1788506801002",
        "platOrderNum": "CW20260825143024554",
        "amount": 10.500000,
        "fee": 0.700000,
        "feeType": 0,
        "status": 1,
        "statusMsg": "PENDING",
        "currency": "USDT",
        "netWork": "TRC20"
    }
}

---

Reconciliation guidance

• Use platOrderNum as the reconciliation primary key; orderNum is only unique within a merchant.
• Stop polling only on a final status: pay-in SUCCESS / FAILED / EXPIRED, pay-out status of 2 / 3 / 4.
• Start inquiry-based compensation only after the expected callback window elapses, and make your handler idempotent to avoid double processing.

---

References

• Crypto Pay-In
• Crypto Pay-Out
• Crypto Callback
• Exception Codes