签约与解约结果回调
更新时间:2025.01.07签约、解约成功后(不成功不通知),微信会把相关签约、解约信息异步通知给商户。
|
1. 接口说明
适用对象: 直连模式 机构模式
请求URL:签约结果通知路径为签约接口商户上传的success_notify_url字段,解约结果通知路径为商户申请代扣权限与代扣模板ID时提供的解约回调地址。必须为https协议。如果链接无法访问,商户将无法接收到微信通知。通知url必须为直接可访问的url,不能携带参数。示例:success_notify_url:“http://pay.weixin.qq.com/wxpay/pay.action”
请求方式:POST
2. 通知规则
签约、解约成功后(不成功不通知),微信会把相关签约、解约信息异步通知给商户。 商户需要接收处理,并返回应答。出于安全的考虑,我们对通知结果数据进行了加密,商户需要先对通知数据进行解密,才能得到结果数据。
对后台通知交互时,如果微信收到商户的应答不是成功或超时,微信认为通知失败,微信会通过一定的策略定期重新发起通知,尽可能提高通知的成功率,但微信不保证通知最终能成功。(通知频率为15/15/30/180/1800/1800/1800/1800/3600,单位:秒)
3. 通知报文
签约、解约结果通知是以POST方法访问商户设置的通知url,通知的数据以JSON格式通过请求主体(BODY)传输。通知的数据包括了加密的支付结果详情。
下面详细描述证书解密的流程
1、从商户平台上获取商户的密钥,记为“key”。
2、针对resource.algorithm中描述的算法(目前为AEAD_AES_256_GCM),取得对应的参数nonce和associated_data。
3、使用key、nonce和associated_data,对数据密文resource.ciphertext进行解密,得到JSON形式的资源对象
注意:AEAD_AES_256_GCM算法的接口细节,请参考rfc5116。微信支付使用的密钥key长度为32个字节,随机串nonce长度12个字节,associated_data长度小于16个字节并可能为空。
4. 请求参数
参数名 | 变量 | 类型[长度限制] | 必填 | 描述 | |||
---|---|---|---|---|---|---|---|
通知ID | id | string[1,32] | 是 | 通知的唯一ID | |||
通知创建时间 | create_time | string[1,64] | 是 | 通知创建的时间,格式为rfc3339格式,如2018-06-08T10:34:56+08:00 代表北京时间2018年06月08日10时34分56秒 | |||
通知类型 | event_type | string[1,32] | 是 | 通知的类型 | |||
通知数据类型 | resource_type | string[1,32] | 是 | 通知的资源数据类型,支付成功通知为encrypt-resource | |||
通知数据 | resource | object | 是 | 通知资源数据 | |||
|
5. 通知签名
加密不能保证通知请求来自微信。微信会对发送给商户的通知进行签名,并将签名值放在通知的HTTP头Wechatpay-Signature。商户应当验证签名,以确认请求来自微信,而不是其他的第三方。签名验证的算法请参考《微信支付API V3签名验证》。
签约与解约结果通知
商户对resource对象进行解密后,得到的资源对象示例
场景一:直连模式
场景二:服务商模式/机构模式
6. 签约与解约结果参数
参数名 | 变量 | 类型[长度限制] | 必填 | 描述 |
---|---|---|---|---|
商户号 | mchid | string[1,32] | 是 | 微信支付分配的商户号 |
APPID | appid | string[1,32] | 是 | 商户在微信开放平台申请移动应用对应的APPID |
机构商户号 | sp_mchid | string[1,32] | 是 | 微信支付分配的机构商户号 |
子商户号 | sub_mchid | string[1,32] | 是 | 微信支付分配的子商户商户号 |
机构APPID | sp_appid | string[1,32] | 是 | 机构在微信公众平台申请服务号对应的APPID |
子商户APPID | sub_appid | string[1,32] | 否 | 子商户在微信开放平台申请移动应用对应的APPID |
签约协议号 | out_contract_code | string[1,32] | 是 | 商户请求签约时传入的签约协议号,商户侧须唯一 |
委托代扣协议ID | contract_id | string[1,64] | 是 | 签约成功后,微信返回的委托代扣协议id |
模板ID | plan_id | int | 是 | 商户向微信支付申请代扣权限时,微信支付将会为商户分配一个唯一的代扣模板ID |
用户标识 | openid | string[1,128] | 是 | 用户在商户appid对应下的唯一标识,需要传appid才有返回 |
协议解约方式 | contract_termination_mode | string[1,64] | 否 | 解约方式 |
协议到期时间 | contract_expire_time | string[1,32] | 否 | 协议到期时间,遵循rfc3339标准格式,格式为YYYY-MM-DDTHH:mm:ss+TIMEZONE,YYYY-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。 |
操作时间 | operate_time | string[1,32] | 是 | 操作时间,遵循rfc3339标准格式,格式为YYYY-MM-DDTHH:mm:ss+TIMEZONE,YYYY-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。 |
7. 通知应答
接收成功:HTTP应答状态码需返回200或204,无需返回应答报文。
接收失败:HTTP应答状态码需返回5XX或4XX,同时需返回应答报文,格式如下:
注意:重试过多会导致微信支付端积压过多通知而堵塞,影响其他正常通知。
参数名 | 变量 | 类型 | 必填 | 描述 |
---|---|---|---|---|
返回状态码 | code | string[1,32] | 是 | 详见下面返回状态码说明 |
返回信息 | message | string[1,256] | 否 | 返回信息,为错误原因 |
场景一:成功示例
场景二:失败示例