API ReferenceQuery Order
On this pageQuery Order StatusEndpointRequestResponseQuery SupplementsEndpointRequestResponseQuery Latest SupplementRequestQuery Paid TransactionEndpointRequestResponse

Query Order ​

Query the current state of a payment order and related records. These endpoints use body-level accessSign authentication.

Query Order Status ​

Endpoint ​

POST /v4.0.0/pay/orders/query

Request ​

json
{
  "accessKeyId": "ak_test_abc123",
  "merchantOrderId": "ORDER-20260621-001",
  "accessSign": "BASE64_HMAC_SIGNATURE"
}
FieldTypeRequiredDescription
accessKeyIdstringYesYour merchant Access Key ID
merchantOrderIdstringYesYour unique order identifier
accessSignstringYesHMAC-SHA256 signature of the body (excluding accessSign itself)

Response ​

json
{
  "code": 0,
  "msg": "success",
  "data": {
    "payOrderId": "PO202606210001",
    "merchantOrderId": "ORDER-20260621-001",
    "receiptAddress": "0xabcdef1234567890abcdef1234567890abcdef12",
    "chainCode": "erc20",
    "coinCode": "usdt",
    "amount": "10.50",
    "paidAmount": "10.50",
    "state": 3,
    "payTxId": "0x9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba",
    "createTime": "2026-06-21T10:00:00Z",
    "expireTime": "2026-06-21T11:00:00Z",
    "paidTime": "2026-06-21T10:05:30Z"
  }
}
FieldTypeDescription
data.stateintegerCurrent order state. See Order States
data.paidAmountstringAmount actually paid by the customer
data.payTxIdstringBlockchain transaction hash (present after payment detected)
data.paidTimestringTimestamp when payment was detected

Query Supplements ​

Retrieve all supplement (underpayment top-up) records for an order.

Endpoint ​

POST /v4.0.0/pay/orders/supplements

Request ​

json
{
  "accessKeyId": "ak_test_abc123",
  "payOrderId": "PO202606210001",
  "accessSign": "BASE64_HMAC_SIGNATURE"
}

Response ​

json
{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "supplementId": "SUP001",
      "payOrderId": "PO202606210001",
      "amount": "2.00",
      "paidAmount": "2.00",
      "state": 3,
      "payTxId": "0xabc123...",
      "createTime": "2026-06-21T10:10:00Z"
    }
  ]
}

Query Latest Supplement ​

To get only the most recent supplement record, add the latest flag:

Request ​

json
{
  "accessKeyId": "ak_test_abc123",
  "payOrderId": "PO202606210001",
  "latest": true,
  "accessSign": "BASE64_HMAC_SIGNATURE"
}

The response has the same structure but returns a single object in data instead of an array.

Query Paid Transaction ​

Retrieve the on-chain transaction details for a paid order.

Endpoint ​

POST /v4.0.0/pay/orders/paidTx

Request ​

json
{
  "accessKeyId": "ak_test_abc123",
  "payOrderId": "PO202606210001",
  "accessSign": "BASE64_HMAC_SIGNATURE"
}

Response ​

json
{
  "code": 0,
  "msg": "success",
  "data": {
    "payOrderId": "PO202606210001",
    "payTxId": "0x9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba",
    "fromAddress": "0xcustomerAddress...",
    "toAddress": "0xreceiptAddress...",
    "amount": "10.50",
    "coinCode": "usdt",
    "chainCode": "erc20",
    "blockNumber": 12345678,
    "blockTime": "2026-06-21T10:05:30Z",
    "confirmations": 15
  }
}

TIP

Use Query Order for checking order status. Use Query Paid Transaction when you need detailed on-chain information such as block number and confirmation count.

PreviousCreate OrderNextConfirm Payment