订单查询接口

更新时间：2026-07-01

接口说明

订单状态查询接口，支持通过平台订单号（transactionNo）或商户订单号（orderNo）查询订单的详细状态信息。

接口信息

适用对象：间连商户
请求 URL：https://webpayapi.com/openapi/v1/order/query
请求方法：POST

ℹ️ 公共参数说明详见通用规则 - API公共参数部分

WARNING

⚠️ 频率限制：

每个商户每分钟最多查询 120 次，超过限制将返回错误码 9000
建议商户端做好请求频率控制，避免频繁查询
对于支付结果，建议优先使用异步通知，查询接口作为补充手段

查询流程图

请求参数（bizContent）

INFO

ℹ️ transactionNo、orderNo 二者必须提供其中一个。推荐使用 transactionNo（平台订单号）进行查询，效率更高。

参数名	类型	必填	参数说明
`transactionNo`	String	二选一	平台订单号，与 `orderNo` 二选一
`orderNo`	String	二选一	商户订单号，与 `transactionNo` 二选一

请求示例

方式一：平台订单号方式二：商户订单号

json

{
  "appId": "you_system_appid",
  "subMerchantNo": "your_user_id",
  "bizContent": "{\"transactionNo\":\"SHPAY_202607021507077387091\"}",
  "version": "1.0",
  "nonce": "49d55020fa3adf6ed67b253c583ccdaa",
  "contentHash": "95772c8a0c74e52b707e2ace5963e0eae956e8b1ae26e86a6cde5469247d0382",
  "timestamp": "2026-07-02 14:33:11",
  "sign": "your_sign"
}

json

{
  "appId": "you_system_appid",
  "subMerchantNo": "your_user_id",
  "bizContent": "{\"orderNo\":\"TEST202607021506596406\"}",
  "version": "1.0",
  "nonce": "49d55020fa3adf6ed67b253c583ccdaa",
  "contentHash": "95772c8a0c74e52b707e2ace5963e0eae956e8b1ae26e86a6cde5469247d0382",
  "timestamp": "2026-07-02 14:33:11",
  "sign": "your_sign"
}

响应参数

响应附加参数（data）

参数名	类型	必填	参数说明
`transactionNo`	String	Y	平台订单号
`orderNo`	String	Y	商户订单号
`orderStatus`	Integer	Y	订单状态码（见下方状态码说明）
`amount`	String	Y	订单金额（元）
`pointsDeducted`	String	N	扣除积分
`paymentMethod`	String	Y	支付编码
`merchantId`	String	Y	商户号
`subMerchantId`	String	N	子商户号
`appId`	String	N	应用 ID
`notifyStatus`	Integer	N	通知状态码（见下方状态码说明）
`notifyUrl`	String	N	通知回调地址
`notifyTime`	String	N	通知时间
`createTime`	String	Y	订单创建时间
`payTime`	String	N	支付完成时间
`openId`	String	N	买家 openid（微信/支付宝）
`clientIp`	String	N	下单 IP 地址
`remark`	String	N	订单备注/描述

订单状态码说明

状态码	状态	说明
`1`	待支付	订单已创建，等待用户支付
`2`	支付成功	用户已完成支付
`3`	支付失败	订单支付失败
`4`	已关闭	订单已关闭（超时/主动关闭）
`5`	已退款	订单已发生退款

通知状态码说明

状态码	状态	说明
`0`	未通知	尚未发送异步通知
`1`	通知中	异步通知循环发送中
`2`	通知成功	异步通知已成功送达
`3`	通知失败	异步通知发送失败

响应示例

成功响应：

json

{
  "code": "0000",
  "message": "Success",
  "timestamp": "2026-07-02T18:08:02.000Z",
  "data": {
    "transactionNo": "SHPAY_202607021507077387091",
    "orderNo": "TEST202607021506596406",
    "orderStatus": 2,
    "amount": "0.01",
    "pointsDeducted": "0",
    "paymentMethod": "HUIFU_WX_MINIAPP",
    "merchantId": "208821123132131",
    "subMerchantId": "sub208821123132131",
    "appId": "202606241126125284521215",
    "notifyStatus": 0,
    "notifyUrl": "/api/notify/huifu/handle",
    "notifyTime": "",
    "createTime": "2026-07-02 15:07:07",
    "payTime": "2026-07-02 16:15:10",
    "openId": "",
    "clientIp": "127.0.0.1",
    "remark": ""
  }
}

失败响应：

json

// 订单不存在
{
  "code": "4004",
  "message": "订单号 ORDER202501150001 不存在或不属于当前商户",
  "timestamp": "2026-07-02T18:08:02.000Z",
  "data": {}
}

// 参数缺失
{
  "code": "4001",
  "message": "transactionNo 或 orderNo 必须提供其中一个",
  "timestamp": "2026-07-02T18:08:02.000Z",
  "data": {}
}

代码示例

JavaPythonPHP

java

import java.util.HashMap;
import java.util.Map;
import com.alibaba.fastjson.JSON;

public class OrderQueryExample {
    public static void main(String[] args) {
        // 方式一：通过平台订单号查询
        Map<String, String> queryByTransactionNo = new HashMap<>();
        queryByTransactionNo.put("transactionNo", "SHPAY_202607021507077387091");
        String result1 = queryOrderStatus(queryByTransactionNo);
        System.out.println("查询结果：" + result1);

        // 方式二：通过商户订单号查询
        Map<String, String> queryByOrderNo = new HashMap<>();
        queryByOrderNo.put("orderNo", "TEST202607021506596406");
        String result2 = queryOrderStatus(queryByOrderNo);
        System.out.println("查询结果：" + result2);
    }

    public static String queryOrderStatus(Map<String, String> queryParams) {
        String appId = "your_app_id";
        String subMerchantNo = "your_user_id";
        String signKey = "your_sign_key";
        String apiUrl = "https://webpayapi.com/openapi/v1/order/query";

        Map<String, String> requestData = new HashMap<>();
        requestData.put("appId", appId);
        requestData.put("subMerchantNo", subMerchantNo);
        requestData.put("bizContent", JSON.toJSONString(queryParams));
        requestData.put("version", "1.0");
        requestData.put("nonce", "49d55020fa3adf6ed67b253c583ccdaa");
        requestData.put("contentHash", "95772c8a0c74e52b707e2ace5963e0eae956e8b1ae26e86a6cde5469247d0382");
        requestData.put("timestamp", "2026-07-02 14:33:11");

        String sign = SignUtil.generateSign(requestData, signKey);
        requestData.put("sign", sign);

        String response = HttpUtil.post(apiUrl, requestData);
        return response;
    }
}

python

import requests
import json
import hashlib

def query_order_status(query_params):
    """查询订单状态"""
    sys_appid = "your_sys_appid"
    open_subMerchantNo = "your_open_subMerchantNo"
    sign_key = "your_sign_key"
    api_url = "https://webpayapi.com/openapi/v1/order/query"

    request_data = {
        "sys_appid": sys_appid,
        "open_subMerchantNo": open_subMerchantNo,
        "version": "1.0",
        "timestamp": "2026-07-02 14:33:11",
        "replay": "49d55020fa3adf6ed67b253c583ccdaa",
        "bizContent": json.dumps(query_params),
        "data_hash": "95772c8a0c74e52b707e2ace5963e0eae956e8b1ae26e86a6cde5469247d0382",
    }

    sign = generate_sign(request_data, sign_key)
    request_data["sign"] = sign

    try:
        response = requests.post(api_url, json=request_data, timeout=30)
        return response.json()
    except Exception as e:
        print(f"查询失败: {e}")
        return None

def generate_sign(params, sign_key):
    sorted_params = sorted(params.items())
    sign_str = "&".join([f"{k}={v}" for k, v in sorted_params if v])
    sign_str += f"&key={sign_key}"
    return hashlib.md5(sign_str.encode()).hexdigest().upper()

# 方式一：通过平台订单号查询
result1 = query_order_status({"transactionNo": "SHPAY_202607021507077387091"})

# 方式二：通过商户订单号查询
result2 = query_order_status({"orderNo": "TEST202607021506596406"})

# 处理返回结果
if result1 and result1.get("code") == "0000":
    data = result1.get("data", {})
    order_status = data.get("orderStatus")
    if order_status == 1:
        print("订单待支付")
    elif order_status == 2:
        print("支付成功")
    elif order_status == 3:
        print("支付失败")
    elif order_status == 4:
        print("订单已关闭")
    elif order_status == 5:
        print("已退款")

php

<?php

class OrderQuery {
    private $appId = 'your_app_id';
    private $subMerchantNo = 'your_user_id';
    private $signKey = 'your_sign_key';
    private $apiUrl = 'https://webpayapi.com/openapi/v1/order/query';

    public function queryOrderStatus($queryParams) {
        $requestData = [
            'appId'       => $this->appId,
            'subMerchantNo'      => $this->subMerchantNo,
            'bizContent'  => json_encode($queryParams),
            'version'     => '1.0',
            'nonce'       => '49d55020fa3adf6ed67b253c583ccdaa',
            'contentHash' => '95772c8a0c74e52b707e2ace5963e0eae956e8b1ae26e86a6cde5469247d0382',
            'timestamp'   => '2026-07-02 14:33:11',
        ];

        $requestData['sign'] = $this->generateSign($requestData);
        $response = $this->httpPost($this->apiUrl, $requestData);
        return json_decode($response, true);
    }

    private function generateSign($params) {
        ksort($params);
        $signStr = '';
        foreach ($params as $key => $value) {
            if ($value !== '') {
                $signStr .= "{$key}={$value}&";
            }
        }
        $signStr .= "key={$this->signKey}";
        return strtoupper(md5($signStr));
    }

    private function httpPost($url, $data) {
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
        curl_setopt($ch, CURLOPT_TIMEOUT, 30);
        $response = curl_exec($ch);
        curl_close($ch);
        return $response;
    }
}

// 方式一：通过平台订单号查询
$result1 = (new OrderQuery())->queryOrderStatus([
    'transactionNo' => 'SHPAY_202607021507077387091'
]);

// 方式二：通过商户订单号查询
$result2 = (new OrderQuery())->queryOrderStatus([
    'orderNo' => 'TEST202607021506596406'
]);

// 处理返回结果
if ($result1 && $result1['code'] === '0000') {
    $data = $result1['data'] ?? [];
    switch ($data['orderStatus'] ?? 0) {
        case 1: echo "订单待支付"; break;
        case 2: echo "支付成功"; break;
        case 3: echo "支付失败"; break;
        case 4: echo "订单已关闭"; break;
        case 5: echo "已退款"; break;
    }
}

注意事项

WARNING

⚠️ 查询限制：

每个商户每分钟最多查询 120 次，超过限制将返回错误码 9000
建议商户端做好请求频率控制，避免频繁查询
对于支付结果，建议优先使用异步通知，查询接口作为补充手段

INFO

💡 查询建议：

推荐使用 transactionNo（平台订单号）进行查询，效率更高
订单创建后建议等待 5 秒再发起查询，确保订单状态已同步
查询结果中的时间字段格式为 YYYY-MM-DD HH:mm:ss

TIP

✅ 最佳实践：

支付后等待异步通知，如超时未收到再发起主动查询
查询间隔建议：首次 5 秒，后续每隔 10 秒查询一次，最多查询 5 次
妥善保存 transactionNo（平台订单号），便于后续查询和对账

订单查询接口 ​

接口说明 ​

查询流程图 ​

请求参数（bizContent） ​

请求示例 ​

响应参数 ​

响应附加参数（data） ​

订单状态码说明 ​

通知状态码说明 ​

响应示例 ​

代码示例 ​

注意事项 ​

订单查询接口

接口说明

查询流程图

请求参数（bizContent）

请求示例

响应参数

响应附加参数（data）

订单状态码说明

通知状态码说明

响应示例

代码示例

注意事项