For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt, and this page is available as Markdown at /zh/api/query.md.
  • 简体中文
  • 订单查询

    查询当前订单状态与支付结果,用于对账与异常处理。

    接口信息

    • 接口地址: POST https://api.aimt-horizon.com/upay/v2/query
    • 签名凭证: 使用 terminal_sn + terminal_key

    请求参数

    参数类型是否必填说明
    terminal_snString(32)是原交易商户下的有效终端;不能填 target_device_id。跨终端查询须保持同商户授权。
    snString(16)条件必填系统订单号(优先使用;sn 与 client_sn 至少提供一个)
    client_snString(32)条件必填原 tradePush.out_trade_no;与 sn 至少传一个,同时传入时保持一致。
    refund_request_noString(31)否查询指定退款时填写原退款请求号;省略时通常返回订单最新交易流水,可能是退款。

    响应关键字段

    {
      "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 毫秒;退款查询时可能是退款完成时间,未完成时可缺省。
    查询调用场景
    • 1. 推送后确认: 推送订单后,查询并确认支付结果。
    • 2. 支付状态未知: 发生网络超时或异常时,查询实际状态。
    • 3. 退款后确认: 调用退款接口后,查询并确认退款结果。
    • 4. 防止单边账: 为操作员提供手动查询按钮。

    按商户订单号查询

    {
      "terminal_sn": "2101107140290972547",
      "client_sn": "SG20261022001"
    }

    取得 sn 后优先用它替代 client_sn。通用查询支持原商户下的有效调用终端;目标设备归属错误、尚未创建支付单或权限问题都可能导致查不到,不能直接重新收款。

    查询成功且付款成功的字段示例

    {
      "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"
        }
      }
    }

    查询成功也可返回处理中或失败的交易状态;请按四层规则判断。查询某次退款时额外传入原 refund_request_no,预期 type=REFUND,不要把它解释成 PAYMENT。