> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt. # Query Query current order status and payment results. The essential tool for reconciliation and exception handling. ## API Information - **Endpoint:** POST `https://api.aimt-horizon.com/upay/v2/query` - **Signature:** Uses terminal_sn + terminal_key ## Request Parameters | Parameter | Type | Required | Description | | ------------------- | ---------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `terminal_sn` | String(32) | Yes | Valid terminal under the original merchant, not target_device_id. Cross-terminal queries require authorization under that merchant. | | `sn` | String(16) | Conditional | System order number (preferred lookup; one of sn or client_sn required) | | `client_sn` | String(32) | Conditional | Original tradePush.out_trade_no; provide sn or client_sn, and keep them consistent if both are provided. | | `refund_request_no` | String(31) | No | Provide the original refund ID to query that refund. Without it, the latest transaction may be returned, including a refund. | ## Response Key Fields ```json { "result_code": "200", "biz_response": { "result_code": "SUCCESS", "data": { "sn": "7892250221234567", "client_sn": "SG20261022001", "tsn": "7892250221234568", "type": "PAYMENT", "status": "SUCCESS", "order_status": "PAID", "payway": "2", "total_amount": "100", "net_amount": "100", "subject": "Dining - Table 12", "finish_time": "1792627201000" } } } ``` | Parameter | Description | | -------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `type` | Transaction type: PAYMENT, REFUND, CANCEL, etc.; interpret together with status. | | `tsn` | Platform transaction ID; one order may have multiple transactions. | | `order_status` | Aggregate order state; see Response and State Handling, including pending/error payment, refund and cancellation states. | | `status` | Current transaction state, interpreted with type; SUCCESS can refer to a refund as well as a payment. | | `total_amount` | Original transaction amount | | `net_amount` | Remaining amount (total_amount minus refunds) | | `finish_time` | Completion time of the returned transaction in Unix milliseconds; may be refund completion time and may be absent while pending. | :::info When to call Query - **1. Post-push confirmation:** After pushing an order, query to confirm payment result. - **2. Unknown payment status:** Network timeout or exception — query to determine the true state. - **3. Post-refund confirmation:** Verify refund result after calling the refund API. - **4. Prevent single-sided transactions:** Provide a manual query button for operators. ::: ## Query by Merchant Order ID ```json { "terminal_sn": "2101107140290972547", "client_sn": "SG20261022001" } ``` Prefer `sn` instead of `client_sn` once available. Use a valid caller under the original merchant. Wrong ownership, no payment order yet or permission errors can all cause a missing result; none authorizes another collection. ## Example: Query Succeeded and Payment Succeeded ```json { "result_code": "200", "biz_response": { "result_code": "SUCCESS", "data": { "sn": "7892250221234567", "client_sn": "SG20261022001", "tsn": "7892250221234568", "type": "PAYMENT", "status": "SUCCESS", "order_status": "PAID", "total_amount": "100", "net_amount": "100" } } } ``` A successful query may also return pending or failed transaction states. Follow the [four-layer rules](/guide/business.md#response-states). Add the original `refund_request_no` to query a specific refund and expect `type=REFUND`, not PAYMENT.