代付订单查询接口
接口说明
转账订单状态查询接口,支持通过平台订单号(transactionNo)或商户订单号(orderNo)查询转账订单的详细状态信息。
适用对象
间连商户
请求 URL
https://openapi.shuhuipay.com/v1/order/queryTrans请求方法
POST
公共参数说明详见「通用规则 - API公共参数」部分
频率限制:
- 每个商户每分钟最多查询 120 次,超过限制将返回错误码 9000
- 建议商户端做好请求频率控制,避免频繁查询
- 对于转账结果,建议优先使用异步通知,查询接口作为补充手段
请求参数(bizContent)
transactionNo、orderNo 二者必须提供其中一个。推荐使用 transactionNo(平台订单号)进行查询,效率更高。
| 参数名 | 类型 | 必填 | 参数说明 |
|---|---|---|---|
transactionNo |
String | 二选一 | 平台订单号,与 orderNo 二选一 |
orderNo |
String | 二选一 | 商户订单号,与 transactionNo 二选一 |
请求示例
通过 transactionNo 查询(推荐)
JSON
{
"appId": "you_system_appid",
"subMerchantNo": "your_user_id",
"bizContent": "{\"transactionNo\":\"SHTRANS202608042051264580514\"}",
"version": "1.0",
"nonce": "49d55020fa3adf6ed67b253c583ccdaa",
"contentHash": "95772c8a0c74e52b707e2ace5963e0eae956e8b1ae26e86a6cde5469247d0382",
"timestamp": "2026-08-04 14:33:11",
"sign": "your_sign"
}
通过 orderNo 查询
JSON
{
"appId": "you_system_appid",
"subMerchantNo": "your_user_id",
"bizContent": "{\"orderNo\":\"ORDER202608013137111100000000007\"}",
"version": "1.0",
"nonce": "49d55020fa3adf6ed67b253c583ccdaa",
"contentHash": "95772c8a0c74e52b707e2ace5963e0eae956e8b1ae26e86a6cde5469247d0382",
"timestamp": "2026-08-04 14:33:11",
"sign": "your_sign"
}
响应参数
公共返回参数
| 参数 | 类型 | 必须 | 参数说明 |
|---|---|---|---|
code |
String | Y | 响应状态码,成功 0000 |
message |
String | Y | 响应描述 |
timestamp |
String | Y | 响应时间戳,UTC 时间,ISO 8601 格式 |
data |
Object | Y | 业务数据,无数据时返回空对象 {} |
响应附加参数(data)
| 参数名 | 类型 | 必填 | 参数说明 |
|---|---|---|---|
transactionNo |
String | Y | 平台订单号 |
orderNo |
String | Y | 商户订单号 |
orderStatus |
Integer | Y | 订单状态码(见下方状态码说明) |
amount |
String | Y | 订单金额(元) |
pointsDeducted |
String | N | 扣除积分 |
paymentMethod |
String | Y | 支付编码,如 ALIPAY_TRANSFER、WECHAT_TRANSFER、BRANK_TRANSFER |
channel |
String | N | 支付渠道名称 |
channelId |
String | N | 渠道 ID |
channelRate |
String | N | 渠道费率 |
feeAmount |
String | N | 手续费(元) |
settleAmount |
String | N | 结算金额(元) |
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 | 订单备注/描述 |
payeeIdentity |
String | N | 收款方标识(如支付宝用户 UID) |
payeeName |
String | N | 收款方姓名 |
payeeIdentityType |
String | N | 收款方标识类型,如 ALIPAY_USER_ID、ALIPAY_LOGON_ID |
转账订单状态码说明
| 状态码 | 状态 | 说明 |
|---|---|---|
0 |
待处理 | 订单已创建,等待处理 |
1 |
处理中 | 转账处理中 |
2 |
已完成 | 转账成功完成 |
3 |
失败 | 转账失败 |
通知状态码说明
| 状态码 | 状态 | 说明 |
|---|---|---|
0 |
未通知 | 尚未发送异步通知 |
1 |
通知中 | 异步通知循环发送中 |
2 |
通知成功 | 异步通知已成功送达 |
3 |
通知失败 | 异步通知发送失败 |
响应示例
成功响应:
JSON
{
"code": "0000",
"message": "Success",
"timestamp": "2026-08-04T20:51:30.000Z",
"data": {
"transactionNo": "SHTRANS202608042051264580514",
"orderNo": "ORDER202608013137111100000000007",
"orderStatus": 0,
"amount": "100.00",
"pointsDeducted": "0",
"paymentMethod": "BRANK_TRANSFER",
"channel": "Alipay",
"channelId": "2",
"channelRate": "",
"feeAmount": "1",
"settleAmount": "0",
"merchantId": "4",
"subMerchantId": "",
"appId": "20260717134222367829283",
"notifyStatus": 0,
"notifyUrl": "",
"notifyTime": "",
"createTime": "2026-08-04 20:51:26",
"payTime": "",
"openId": "",
"clientIp": "",
"remark": "",
"payeeIdentity": "2088002001415652",
"payeeName": "阳ff",
"payeeIdentityType": "ALIPAY_USER_ID"
}
}
失败响应:
JSON
// 订单不存在
{
"code": "4004",
"message": "订单号 ORDER202608010001 不存在或不属于当前商户",
"timestamp": "2026-08-04T20:51:30.000Z",
"data": {}
}
// 参数缺失
{
"code": "4001",
"message": "transactionNo 和 orderNo 不能同时为空",
"timestamp": "2026-08-04T20:51:30.000Z",
"data": {}
}
代码示例
Java
import java.util.HashMap;
import java.util.Map;
import com.alibaba.fastjson.JSON;
public class TransOrderQueryExample {
public static void main(String[] args) {
// 方式一:通过平台订单号查询
Map<String, String> queryByTransactionNo = new HashMap<>();
queryByTransactionNo.put("transactionNo", "SHTRANS202608042051264580514");
String result1 = queryTransOrder(queryByTransactionNo);
System.out.println("查询结果:" + result1);
// 方式二:通过商户订单号查询
Map<String, String> queryByOrderNo = new HashMap<>();
queryByOrderNo.put("orderNo", "ORDER202608013137111100000000007");
String result2 = queryTransOrder(queryByOrderNo);
System.out.println("查询结果:" + result2);
}
public static String queryTransOrder(Map<String, String> queryParams) {
String appId = "your_app_id";
String subMerchantNo = "your_user_id";
String signKey = "your_sign_key";
String apiUrl = "https://openapi.shuhuipay.com/v1/order/queryTrans";
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-08-04 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_trans_order(query_params):
"""查询转账订单状态"""
sys_appid = "your_sys_appid"
open_subMerchantNo = "your_open_subMerchantNo"
sign_key = "your_sign_key"
api_url = "https://openapi.shuhuipay.com/v1/order/queryTrans"
request_data = {
"appId": sys_appid,
"subMerchantNo": open_subMerchantNo,
"version": "1.0",
"timestamp": "2026-08-04 14:33:11",
"nonce": "49d55020fa3adf6ed67b253c583ccdaa",
"bizContent": json.dumps(query_params),
"contentHash": "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_trans_order({"transactionNo": "SHTRANS202608042051264580514"})
# 方式二:通过商户订单号查询
result2 = query_trans_order({"orderNo": "ORDER202608013137111100000000007"})
# 处理返回结果
if result1 and result1.get("code") == "0000":
data = result1.get("data", {})
order_status = data.get("orderStatus")
if order_status == 0:
print("待处理")
elif order_status == 1:
print("处理中")
elif order_status == 2:
print("转账成功")
elif order_status == 3:
print("转账失败")
PHP
<?php
class TransOrderQuery {
private $appId = 'your_app_id';
private $subMerchantNo = 'your_user_id';
private $signKey = 'your_sign_key';
private $apiUrl = 'https://openapi.shuhuipay.com/v1/order/queryTrans';
public function queryTransOrder($queryParams) {
$requestData = [
'appId' => $this->appId,
'subMerchantNo' => $this->subMerchantNo,
'bizContent' => json_encode($queryParams),
'version' => '1.0',
'nonce' => '49d55020fa3adf6ed67b253c583ccdaa',
'contentHash' => '95772c8a0c74e52b707e2ace5963e0eae956e8b1ae26e86a6cde5469247d0382',
'timestamp' => '2026-08-04 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 TransOrderQuery())->queryTransOrder([
'transactionNo' => 'SHTRANS202608042051264580514'
]);
// 方式二:通过商户订单号查询
$result2 = (new TransOrderQuery())->queryTransOrder([
'orderNo' => 'ORDER202608013137111100000000007'
]);
// 处理返回结果
if ($result1 && $result1['code'] === '0000') {
$data = $result1['data'] ?? [];
switch ($data['orderStatus'] ?? 0) {
case 0: echo "待处理"; break;
case 1: echo "处理中"; break;
case 2: echo "转账成功"; break;
case 3: echo "转账失败"; break;
}
}
注意事项
查询限制:
- 每个商户每分钟最多查询 120 次,超过限制将返回错误码 9000
- 建议商户端做好请求频率控制,避免频繁查询
- 对于转账结果,建议优先使用异步通知,查询接口作为补充手段
查询建议:
- 推荐使用
transactionNo(平台订单号)进行查询,效率更高 - 订单创建后建议等待 5 秒再发起查询,确保订单状态已同步
- 查询结果中的时间字段格式为
YYYY-MM-DD HH:mm:ss
最佳实践:
- 转账后等待异步通知,如超时未收到再发起主动查询
- 查询间隔建议:首次 5 秒,后续每隔 10 秒查询一次,最多查询 5 次
- 妥善保存
transactionNo(平台订单号),便于后续查询和对账