Query Order

API Description

Use this API to query the status and details of an existing order by merchant order number.

Interface Information

• Interface URL: POST /v2/queryOrder
• Content-Type: application/json
• Authentication: Need to pass app-id and signature verification in Header

Request Header Parameters

Parameter	Type	Required	Description
app-id	string	Yes	Merchant Application ID
Content-Type	string	Yes	application/json

Request Parameters

Parameter	Type	Required	Description
sign	string	Yes	Request signature
outTradeNo	string	Yes	Merchant order number to query

Response Parameters

Success Response

{
    "code": 0,
    "data": {
        "merchantUuid": "",
        "appId": "app-caf118dc-4e23-4ced-ab23-8a3f65d5071a",
        "merchantOrderNo": "ORDER_1754379719703_5951",
        "orderNo": "1754379945757879200",
        "tokenSymbol": "USD",
        "tokenCount": "20",
        "currencyId": "USD",
        "payHash": "",
        "payObject": "",
        "state": "NON_PAYMENT",
        "timestamp": 1754379719,
        "timeExpire": 900,
        "payTime": 0,
        "callbackCount": 0,
        "callbackState": ""
    },
    "msg": "success"
}

Error Response

{
    "code": 1001,
    "data": {},
    "msg": "Order not found"
}

Request Examples

cURL Example

curl -X POST "/v2/queryOrder" \
  -H "Content-Type: application/json" \
  -H "app-id: your-app-id" \
  -d '{
    "sign": "c2lnbmF0dXJlX3Rlc3Q=",
    "outTradeNo": "ORDER_1754379719703_5951"
  }'

JavaScript Example

const queryData = {
  sign: "c2lnbmF0dXJlX3Rlc3Q=",
  outTradeNo: "ORDER_1754379719703_5951"
};

fetch('/v2/queryOrder', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'app-id': 'your-app-id'
  },
  body: JSON.stringify(queryData)
})
.then(response => response.json())
.then(data => {
  if (data.code === 0) {
    console.log('Order found:', data.data.orderNo);
    console.log('Order status:', data.data.state);
    console.log('Token amount:', data.data.tokenCount, data.data.tokenSymbol);
  } else {
    console.error('Query failed:', data.msg);
  }
})
.catch(error => {
  console.error('Request failed:', error);
});

Python Example

import requests
import json

url = "https://api.chainpay.com/v2/queryOrder"
headers = {
    "Content-Type": "application/json",
    "app-id": "your-app-id"
}

query_data = {
    "sign": "c2lnbmF0dXJlX3Rlc3Q=",
    "outTradeNo": "ORDER_1754379719703_5951"
}

try:
    response = requests.post(url, headers=headers, json=query_data)
    result = response.json()
    
    if result["code"] == 0:
        order_data = result["data"]
        print(f"Order found: {order_data['orderNo']}")
        print(f"Order status: {order_data['state']}")
        print(f"Token amount: {order_data['tokenCount']} {order_data['tokenSymbol']}")
        print(f"Payment time: {order_data['payTime']}")
    else:
        print(f"Query failed: {result['msg']}")
except requests.exceptions.RequestException as e:
    print(f"Request failed: {e}")

Response Field Description

Success Response Fields

Field	Type	Description
code	integer	Response code, 0 indicates success
data	object	Order data
data.merchantUuid	string	Merchant UUID
data.appId	string	Application ID
data.merchantOrderNo	string	Merchant order number
data.orderNo	string	System generated order number
data.tokenSymbol	string	Token symbol (e.g., USD, USDT)
data.tokenCount	string	Token amount
data.currencyId	string	Currency ID
data.payHash	string	Payment transaction hash
data.payObject	string	Payment object information
data.state	string	Order status (NON_PAYMENT, PAID, EXPIRED, etc.)
data.timestamp	integer	Order creation timestamp
data.timeExpire	integer	Order expiration time in seconds
data.payTime	integer	Payment completion timestamp (0 if not paid)
data.callbackCount	integer	Number of callback attempts
data.callbackState	string	Callback status
msg	string	Response message

Order Status Values

Status	Description
NON_PAYMENT	Order created but not paid
PAID	Order successfully paid
EXPIRED	Order expired
CANCELLED	Order cancelled
REFUNDED	Order refunded

Error Response Fields

Field	Type	Description
code	integer	Error code
data	object	Empty object for error responses
msg	string	Error message description

Error Codes

Code	Description
0	Success
1001	Order not found
1002	Invalid signature
1003	Invalid parameters
1004	Missing required parameters
1005	Access denied

Important Notes

1. Signature Verification: All requests must include a valid signature in the sign parameter
2. Order Number: Use the exact outTradeNo that was used when creating the order
3. Real-time Status: The API returns real-time order status and payment information
4. Timestamp Format: All timestamps are in Unix timestamp format
5. Payment Tracking: Use payHash to track the transaction on blockchain if available

Use Cases

• Order Status Check: Verify if a payment has been completed
• Payment Confirmation: Get payment details and transaction hash
• Order Management: Track order lifecycle and status changes
• Reconciliation: Match payments with order records
• Customer Support: Provide order status information to customers

Integration Tips

1. Polling Strategy: Implement reasonable polling intervals to check order status
2. Webhook Alternative: Consider using webhooks for real-time order status updates
3. Error Handling: Implement proper error handling for different response codes
4. Caching: Cache order status to reduce API calls for frequently queried orders
5. Logging: Log all query requests for debugging and audit purposes