预扣费通知API

更新时间：2024.12.31

商户进行委托代扣扣费前需要在可通知时间段内调用「预扣费通知」的接口为用户发送扣费提醒，并设定预计扣费金额，经过扣费等待期后，在可扣费期内可发起扣费，扣款金额不能高于预计扣费金额，扣费失败可主动发起重试扣费（重试次数由其他规则限制），直到扣费成功，或者可扣费期结束。

注意：

一个扣费周期内只能扣款成功一次，即无论可扣费期是否结束，只要周期内扣款成功一次，该扣费周期则结束。

能力说明

扣费等待期：商户调用「预扣费通知」接口成功当日及第二个自然日。
扣费持续天数：默认为7天；在扣费等待期后，能够进行扣款的自然日天数；发完通知后，商家可在第3-9天发起扣款。
可扣费期：经过扣费等待期后的N个自然日，N为扣费持续天数。
扣费周期：商户调用「预扣费通知」接口成功后，到扣款成功或可扣费日期结束。
可通知时间段：为了不打扰用户，商户只能在北京时间每天 7:00～22:00调用「预扣费通知」

扣费规则

假如扣费持续天数为1，通知下发当天为“扣费等待期”，商户不允许扣费；
第二天为“扣费等待期”，商户不允许扣费；
第三天为“可扣费期”，在可扣费期内可以发起扣费。
如：若需要在3号扣费，则需要在1号将通知下发给用户，2号为用户的扣费等待期，用户可以选择等待扣费或关闭扣费服务，3号商户可正常发起扣费。

接口说明

适用对象：服务商

请求URL： https://api.mch.weixin.qq.com/v3/partner-papay/contracts/{contract_id}/notify

请求方式： POST

数据格式： JSON

接口规则：V3接口规则概述

接口请求方：具有委托代扣扣费权限，且另行开通了预扣费通知权限的服务商商户

path指该参数为路径参数

query指该参数需在请求URL传参

body指该参数需在请求JSON传参

请求参数

参数名

变量

类型[长度限制]

必填

描述

委托代扣协议id

contract_id

string[1,32]

是

path 签约成功后，微信返回的委托代扣协议id。
示例值：123124412412423431

服务商商户号

sp_mchid

string[1,32]

是

body 填写微信支付分配的服务商商户号。
示例值：1230000109

服务商应用ID

sp_appid

string[1,32]

是

body 服务商申请的公众号或移动应用appid。
示例值：wxd678efh567hg6787

子商户号

sub_mchid

string[1,32]

是

body 填写微信支付分配的子商户号。
示例值：12345512

子商户应用D

sub_appid

string[1,32]

否

body 子商户的APPID。
示例值：wxd678efh567hg6787

扣费持续时间

deduct_duration

object

否

body 在扣费等待期后，能够进行扣款的时间。注：扣费等待期是指商户调用本接口成功当日及第二个自然日。

扣费持续时间

预计扣费金额信息

estimated_amount

object

是

body 预计扣款的金额信息。

预计扣费金额信息

请求示例：

JSON

1{
2  "sp_appid" : "wxd678efh567hg6787",
3  "sp_mchid" : "1230000109",
4  "deduct_duration" : {
5      "count" : 1,
6      "unit" : "DAY"
7    },
8  "estimated_amount" : {
9    "amount" : 1,
10    "currency" : "CNY"
11  },
12  "sub_mchid" : "12345512",
13  "sub_appid" : "wxd678efh567hg6787"
14}

返回参数

无参数返回

返回示例：

正常示例

1
2无数据（Http状态码为204）
3

错误码

公共错误码

错误码	描述	解决方案
SYSTEMERROR	接口返回错误	系统异常，请使用相同参数重新调用接口
CONTRACT_NOT_EXIST	签约协议不存在	请检查签约协议号是否正确,是否已解约
PARAM_ERROR	参数错误	请根据接口返回的详细信息检查您的程序
APPID_MCHID_NOT_MATCH	appid和mchid不匹配	请确认appid和mchid是否匹配
INVALID_REQUEST	无效请求	请根据接口返回的详细信息检查您的程序
RULELIMIT	该请求存在风险	请检查当前预计扣费金额，已扣款次数，确认请求是否存在风险。
RESOURCE_ALREADY_EXISTS	资源已经存在	已经成功发送通知，无需重复调用。

文档是否有帮助

更多支持

开发文档(商户)开发文档(V2版)开发者社区微信开放平台微信公众平台腾讯客服