返回主页

代收订单查询接口文档

接口说明

请求URL：https://api.openpayhub.com/api/order/getOrderStatus

请求方式：POST

请求类型：application/json 或 application/x-www-form-urlencoded

认证方式：Header 认证（X-Api-Key + X-Api-Secret）

请求头参数

字段名 变量名 必填 类型 描述
API密钥 X-Api-Key 是 String 商户API密钥，用于身份认证
API密钥 X-Api-Secret 是 String 商户API密钥，用于身份认证（MD5加密后对比）

请求参数

字段名 变量名 必填 类型 示例值 描述
商户订单号 orderId 是 String ORDER20240315001 商户生成的唯一订单号，长度6-32位

请求示例

curl --location 'https://api.openpayhub.com/api/order/getOrderStatus' \
--header 'X-Api-Key: your_api_key' \
--header 'X-Api-Secret: your_api_secret' \
--header 'Content-Type: application/json' \
--data '{
    "orderId": "ORDER20240315001"
}'

返回参数

字段名 变量名 必填 类型 示例值 描述
返回状态码 code 是 int 0 0-处理成功，其他-处理有误
返回信息 message 否 String success 具体返回信息
返回数据 data 否 Object {} 返回数据对象

data数据格式

变量名 必填 类型 示例值 描述
orderId 是 String ORDER20240315001 商户订单号
tmId 是 String HZ1234567890 平台订单号
amount 是 int 100 支付金额（整数）
utr 否 String 123456789012 UTR交易参考号（支付成功后返回）
status 是 String SUCCESS 订单状态：SUCCESS-成功，FAILED-失败，PENDING-处理中

订单状态说明

状态值 说明 描述
PENDING 处理中 订单正在处理中，尚未完成支付
SUCCESS 成功 订单支付成功
FAILED 失败 订单支付失败

成功返回示例

支付成功

{
    "code": 0,
    "message": "success",
    "data": {
        "orderId": "ORDER20240315001",
        "tmId": "HZ1234567890",
        "amount": 100,
        "utr": "123456789012",
        "status": "SUCCESS"
    }
}

支付失败

{
    "code": 0,
    "message": "success",
    "data": {
        "orderId": "ORDER20240315001",
        "tmId": "HZ1234567890",
        "amount": 100,
        "utr": "",
        "status": "FAILED"
    }
}

处理中

{
    "code": 0,
    "message": "success",
    "data": {
        "orderId": "ORDER20240315001",
        "tmId": "HZ1234567890",
        "amount": 100,
        "utr": "",
        "status": "PENDING"
    }
}

错误返回示例

// 请求数据为空
{
    "code": 400,
    "message": "Empty data",
    "data": ""
}

// 订单号为空
{
    "code": 400,
    "message": "Empty orderId",
    "data": ""
}

// 订单号长度错误
{
    "code": 400,
    "message": "orderId length must between 6 and 32",
    "data": ""
}

// API Key 无效
{
    "code": 400,
    "message": "X-Api-Key Is Invalid",
    "data": ""
}

// API Key 未授权
{
    "code": 401,
    "message": "X-Api-Key Is unauthrized",
    "data": ""
}

// API Secret 未授权
{
    "code": 401,
    "message": "X-Api-Secret Is unauthrized",
    "data": ""
}

// 商户不存在
{
    "code": 404,
    "message": "Merchant Not Found",
    "data": ""
}

// IP 不在白名单中
{
    "code": 403,
    "message": "Ip not allowed-192.168.1.1",
    "data": ""
}

// 订单不存在
{
    "code": 404,
    "message": "Order Not Found",
    "data": ""
}

错误码说明

错误码 说明
0 请求成功
400 请求参数错误（数据为空、订单号格式错误等）
401 未授权（API Key 或 Secret 验证失败）
403 禁止访问（IP 不在白名单）
404 资源不存在（商户不存在、订单不存在）
500 服务器内部错误

注意事项

重要提示
  • 调用接口前请确保已在后台配置 IP 白名单
  • X-Api-Secret 需要进行 MD5 加密后与数据库中的 iv 字段对比
  • 建议在生产环境使用 HTTPS 协议
  • 接口会记录请求日志，包含请求 IP 和 API Key
  • 订单号 orderId 长度必须在 6-32 位之间
  • 只能查询当前商户自己创建的订单
  • UTR 字段仅在支付成功后才会有值

业务流程说明

  1. 验证请求参数是否完整
  2. 验证请求头中 X-Api-Key 和 X-Api-Secret
  3. 获取客户端真实 IP 地址
  4. 记录请求日志
  5. 验证订单号长度（6-32位）
  6. 根据 X-Api-Key 查询商户密钥信息
  7. 验证 X-Api-Secret（MD5 加密后对比）
  8. 查询商户信息并验证 IP 白名单
  9. 根据订单号查询订单信息
  10. 转换订单状态码为可读状态（PENDING/SUCCESS/FAILED）
  11. 返回订单详情

订单状态转换规则

数据库存储值 接口返回状态 说明
1 或其他 PENDING 订单处理中
2 SUCCESS 支付成功
3 FAILED 支付失败

使用建议

最佳实践
  • 建议在异步通知未能正常接收时，使用此接口主动查询订单状态
  • 可以设置定时任务轮询未支付订单的状态
  • 查询频率建议控制在合理范围内，避免频繁调用
  • 收到 SUCCESS 状态后，建议将订单标记为已完成，避免重复处理
  • 对于 PENDING 状态的订单，可以间隔一段时间后再次查询