代付查询接口

概述

代付查询接口用于查询代付订单的状态和详情信息。商户可以通过此接口获取订单的实时状态、支付结果等详细信息。

接口信息

• 接口地址：POST /api/ec/payout-query
• 请求方式：POST
• Content-Type：application/json

请求头

所有 API 请求都需要在请求头中包含以下参数，详见 API签名规范：

参数名	类型	必选	说明
Content-Type	string	Y	application/json，固定值
MerchantId	string	Y	商户 ID，由 Veloraya 提供
Timestamp	string	Y	当前时间戳（毫秒），防止重放攻击
Nonce	string	Y	随机字符串，防重放攻击，每次请求唯一
Signature	string	Y	请求签名（RSA签名），Base64编码

请求参数

参数名	类型	必选	说明
merchantOrderId	string	N	商户订单号（与 orderId 二选一，必填其一）
orderId	string	N	平台订单号（与 merchantOrderId 二选一，必填其一）

请求示例

{
  "merchantOrderId": "ORDER20231201001"
}

响应格式

所有接口的响应都采用统一的 JSON 格式，包含以下字段：

参数名	类型	说明
code	int	响应码，200 表示成功，非 200 表示失败
msg	string	响应消息
data	object	响应数据，成功时包含订单信息

响应参数（data 字段）

参数名	类型	说明
orderId	string	平台订单号
merchantOrderId	string	商户订单号
amount	BigDecimal	订单金额
fee	BigDecimal	手续费
currency	string	货币代码
completeDatetime	string	订单完成时间，格式：yyyy-MM-dd HH:mm:ss，未完成时为空字符串
orderStatus	string	订单状态，见订单状态枚举
resultCode	string	错误码（错误时有值）
resultDesc	string	错误结果描述（错误时有值）

订单状态枚举

值	说明
PENDING	支付中
SUCCESS	支付成功
FAILED	支付失败

响应示例

查询成功

{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "orderId": "PAYIN1991084006458683392",
    "merchantOrderId": "ORDER20231201001",
    "amount": 100,
    "fee": 0,
    "currency": "USD",
    "completeDatetime": "2024-01-01 10:05:00",
    "orderStatus": "SUCCESS"
  }
}

注意事项

• 请求头：必须在请求头中传入所有必需的参数（Content-Type、MerchantId、Timestamp、Nonce、Signature），详见 API签名规范
• 签名验证：所有请求必须包含正确的签名（通过网关过滤器验证）
• 查询权限：只能查询本商户的订单，系统会根据 merchantId 进行权限校验
• 日志记录：建议记录查询日志用于审计
• 错误处理：妥善处理各种错误情况（订单不存在、参数错误等）