基础支付
JSAPI支付
APP支付
H5支付
Native支付
小程序支付
合单支付
付款码支付
经营能力
微信支付分(免确认模式)
微信支付分(免确认预授权模式)
微信支付分(需确认模式)
微信支付分(公共API)
微信先享卡
支付即服务
行业方案
智慧商圈
营销工具
代金券
商家券
委托营销
消费卡
支付有礼
小程序发券插件
H5发券
图片上传(营销专用)
现金红包
资金应用
付款
分账
风险合规
消费者投诉2.0
其他能力
清关报关
图片上传
视频上传

核销事件回调通知API

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


注意:

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

• 如果在所有通知频率后没有收到微信侧回调,商户应调用查询订单接口确认订单状态。


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

接口说明

适用对象:直连商户

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

通知规则

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

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

通知报文

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

参数解密

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

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

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

通知参数

参数名 变量 类型[长度限制] 必填 描述
通知ID id string[1,32] 通知的唯一id。
示例值:EV-2018022511223320873
通知创建时间 create_time string[1,16] 通知创建的时间,格式为yyyyMMddHHmmss。
示例值:20180225112233
通知类型 event_type string[1,32] 通知的类型,代金券用券回调通知的类型为COUPON.USE。
示例值:COUPON.USE
通知数据类型 resource_type string[1,32] 通知的资源数据类型,代金券用券回调通知为encrypt-resource。
示例值:encrypt-resource
回调摘要 summary string[1,62] 回调摘要
示例值:用券成功
+通知数据 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] 附加数据
随机串 nonce string[1,16] 加密使用的随机串。
示例值:fdasflkja484w
原始回调类型 original_type string[1,64] 原始回调类型,券的原始回调类型为coupon
示例值:coupon

通知签名

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

回调示例

核销券成功结果通知


{ 
     "id":"EV-2018022511223320873", 
     "create_time":"20180225112233", 
     "resource_type":"encrypt-resource", 
     "event_type":"COUPON.USE", 
     "summary": "支付成功", 
     "resource" : { 
         "original_type": "coupon", 
         "algorithm":"AEAD_AES_256_GCM", 
         "ciphertext": "...", 
         "nonce": "...", 
         "associated_data": "", 
     } 
} 

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


{ 
   "stock_creator_mchid": "9800064", 
   "stock_id": "9865888", 
   "coupon_id": "98674556",
   "singleitem_discount_off": { 
     "single_price_max": 100 
   }, 
   "discount_to": { 
     "cut_to_price": 100, 
     "max_price": 10 
   }, 
   "coupon_name": "微信支付代金券", 
   "status": "EXPIRED", 
   "description": "微信支付营销", 
   "create_time": "2015-05-20T13:29:35.120+08:00", 
   "coupon_type": "CUT_TO", 
   "no_cash": true, 
   "available_begin_time": "2015-05-20T13:29:35.120+08:00", 
   "available_end_time": "2015-05-20T13:29:35.120+08:00", 
   "singleitem": true, 
   "normal_coupon_information": { 
     "coupon_amount": 100, 
     "transaction_minimum": 100 
   }, 
   "consume_information": { 
     "consume_time": "2015-05-20T13:29:35.120+08:00", 
     "consume_mchid": "9856081", 
     "transaction_id": "2345234523", 
     "goods_detail": [ 
       { 
         "goods_id": "a_goods1", 
         "quantity": 7, 
         "price": 1, 
         "discount_amount": 4 
       } 
     ] 
   } 
}

核销券通知参数

参数名 变量 类型[长度限制] 必填 描述
创建批次的商户号 stock_creator_mchid string[1,20] 批次创建方商户号。
示例值:9800064
批次号 stock_id string[1,20] 微信为每个代金券批次分配的唯一id。
示例值:9865888
代金券id coupon_id string[1,20] 微信为代金券唯一分配的id。
示例值:98674556
+单品优惠特定信息 singleitem_discount_off object 单品优惠特定信息。
参数名 变量 类型[长度限制] 必填 描述
单品最高优惠价格 single_price_max int64 单品最高优惠价格,单位:分。
示例值:100
+减至优惠特定信息 discount_to object 减至优惠限定字段,仅减至优惠场景有返回。
参数名 变量 类型[长度限制] 必填 描述
减至后优惠单价 cut_to_price int64 减至后优惠单价,单位:分。
示例值:100
最高价格 max_price int64 可享受优惠的最高价格,单位:分。
示例值:20
代金券名称 coupon_name string[1,20] 代金券名称
示例值:微信支付代金券
代金券状态 status string[1,16]
代金券状态:
SENDED:可用
USED:已实扣
EXPIRED:已过期
示例值:EXPIRED
代金券描述 description string[1,3000] 代金券描述说明字段。
示例值:微信支付营销
领券时间 create_time string[1,32] 领券时间,遵循rfc3339标准格式,格式为YYYY-MM-DDTHH:mm:ss.sss+TIMEZONE,YYYY-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss.sss表示时分秒毫秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35.120+08:00表示,北京时间2015年5月20日 13点29分35秒。
示例值:2015-05-20T13:29:35.120+08:00
券类型 coupon_type string[1,16]
NORMAL:满减券
CUT_TO:减至券
示例值:CUT_TO
是否无资金流 no_cash bool true:是
false:否
示例值:true
可用开始时间 available_begin_time string[1,32] 可用开始时间,遵循rfc3339标准格式,格式为YYYY-MM-DDTHH:mm:ss.sss+TIMEZONE,YYYY-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss.sss表示时分秒毫秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35.120+08:00表示,北京时间2015年5月20日 13点29分35秒。
示例值:2015-05-20T13:29:35.120+08:00
可用结束时间 available_end_time string[1,32] 可用结束时间,遵循rfc3339标准格式,格式为YYYY-MM-DDTHH:mm:ss.sss+TIMEZONE,YYYY-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss.sss表示时分秒毫秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35.120+08:00表示,北京时间2015年5月20日 13点29分35秒。
示例值:2015-05-20T13:29:35.120+08:00
是否单品优惠 singleitem bool true:是
false:否
示例值:true
+普通满减券信息 normal_coupon_information object 普通满减券面额、门槛信息。
参数名 变量 类型[长度限制] 必填 描述
面额 coupon_amount int64 面额,单位:分。
示例值:100
门槛 transaction_minimum int64 使用券金额门槛,单位:分。
示例值:100
+实扣代金券信息 consume_information object 已实扣代金券信息。
参数名 变量 类型[长度限制] 必填 描述
核销时间 consume_time string[1,32] 代金券核销时间,遵循rfc3339标准格式,格式为YYYY-MM-DDTHH:mm:ss.sss+TIMEZONE,YYYY-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss.sss表示时分秒毫秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35.120+08:00表示,北京时间2015年5月20日 13点29分35秒。
示例值:2015-05-20T13:29:35.120+08:00
核销商户号 consume_mchid string[1,20] 核销代金券的商户号。
示例值:9856081
核销订单号 transaction_id string[1,32]
核销订单号
示例值:2345234523
+单品信息 goods_detail array 商户下单接口传的单品信息。
参数名 变量 类型[长度限制] 必填 描述
单品编码 goods_id string[1,128] 单品券创建时录入的单品编码。
示例值:a_goods1
单品数量 quantity int 单品数据
示例值:7
单品单价 price int 单品单价
示例值:1
优惠金额 discount_amount int 优惠金额
示例值:4

通知应答

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

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

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



{   
    "code": "SUCCESS",
    "message": "成功"
}


文档调研

技术咨询

反馈有奖