普通服务商预约扣费API

更新时间:2024.11.18

接口说明

商户在进行委托代扣费前,需要提前在微信支付系统中预约扣费,预约成功后方可在约定时间内扣费。

规则说明

  • 预约扣费规则:商户调用「受理扣款」接口进行委托代扣扣费前,需要指定委托代扣协议和扣费金额,扣费金额需要等于该周期指定的预计扣费金额,在可预约日可预约时间段内调用「预约扣费」接口,系统将会在调用成功后的30分钟内,为用户发送预扣费通知,并返回可扣费日期。该协议不能再次调用「预约扣费」接口进行预约。调用「预约扣费」接口成功后,商户可遵循下述扣费规则进行扣费。

  • 扣费规则:在可扣费期内,商户可调用「受理扣款」接口发起扣费,扣费金额必须等于预约扣费时传入的扣费金额。扣费失败可再次调用「受理扣款」接口发起重试扣费(重试次数由其他规则限制),直到扣费成功或者可扣费期结束。若可扣费期结束时仍未扣费成功,则系统会在第二天的8点进行解约。


可预约日:商户在跟用户签订委托代扣协议时指定预计扣费日期的前1个自然日当天。


可预约时间段:为了不打扰用户,商户只能在北京时间每天 [8:00,19:30)内调用「预约扣费」接口。


可扣费期:商户预约成功后,预约接口返回的可扣费开始日期至可扣费结束日期之间为可扣费期。注:目前可扣费期固定为一个自然日,即可扣费开始日期等于可扣费结束日期。


预约扣费示例


假设商户跟用户签约时指定的预计扣费时间为2022-03-02,预计扣费金额为100元人民币


该协议可预约日为2022-03-01,商户可以在2022-03-01 [8:00,19:30) ,指定协议ID、预计扣费金额100元人民币(必须等于100元人民币),调用「预约扣费」接口进行预约,系统将会在调用成功后的30分钟内,为用户发送预扣费通知,并返回可扣费期的开始日期2022-03-02 及结束日期2022-03-02,商户可以在[2022-03-02 00:00,2022-03-02 24:00)内,调用「受理扣款」接口进行委托代扣扣费,直到扣费成功。扣费成功后,系统将立即进行解约,该协议不能再次调用「预约扣费」接口和「受理扣款」接口。
若在2022-03-02 24:00前,仍未扣费成功,系统会在2022-03-03的8点进行解约。

接口说明

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

请求方式:【POST】/v3/papay/pay/partner/schedules/contract-id/{contract_id}/schedule

请求域名:【主域名】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


path 路径参数

contract_id  必填 string(32)

【委托代扣协议ID】签约成功后,微信返回的委托代扣协议ID。


body 包体参数

sp_appid  必填 string(32)

【应用ID】商户在微信申请的公众号或移动应用AppID


sub_mchid  必填 string(32)

【子商户号商户号】微信支付分配的商户号


sub_appid  选填 string(32)

【子商户的AppID】AppID是商户在微信申请公众号或移动应用成功后分配的账号ID,登录平台为mp.weixin.qq.com或open.weixin.qq.com


schedule_amount  必填 object

【预约的金额信息】预约的金额信息

属性

请求示例

POST

1curl -X POST \
2  https://api.mch.weixin.qq.com/v3/papay/pay/partner/schedules/contract-id/123124412412423431/schedule \
3  -H "Authorization: WECHATPAY2-SHA256-RSA2048 mchid=\"1900000001\",..." \
4  -H "Accept: application/json" \
5  -H "Content-Type: application/json" \
6  -d '{
7    "sp_appid" : "wxd678efh567hg6787",
8    "sub_mchid" : "1900000109",
9    "sub_appid" : "wxd678efh567hg6787",
10    "schedule_amount" : {
11      "total" : 1,
12      "currency" : "CNY"
13    }
14  }'
15

应答参数

200 OK

schedule_state  必填 string

【扣费预约的状态】扣费预约的状态

可选取值:

  • NO_SCHEDULED: 未进行预约

  • SCHEDULED: 已预约成功,未发起扣费或已发起扣费但扣费失败。

  • PAID: 已发起扣费且扣费成功

  • EXPIRED: 超过预计扣费时间且没有扣费成功。此时商户无法再进行预约或扣费。


deduct_start_date  选填 string(32)

【可扣费开始日期】可扣费的开始日期,当状态为已预约或已扣费时有返回。遵循rfc3339标准格式,格式为yyyy-MM-DD,yyyy-MM-DD表示年月日,例如:2015-05-20表示,北京时间2015年5月20日。


deduct_end_date  选填 string(32)

【可扣费结束日期】可扣费结束日期,当状态为已预约或已扣费时有返回。遵循rfc3339标准格式,格式为yyyy-MM-DD,yyyy-MM-DD表示年月日,例如:2015-05-20表示,北京时间2015年5月20日。


scheduled_amount  选填 object

【已预约的扣费金额信息】已预约的扣费金额信息,当状态为已预约或已扣费时有返回。

属性

deduct_amount  选填 object

【实际扣费金额】实际扣费金额,当预约状态为已扣费时有返回

属性

deduct_date  选填 string(32)

【实际扣费的日期】实际扣费的日期,当预约状态为已扣费时有返回。遵循rfc3339标准格式,格式为yyyy-MM-DD,yyyy-MM-DD表示年月日,例如:2015-05-20表示,北京时间2015年5月20日。

应答示例

200 OK

1{
2  "schedule_state" : "NO_SCHEDULED",
3  "deduct_start_date" : "2019-11-22",
4  "deduct_end_date" : "2019-11-22",
5  "scheduled_amount" : {
6    "total" : 1,
7    "currency" : "CNY"
8  },
9  "deduct_amount" : {
10    "total" : 1,
11    "currency" : "CNY"
12  },
13  "deduct_date" : "2019-11-22"
14}
15

 

错误码

公共错误码

状态码

错误码

描述

解决方案

400

PARAM_ERROR

参数错误

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

400

INVALID_REQUEST

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

请参阅 接口规则

401

SIGN_ERROR

验证不通过

请参阅 签名常见问题

500

SYSTEM_ERROR

系统异常,请稍后重试

请稍后重试

业务错误码

状态码

错误码

描述

解决方案

400

INVALID_REQUEST

无效请求

请根据接口返回的详细信息检查您的程序

403

CONTRACT_NOT_EXIST

签约协议不存在

请检查签约协议号是否正确

403

NO_AUTH

商户暂无权限使用此功能

请开通商户号权限。请联系产品或商务申请

429

FREQUENCY_LIMITED

频率超限

请降低请求接口频率

500

SYSTEM_ERROR

接口返回错误

系统异常,请用相同参数重新调用

 

 

反馈
咨询
目录
置顶