基本定义

  • 方法：POST
  • 路径：/v1/wallet/deduct/query
  • Content-Type：application/json
  • Auth：统一网关
  • Timeout：5000ms（建议）
  • 查询键：out_trade_no 或 trade_no（至少传一个）
  • 描述：查询扣款结果

请求字段

字段 类型 必填 约束 说明
out_trade_no string 条件 与 trade_no 二选一 商户订单号
trade_no string 条件 与 out_trade_no 二选一 平台交易号

请求示例：

{
  "out_trade_no": "DED202505250001"
}

响应字段（分支 A：成功 trade_status=SUCCESS）

字段 类型 必填 说明
trade_no string 是 平台交易号
out_trade_no string 是 商户订单号
trade_status string 是 固定 SUCCESS
success_agreement_no string 是 成功协议绑定号
payment_amount integer 是 扣款金额（分）
successful_payment_time string 是 成功时间
bank_code string 否 扣款成功卡银行编码
bank_card_type string 否 扣款成功卡类型，如 D/C
bank_card_no_masked string 否 扣款成功卡脱敏卡号，格式如 ****5661

响应示例：

{
  "trade_no": "4101010120250525120000000001",
  "out_trade_no": "DED202505250001",
  "trade_status": "SUCCESS",
  "success_agreement_no": "AGR20250525000001",
  "payment_amount": 1990,
  "successful_payment_time": "2026-05-25T15:10:01+08:00",
  "bank_code": "ICBC",
  "bank_card_type": "D",
  "bank_card_no_masked": "****5661"
}

响应字段（分支 B：失败 trade_status=FAIL）

HTTP 200（查单接口不对终态失败抛业务错误码）。

字段 类型 必填 说明
trade_no string 是 平台交易号
out_trade_no string 是 商户订单号
trade_status string 是 固定 FAIL

响应示例：

{
  "trade_no": "4101010120250525120000000001",
  "out_trade_no": "DED202505250001",
  "trade_status": "FAIL"
}

响应字段（分支 C：处理中 trade_status=PROCESSING）

HTTP 200。

字段 类型 必填 说明
trade_no string 是 平台交易号
out_trade_no string 是 商户订单号
trade_status string 是 固定 PROCESSING

响应示例：

{
  "trade_no": "4101010120250525120000000001",
  "out_trade_no": "DED202505250001",
  "trade_status": "PROCESSING"
}

错误与调用方处理

HTTP 网关 code 触发条件 调用方处理 可重试
200 — trade_status 为 SUCCESS / FAIL / PROCESSING 按 trade_status 分支处理；失败原因以 HTTP-007 同步应答或 NOTIFY-002 为准 视状态
非 200 NOT_FOUND 扣款单不存在 核查 out_trade_no / trade_no 与商户号 否
非 200 INVALID_PARAMETER 查询键均未传；Header 缺失 至少传一个查询键 是
非 200 SYSTEM_ERROR 系统异常 稍后重试 是

与 HTTP-003 不同：HTTP-008 仅在单不存在时返回错误；FAIL / PROCESSING 均为 HTTP 200 + trade_status，不返回 USER_PAYING / TRADE_ERROR 网关码。