普通服务商委托代扣签解约通知API

更新时间:2024.01.24

微信支付通过签解约通知接口将协议签解约结果通知给商户。

注意

对后台通知交互时,如果微信收到应答不是成功或超时,微信认为通知失败,微信会通过一定的策略定期重新发起通知,尽可能提高通知的成功率,但微信不保证通知最终能成功。

  • 同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。推荐的做法是,当商户系统收到通知进行处理时,首先检查对应业务数据的状态,判断该通知是否已经处理过,如果没有处理过再进行处理,如果处理过直接返回结果成功。在对业务数据进行状态检查和处理之前,要采用数据锁进行并发控制,以避免函数重入造成的数据混乱。
  • 如果在所有通知频率(4小时)后没有收到微信侧回调,商户应调用查询签约接口确认签约状态。

特别提醒: 商户系统对于开启结果通知的内容一定要做签名验证,并校验通知的信息是否与商户侧的信息一致,防止数据泄露导致出现“假通知”,造成资金损失。

# 接口说明

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

请求方式: 【POST】

回调URL: 签约结果通知路径是通过【普通服务商预约扣费类型签约的预签约API】提交"contract_notify_URL"参数设置的回调地址,解约结果通知路径为商户配置委托扣款模版时填写的解约回调地址。回调地址必须为HTTPS协议。如果回调地址无法访问,商户将无法接收到微信通知。 回调地址必须为直接可访问的URL,不能携带参数。示例:"https://pay.weixin.qq.com/wxpay/pay.action"

接口规则: https://wechatpay-api.gitbook.io/wechatpay-api-v3

# 通知规则

签约、解约成功后,微信会把相关签约信息或者解约信息发送给商户,商户需要接收处理该消息,并按照文档规范返回应答。出于安全的考虑,我们对签约、解约数据进行了加密,商户需要先对通知数据进行解密,才能得到签约、解约结果数据。

对后台通知交互时,如果微信收到商户的应答不符合规范或超时,微信认为通知失败,微信会通过一定的策略定期重新发起通知,尽可能提高通知的成功率,但微信不保证通知最终能成功。(通知频率为:0/10/10/10/30/30/30/300/300/300/300/300/300/300/300/300/300/300/300/300/300/300/300/300/300/300/300/300/300/300(单位:秒))

# 通知报文

结果通知是以POST方法访问商户设置的通知URL,通知的数据以JSON格式通过请求主体(BODY)传输。通知的数据包括了加密结果详情。

# 参数解密

下面详细描述对通知数据进行解密的流程:

  1. 用商户平台上设置的APIv3密钥【微信商户平台—>账户设置—>API安全—>设置APIv3密钥】,记为key。
  2. 针对resource.algorithm中描述的算法(目前为AEAD_AES_256_GCM),取得对应的参数nonce和associated_data。
  3. 使用key、nonce和associated_data,对数据密文resource.ciphertext进行解密,得到JSON形式的资源对象。

注意

  1. AEAD_AES_256_GCM算法的接口细节,请参考rfc5116。微信支付使用的密钥key长度为32个字节,随机串nonce长度12个字节,associated_data长度小于16个字节并可能为空。
  2. Java回调解密Json取值不带引号

# 字段说明

# 通知参数

    Body 包体参数
  • id 必填 string(36)
    通知的唯一ID。
  • create_time 必填 string(32)
    通知创建的时间,遵循rfc3339标准格式,格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE,yyyy-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35+08:00表示,北京时间2015年5月20日13点29分35秒。
  • event_type 必填 string(32)
    通知类型,枚举值:
    ENTRUST.SIGN:签约完成
    ENTRUST.TERMINATE: 解约完成
  • resource_type 必填 string(32)
    通知的资源数据类型,为encrypt-resource。
  • summary 必填 string(64)
    回调摘要
  • resource 必填 object
    通知资源数据。 json格式,见示例
    • 属性

# 签约成功通知结果

1{
2 "id":"EV-2018022511223320873",
3 "create_time":"2020-06-08T10:34:56+08:00",
4 "resource_type":"encrypt-resource",
5 "event_type":"ENTRUST.SIGN",
6 "summary": "委托代扣签约通知",
7 "resource" : {
8 "original_type":"entrust",
9 "algorithm":"AEAD_AES_256_GCM",
10 "ciphertext": "...",
11 "nonce": "...",
12 "associated_data": ""
13 }
14}

# 解约成功通知结果

1{
2 "id":"EV-2018022511223320873",
3 "create_time":"2020-06-08T10:34:56+08:00",
4 "resource_type":"encrypt-resource",
5 "event_type":"ENTRUST.TERMINATE",
6 "summary": "委托代扣解约通知",
7 "resource" : {
8 "original_type":"entrust",
9 "algorithm":"AEAD_AES_256_GCM",
10 "ciphertext": "...",
11 "nonce": "...",
12 "associated_data": ""
13 }
14}

# 通知签名

加密不能保证通知请求来自微信。微信会对发送给商户的通知进行签名,并将签名值放在通知的HTTP头Wechatpay-Signature。商户应当验证签名,以确认请求来自微信,而不是其他的第三方。签名验证的算法请参考 《微信支付API v3签名验证》

# 签约、解约通知参数

    Body 包体参数
  • contract_id 必填 string(32)
    委托代扣协议的主键,唯一定义此资源的标识
  • sp_mchid 必填 string(32)
    普通服务商商户号,微信支付分配的商户号
  • sp_appid 必填 string(32)
    商户在微信申请的公众号或移动应用AppID
  • sub_mchid 必填 string(32)
    子商户号,微信支付分配的商户号
  • sub_appid 必填 string(32)
    子商户的AppID,商户在微信申请的公众号或移动应用AppID
  • plan_id 必填 int
    委托代扣协议模板ID
  • out_contract_code 必填 string(32)
    商户侧的签约协议号,商户侧需保证唯一性。只能是数字、大小写字母的组合
  • contract_display_account 必填 string(64)
    签约用户的名称,用于页面展示,在签约时由商户传入。
  • contract_state 必填 string
    委托代扣协议状态,枚举值:
    SIGNED:已签约(签约生效中。)
    TERMINATED:已解约(生效的签约协议已被解约。)
  • contract_signed_time 必填 string(32)
    协议签署时间,按照使用rfc3339所定义的格式,格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE,yyyy-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35+08:00表示,北京时间2015年5月20日 13点29分35秒示例值:2020-09-10T13:29:35+08:00
  • contract_expired_time 必填 string(32)
    协议到期时间,按照使用rfc3339所定义的格式,格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE,yyyy-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35+08:00表示,北京时间2015年5月20日 13点29分35秒示例值:2020-09-10T13:29:35+08:00
  • sp_openid 必填 string(64)
    商户AppID下的用户唯一标识
  • sub_openid 必填 string(64)
    子商户AppID对应的用户OpenID,商户AppID下的用户唯一标识
  • contract_terminate_info 选填 object
    协议解约信息,仅当contract_state=TERMINATED时,该值有效。
    • 属性
  • deduct_schedule 选填 object
    预约扣费场景的预约信息,仅当模板类型为预约扣费时,该值有效。
    • 属性

# 商户对resource对象进行解密后,得到的资源对象示例

1{
2 "contract_display_account": "微信代扣用户A",
3 "contract_expired_time": "2021-09-10T13:29:35+08:00",
4 "contract_id": "123124412412423431",
5 "contract_signed_time": "2020-09-10T13:29:35+08:00",
6 "contract_state": "SIGNED",
7 "deduct_schedule": {
8 "deduct_amount": {
9 "currency": "CNY",
10 "total": 1
11 },
12 "deduct_date": "2019-11-22",
13 "estimated_deduct_amount": {
14 "currency": "CNY",
15 "total": 1
16 },
17 "estimated_deduct_date": "2019-11-22",
18 "schedule_state": "PAID",
19 "scheduled_amount": {
20 "currency": "CNY",
21 "total": 1
22 }
23 },
24 "out_contract_code": "wxwtdk20200910100000",
25 "out_user_code": "用户A",
26 "plan_id": 12535,
27 "sp_appid": "wxd678efh567hg6787",
28 "sp_mchid": "1900000109",
29 "sp_openid": "o-MYE42l80oelYMDE34nYD456Xoy",
30 "sub_appid": "wxd678efh567hg6787",
31 "sub_mchid": "1900000109",
32 "sub_openid": "o-MYE42l80oelYMDE34nYD456Xoy"
33}

# 通知应答

接收成功: HTTP应答状态码需返回200或204,无需返回应答报文。

接收失败: HTTP应答状态码需返回5XX或4XX,同时需返回应答报文,格式如下:

    Body 包体参数
  • code 必填 string(32)
    错误码,SUCCESS为接收成功,其他错误码为失败。
  • message 必填 string(64)
    返回信息,如非空,为错误原因。

# 应答示例

1{
2 "code": "SUCCESS",
3 "message": "成功"
4}