按签约号扣款

建议超时 15000ms。幂等键：商户号 + out_trade_no。按 contract_no 查询可用协议并扣款；可同步返回结果，并在配置 notify_url 时推送异步通知。

接口说明

请求方式：【POST】/v1/wallet/deduct/pay

请求域名：【主域名】https://api.baofu.com

请求参数

Header 参数

参数名	类型	必填	描述
Authorization	string	true	请参考【开发指引-整体说明】生成认证信息
Accept	string	true	请设置为 `application/json`
Content-Type	string	true	请设置为 `application/json`

Body 参数

参数名	类型	必填	描述
out_trade_no	string	true	商户订单号；最长 64
contract_no	string	true	签约号；最长 32
agreement_no	string	false	指定扣款协议；未传则按顺序尝试；最长 64
payment_amount	integer	true	扣款金额；>0；单位分
goods_info	string	true	商品/消费信息说明；最长 256
biz_type	string	false	业务类型（预留）；最长 32
notify_url	string	false	扣款终态异步通知地址；最长 256
risk_control_info	object	true	风控参数 JSON 对象
risk_control_info.goods_category	string	false	商品类目
risk_control_info.user_register_dt	string	false	用户注册时间
risk_control_info.user_login_method	string	false	用户登录方式
risk_control_info.user_ip	string	false	用户 IP
risk_control_info.user_device_id	string	false	用户设备 ID

请求示例

{
  "out_trade_no": "DED202505250001",
  "contract_no": "C20250525000001",
  "payment_amount": 1990,
  "goods_info": "会员月卡",
  "notify_url": "https://merchant.example.com/callback/wallet/deduct",
  "risk_control_info": {
    "goods_category": "02",
    "user_register_dt": "20220101000000",
    "user_login_method": "1",
    "user_ip": "192.168.1.1",
    "user_device_id": "device_001"
  }
}

应答参数

200 OK

参数名	类型	必填	描述
trade_no	string	true	平台交易号
out_trade_no	string	true	商户订单号
trade_status	string	true	成功时固定 SUCCESS
success_agreement_no	string	true	扣款成功的协议绑定号
payment_amount	integer	true	扣款金额（分）
successful_payment_time	string	true	扣款成功时间，ISO 8601
bank_code	string	false	银行编码
bank_card_type	string	false	卡类型，如 D/C
bank_card_no_masked	string	false	脱敏卡号，如 ****5661

应答示例

200 OK

{
  "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"
}

错误码

公共错误码

状态码	错误码	描述	解决方案
401	SIGN_ERROR	验证不通过	请参阅【开发指引-整体说明】排查签名
400	PARAM_ERROR	参数错误	请根据错误提示正确传入参数
500	SYSTEM_ERROR	系统异常，请稍后重试	请稍后重试

业务错误码

状态码	错误码	描述	解决方案
非 200	USER_PAYING	处理中	轮询扣款查询或等通知；勿用相同 out_trade_no 重试
非 200	TRADE_ERROR	无可用协议；协议不匹配；全部失败	读 message；查协议列表；失败须换单
非 200	ORDER_DUPLICATED	幂等命中处理中/历史失败	查扣款结果；失败换单
非 200	INVALID_PARAMETER	参数错误；risk_control_info 为空	修正参数
非 200	UPSTREAM_TIMEOUT	上游异常	查扣款结果确认是否已受理

应答示例

失败

{
  "code": "TRADE_ERROR",
  "message": "协议号全部扣款失败"
}

应答示例

失败

{
  "code": "USER_PAYING",
  "message": "扣款处理中，请勿重复提交"
}

应答示例

失败

{
  "code": "ORDER_DUPLICATED",
  "message": "交易失败"
}

应答示例

失败

{
  "code": "INVALID_PARAMETER",
  "message": "交易失败"
}

应答示例

失败

{
  "code": "UPSTREAM_TIMEOUT",
  "message": "交易失败"
}

应答示例

失败

{
  "code": "SYSTEM_ERROR",
  "message": "交易失败"
}