token支付接口

token支付接口 `POST /v1/wallet/deduct/pay`

用途：根据 contractNo 查询绑卡列表并调用协议支付扣款；同步返回扣款结果；成功/失败均推送 DEDUCT_SUCCESS / DEDUCT_FAIL 异步通知。

扣款策略

场景	行为
未传 `agreementNo`	按 `bindOrder` 升序依次扣款，首个成功即停止；某一协议失败则尝试下一个，直至成功或全部失败
传入 `agreementNo`	仅对该协议扣款一次（不切换其他卡）；不存在或不匹配则失败

agreementNo 来自 绑卡列表查询 agreements/query。

Body 字段说明

字段	类型	必填	说明
`merchantId`	string	条件	商户直连必填；统一会员可省略
`deductRequestNo`	string	是	扣款请求号；幂等键：`merchantId + deductRequestNo`
`contractNo`	string	是	钱包账户签约号
`agreementNo`	string	否	指定扣款协议绑定号
`terminalId`	string	条件	商户直连必填；统一会员可省略
`amount`	long	是	扣款金额，单位：分
`goods_info`	string	是	商品/消费信息说明（描述本笔扣款对应的商品或消费场景，最大 256 字符）
`currency`	string	否	币种，默认 `CNY`
`bizType`	string	否	业务类型（预留）
`notifyUrl`	string	否	扣款终态异步通知地址
`ext`	string	否	扩展 JSON 字符串

响应体字段说明（resBody / body）

字段	类型	说明
`deductOrderNo`	string	扣款订单号；查单、通知幂等使用
`deductRequestNo`	string	扣款请求号（与请求一致）
`deductStatus`	string	`SUCCESS` / `FAIL` / `PROCESSING`
`successAgreementNo`	string	扣款成功的协议绑定号；仅 `SUCCESS`
`amount`	long	扣款金额（分）；仅 `SUCCESS`
`successAt`	string	扣款成功时间，`yyyyMMddHHmmss`；仅 `SUCCESS`
`failCode`	string	失败错误码；仅支付结果查询终态 `FAIL`/`PROCESSING`；同步扣款抛异常时不返回（已合并进网关 `message`）
`failReason`	string	失败原因；语义同 `failCode`
`idempotentHint`	string	重复请求提示；仅幂等命中时（如「订单已支付成功，请勿重复支付」）

同步扣款失败/处理中时，网关 message 格式为 [failCode] 描述，resBody 保留 deductOrderNo、deductStatus 等，不含 failCode/failReason。
实际 JSON 中还可能包含 attemptCount、latestDeductPayFlowNo 等内部流水字段，可忽略。

成功响应示例

{
  "deductOrderNo": "4101010120250525120000000001",
  "deductRequestNo": "DED202505250001",
  "deductStatus": "SUCCESS",
  "successAgreementNo": "AGR20250525000001",
  "amount": 1990,
  "successAt": "20260525151001"
}

失败响应示例（多卡轮询后全部失败，同步抛异常）

网关/SDK：code=TRADE_ERROR，message=[BF00127] 不支持该支付通道的交易

resBody / body：

{
  "deductOrderNo": "4101010120250525120000000001",
  "deductRequestNo": "DED202505250001",
  "deductStatus": "FAIL"
}

失败响应示例（指定 agreementNo 扣款失败）

网关/SDK：code=TRADE_ERROR，message=[BF00135] 交易金额不正确（无渠道文案时为 [WF_005004] 指定协议号扣款失败）

resBody / body：

{
  "deductOrderNo": "4101010120250525120000000002",
  "deductRequestNo": "DED202505250002",
  "deductStatus": "FAIL"
}

处理中响应示例（code=USER_PAYING 由网关/SDK 返回）

{
  "deductOrderNo": "4101010120250525120000000001",
  "deductRequestNo": "DED202505250001",
  "deductStatus": "PROCESSING"
}

渠道返回处理中时，主单为 PROCESSING；网关/SDK 返回 code=USER_PAYING，resBody 内返回当前进度。
系统会异步推进终态并发送异步通知；商户应轮询扣款结果查询**（建议间隔 3~~5 秒，最长 1~~2 分钟）。

防重复扣款（必须遵守）

同一 merchantId + deductRequestNo 的重复请求不得再次触发扣款。
重复请求应直接返回已有 deductOrderNo 及终态 deductStatus（或 PROCESSING），并附带提示：
- 已成功：message / idempotentHint = 「订单已支付成功，请勿重复支付」
- 处理中：code=ORDER_DUPLICATED，message = 「扣款处理中，请勿重复提交」
禁止通过更换 deductRequestNo 对同一笔业务重复扣款。

常见失败 code

code	说明
`INVALID_PARAMETER`	必填参数缺失、`contractNo` 无效
`TRADE_ERROR`	无可用协议、指定 `agreementNo` 不匹配、全部扣款失败等
`ORDER_DUPLICATED`	重复扣款请求
`USER_PAYING`	扣款处理中

token支付接口

token支付接口 POST /v1/wallet/deduct/pay

防重复扣款（必须遵守）

token支付接口 `POST /v1/wallet/deduct/pay`