> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt. # 订单查询 查询当前订单状态与支付结果,用于对账与异常处理。 ## 接口信息 - **接口地址:** POST `https://api.aimt-horizon.com/upay/v2/query` - **签名凭证:** 使用 terminal_sn + terminal_key ## 请求参数 | 参数 | 类型 | 是否必填 | 说明 | | ------------------- | ---------- | ---- | ----------------------------------------------- | | `terminal_sn` | String(32) | 是 | 原交易商户下的有效终端;不能填 target_device_id。跨终端查询须保持同商户授权。 | | `sn` | String(16) | 条件必填 | 系统订单号(优先使用;sn 与 client_sn 至少提供一个) | | `client_sn` | String(32) | 条件必填 | 原 tradePush.out_trade_no;与 sn 至少传一个,同时传入时保持一致。 | | `refund_request_no` | String(31) | 否 | 查询指定退款时填写原退款请求号;省略时通常返回订单最新交易流水,可能是退款。 | ## 响应关键字段 ```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" } } } ``` | 参数 | 说明 | | -------------- | ----------------------------------------------- | | `type` | 流水类型:PAYMENT、REFUND、CANCEL 等;与 status 一起判断。 | | `tsn` | 平台交易流水号;同一订单可对应多条流水。 | | `order_status` | 订单聚合状态,见响应与状态判定;包括支付、退款、撤销的处理中及错误状态。 | | `status` | 当前交易流水状态,需结合 type 判断;SUCCESS 不一定是支付成功,也可能是退款成功。 | | `total_amount` | 原始交易金额 | | `net_amount` | 剩余金额(交易总金额减去退款金额) | | `finish_time` | 当前返回流水的完成时间,Unix 毫秒;退款查询时可能是退款完成时间,未完成时可缺省。 | :::info 查询调用场景 - **1. 推送后确认:** 推送订单后,查询并确认支付结果。 - **2. 支付状态未知:** 发生网络超时或异常时,查询实际状态。 - **3. 退款后确认:** 调用退款接口后,查询并确认退款结果。 - **4. 防止单边账:** 为操作员提供手动查询按钮。 ::: ## 按商户订单号查询 ```json { "terminal_sn": "2101107140290972547", "client_sn": "SG20261022001" } ``` 取得 `sn` 后优先用它替代 `client_sn`。通用查询支持原商户下的有效调用终端;目标设备归属错误、尚未创建支付单或权限问题都可能导致查不到,不能直接重新收款。 ## 查询成功且付款成功的字段示例 ```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" } } } ``` 查询成功也可返回处理中或失败的交易状态;请按[四层规则](/zh/guide/business.md#response-states)判断。查询某次退款时额外传入原 `refund_request_no`,预期 `type=REFUND`,不要把它解释成 PAYMENT。