核销事件回调通知API

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


注意:

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

• 如果在所有通知频率(15s/15s/30s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h/6h/6h - 总计 24h4m)后没有收到微信侧回调,商户应调用查询订单接口确认订单状态。


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

接口说明

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

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

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

通知规则

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

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

通知报文

核销券信息通知是以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签名方案》

通知应答

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

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

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



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

回调示例

核销券成功结果通知


{ 
     "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": null, 
   "available_begin_time": "2015-05-20T13:29:35.120+08:00", 
   "available_end_time": "2015-05-20T13:29:35.120+08:00", 
   "singleitem": null, 
   "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


版本说明

关闭
V1.1
2019.12.25
1. 原始回调类型,券的原始回调类型调整为coupon

V1.0
2019.10.15
1. 核销事件回调通知上线

技术咨询

反馈有奖