发起还款

更新时间:2025.12.05
||

商户在发起还款之前,需要先调用预约还款接口;只有成功预约还款之后才能发起还款

接口说明

支持商户:【普通服务商】

请求方式:【POST】/v3/credit-repayment/partner/deduct-orders

请求域名:【主域名】https://api.mch.weixin.qq.com 使用该域名将访问就近的接入点

     【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点 ,指引点击查看

请求参数

Header  HTTP头参数

 Authorization  必填 string

请参考签名认证生成认证信息


 Accept  必填 string

请设置为application/json


 Content-Type  必填 string

请设置为application/json


body  包体参数

 contract_id  必填   string(64)

【还款协议ID】 商户与用户签约成功后得到的还款协议ID


 out_trade_no  必填   string(32)

【商户侧交易单号】 商户系统的交易单号,只能是数字、大小写字母。需要保证在同一个商户号下唯一


 out_record_id  必填   string(32)

【商户侧预约还款记录ID】 预约还款成功的商户侧预约还款记录ID


 deduct_amount  必填   string

【还款金额】 单位:分。如果是预约还款后首次发起还款,则还款金额必须等于预约还款时的应还款金额;如果不是,则还款金额必须在以下区间内:[预约还款时的最低还款金额,min(预约还款时的应还款金额 * (1 + 0.05% * 天数),还款协议中设置的还款金额上限)]


 notify_url  必填   string(1024)

【商户回调地址】 商户接收还款结果通知的地址,需按照notify_url填写注意事项规范填写。


 description  必填   string(127)

【产品描述】 对产品信息的描述。服务商需传递能真实代表产品信息的描述


 attach  选填   string(128)

【商户数据包】 服务商可传入自定义数据包,该数据对用户不可见,用于存储订单相关的服务商自定义信息。查询API和支付通知中原样返回

请求示例

curl
Java
Go

POST

1curl -X POST \
2  https://api.mch.weixin.qq.com/v3/credit-repayment/partner/deduct-orders \
3  -H "Authorization: WECHATPAY2-SHA256-RSA2048 mchid=\"1900000001\",..." \
4  -H "Accept: application/json" \
5  -H "Content-Type: application/json" \
6  -d '{
7    "contract_id" : "20251105000000123456789",
8    "out_trade_no" : "1217752501201407033233368018",
9    "out_record_id" : "1234567abcde",
10    "deduct_amount" : "10000",
11    "notify_url" : "https://www.test.com",
12    "description" : "信贷还款",
13    "attach" : "备注信息"
14  }'
15

应答参数

200 OK

 out_trade_no  必填   string(32)

【商户侧交易单号】 发起还款时商户传入的商户侧交易单号


 out_record_id  选填   string(32)

【商户侧预约还款记录ID】 预约还款成功的商户侧预约还款记录ID


 appid  必填   string(32)

【商户AppID】 商户在微信申请的公众号或移动应用AppID,与服务商商户号绑定。可参考服务商模式开发必要参数说明


 sub_appid  选填   string(32)

【子商户AppID】 与子商户号绑定的AppID。可参考服务商模式开发必要参数说明


 openid  必填   string(128)

【用户标识】 用户在商户AppID下的唯一标识


 contract_id  必填   string(64)

【还款协议ID】 商户与用户签约的还款协议ID


 order_state  必填   string

【还款单状态】 还款单的状态

可选取值

  • DEDUCT_ORDER_STATE_PENDING:  待处理

  • DEDUCT_ORDER_STATE_NOT_PAY:  待处理还款

  • DEDUCT_ORDER_STATE_PAY_SUCCESS:  还款成功

  • DEDUCT_ORDER_STATE_PAY_FAIL:  还款失败


 deduct_amount  必填   string

【还款金额】 单位分


 pay_success_amount  选填   string

【实际还款金额】 单位分;只有还款成功才会返回


 description  必填   string(127)

【产品描述】 对产品信息的描述。服务商需传递能真实代表产品信息的描述


 attach  选填   string(128)

【商户数据包】 服务商可传入自定义数据包,该数据对用户不可见,用于存储订单相关的服务商自定义信息。查询API和支付通知中原样返回


 transaction_id  选填   string(32)

【微信支付的支付单号】 只有还款成功才返回

应答示例

200 OK

1{
2  "out_trade_no" : "1217752501201407033233368018",
3  "out_record_id" : "123456abcde",
4  "appid" : "wxcbda96de0b165486",
5  "sub_appid" : "wxcbda96de0b165489",
6  "openid" : "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
7  "contract_id" : "20251105000000123456789",
8  "order_state" : "DEDUCT_ORDER_STATE_PENDING",
9  "deduct_amount" : "10000",
10  "pay_success_amount" : "10000",
11  "description" : "信贷还款",
12  "attach" : "备注",
13  "transaction_id" : "1009660380201506130728806387"
14}
15

 

错误码

以下是本接口返回的错误码列表。详细错误码规则,请参考微信支付接口规则-错误码和错误提示

状态码

错误码

描述

解决方案

400

PARAM_ERROR

参数错误

请根据错误提示正确传入参数

400

INVALID_REQUEST

HTTP 请求不符合微信支付 APIv3 接口规则

请参阅 接口规则

401

SIGN_ERROR

验证不通过

请参阅 签名常见问题

500

SYSTEM_ERROR

系统异常,请稍后重试

请稍后重试

403

NO_AUTH

商户没有该业务的相关权限

确认服务商是否已开通产品权限

429

RATELIMIT_EXCEEDED

请求超过接口频率限制

降低频率,稍后重试

400

ALREADY_EXISTS

还款单已经存在

请确认请求中的商户侧交易单号是否正确

 

元宝AI
反馈
目录
置顶