领券事件回调通知API

最新更新时间:2020.11.12 版本说明


注意:

• 同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。 推荐的做法是,当商户系统收到通知进行处理时,先检查对应业务数据的状态,并判断该通知是否已经处理。如果未处理,则再进行处理;如果已处理,则直接返回结果成功。在对业务数据进行状态检查和处理之前,要采用数据锁进行并发控制,以避免函数重入造成的数据混乱。

• 如果在所有通知频率(60s/次 - 总计11次)后没有收到微信侧回调,商户应调用查询订单接口确认订单状态。


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

接口说明

适用对象:直连商户 服务商 渠道商

请求URL:该链接是通过【设置商家券事件通知地址API】提交notify_url参数设置,必须为https协议。如果链接无法访问,商户将无法接收到微信通知。 通知url必须为直接可访问的url,不能携带参数。示例:“https://pay.weixin.qq.com/wxpay/pay.action”

接口规则:https://pay.weixin.qq.com/wiki/doc/apiv3/wechatpay/wechatpay-1.shtml

通知规则

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

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

通知报文

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


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

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

注: 1、AEAD_AES_256_GCM算法的接口细节,请参考rfc5116。微信支付使用的密钥key长度为32个字节,随机串nonce长度12个字节,associated_data长度小于16个字节并可能为空。

        2、java回调解密json取值不带引号

通知参数

参数名 变量 类型[长度限制] 必填 描述
通知ID id string[1,32] 通知的唯一id。
示例值:8b33f79f-8869-5ae5-b41b-3c0b59f957d0
通知创建时间 create_time string[1,16] 通知创建的时间,遵循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秒。
示例值:2019-12-12T16:54:38+08:00
通知类型 event_type string[1,32] 券的回调通知类型,枚举值:
COUPON.SEND:领券
示例值:COUPON.SEND
通知数据类型 resource_type string[1,32] 通知的资源数据类型,券的回调通知为encrypt-resource。
示例值:encrypt-resource
回调摘要 summary string[1,64] 回调摘要
示例值:商家券领券通知
+通知数据 resource object 通知资源数据。
json格式,见示例
参数名 变量 类型[长度限制] 必填 描述
加密算法类型 algorithm string[1,32] 对开启结果数据进行加密的加密算法,目前只支持AEAD_AES_256_GCM。
示例值:AEAD_AES_256_GCM
数据密文 ciphertext string[1,1048576] Base64编码后的开启/停用结果数据密文。
附加数据 associated_data string[1,16] 附加数据
示例值:coupon
随机串 nonce string[1,16] 加密使用的随机串。
示例值:j9g1wAzF9Xn1
原始回调类型 original_type string[1,64] 原始回调类型,券的原始回调类型为coupon
示例值:coupon

通知签名

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

回调示例

领券成功通知结果


{ 
    "id":"8b33f79f-8869-5ae5-b41b-3c0b59f957d0",
    "create_time":"2019-12-12T16:54:38+08:00",
    "resource_type":"encrypt-resource",
    "event_type":"COUPON.SEND",
    "summary":"商家券领券通知",
    "resource":{
        "original_type":"coupon",
        "algorithm":"AEAD_AES_256_GCM",
        "ciphertext":"xxx",
        "associated_data":"coupon",
        "nonce":"j9g1wAzF9Xn1"
     } 
} 

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


{   
	"event_type":"EVENT_TYPE_BUSICOUPON_SEND",
	"coupon_code":"1227944959000000911017",
	"stock_id":"1286950000000039",
	"send_time":"2019-12-17T10:35:53+08:00",
	"openid":"odXnH1CJjeQoWTld48db-pnxs-Wg",
	"unionid":"oOuyajgxj0oVwjocSoQm6mp7PGKw",
	"send_channel":"BUSICOUPON_SEND_CHANNEL_PAYGIFT", 
	# 此处原来为BUSICOUPON_SEND_CHANNEL_MINIAPP
	"send_merchant":"98568888",
	"attach_info":"{
		\"transaction_id\":\"4200000462220200226114599\",\"act_code\":\"540358695\"}"
	 # attach_info只有在支付有礼渠道才会有,其他渠道没有
}

领券成功通知参数

参数名 变量 类型[长度限制] 必填 描述
事件类型 event_type string[1,32] 业务细分事件类型,枚举值:
EVENT_TYPE_BUSICOUPON_SEND:商家券用户领券通知
示例值:EVENT_TYPE_BUSICOUPON_SEND
券code coupon_code string[1,32] 券的唯一标识。
示例值:1227944959000000911017
批次号 stock_id string[1,32] 批次号
示例值:1286950000000039
发放时间 send_time string[1,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秒。
示例值:2015-05-20T13:29:35+08:00
用户标识 openid string[1,128] 微信用户在appid下的唯一标识。
示例值:odXnH1CJjeQ6666648db-pnxs-Wg
用户统一标识 unionid string[1,128] 微信用户在同一个微信开放平台账号下的唯一用户标识,unionid获取方式请参见《UnionID机制说明》文档。
示例值:oOuyajgxj0oVw888SoQm6mp7PGKw
发放渠道 send_channel string 发放渠道,枚举值:
BUSICOUPON_SEND_CHANNEL_MINIAPP:小程序
BUSICOUPON_SEND_CHANNEL_API:API
BUSICOUPON_SEND_CHANNEL_PAYGIFT:支付有礼
BUSICOUPON_SEND_CHANNEL_H5:H5
BUSICOUPON_SEND_CHANNEL_FTOF:面对面
BUSICOUPON_SEND_CHANNEL_MEMBERCARD_ACT:会员卡活动
BUSICOUPON_SEND_CHANNEL_HALL:扫码领券(营销馆)
示例值:BUSICOUPON_SEND_CHANNEL_MINIAPP
发券商户号 send_merchant string[1,16] 发券商户号
示例值:98568888
+ 发券附加信息 attach_info string 仅在支付有礼、扫码领券(营销馆)、会员有礼发放渠道,才有该信息
参数名 变量 类型[长度限制] 必填 描述
交易订单编号 transaction_id string[1,32] 仅在支付有礼渠道,才有该信息,对应支付有礼曝光支付订单编号信息 
示例值:4200000462220200226114599
支付有礼活动编号 act_code string[1,32] 二选一 仅在支付有礼渠道,才有该信息,对应支付有礼活动编号信息 。该字段并不会和扫码领券(act_code)同时出现。
示例值:540358695
营销馆活动ID act_code string[1,32] 仅在扫码领券(营销馆)渠道,才有该信息,对应领券的营销馆领券活动ID信息。该字段并不会和支付有礼活动编码(act_code)同时出现。
示例值:v3OlhIVg6HpBi2WP2bjNXw
营销馆ID hall_code string[1,32] 仅在扫码领券(营销馆)渠道,才有该信息,对应领券的营销馆 馆ID信息
示例值:7xcvJIFPzxucJMd3tUeNHg
营销馆所属商户号 hall_belong_mch_id int 仅在扫码领券(营销馆)渠道,才有该信息,对应领券的营销馆所属商户号信息
示例值:1900120923
会员卡ID card_id string[1,32] 仅在会员卡活动渠道,才有该信息,对应会员卡Card_ID信息
示例值:pbLatjuzLrql_szmIQZhhTTPwBcg
会员卡code code string[1,32] 仅在会员卡活动渠道,才有该信息,对应用户卡包会员卡卡Code信息
示例值:15994704420
会员活动ID activity_id string[1,32] 仅在会员卡活动渠道,才有该信息,对应会员有礼活动ID信息
示例值:42001

通知应答

支付通知http应答码为200或204才会当作正常接收,当回调处理异常时,应答的HTTP状态码应为500,或者4xx。

参数名 变量 类型[长度限制] 必填 描述
返回状态码 code string[1,32] 错误码,SUCCESS为清算机构接收成功,其他错误码为失败。
示例值:SUCCESS
返回信息 message string[1,64] 返回信息,如非空,为错误原因。
示例值:系统错误

注意:当商户后台应答失败时,微信支付将记录下应答的报文,建议商户按照以下格式返回。



{   
    "code": "ERROR_NAME",
    "message": "ERROR_DESCRIPTION",
}

版本说明

关闭
V1.2
2020.11.12
1. 发券附加信息 新增“营销馆ID、营销馆所属商户号、营销馆活动ID、会员卡ID、会员卡code、会员活动ID”字段
V1.1
2020.2.27
1. 支付有礼通知增加“发券附加信息(attach_info)”
V1.0
2019.12.20
1. 商家券领券事件回调通知上线

技术咨询

文档反馈