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

用户领卡通知API

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


用户领取优惠卡后,微信会把用户领卡信息发送给商户。

注意:

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

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


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

接口说明

适用对象:直连商户

请求URL:该链接是通过商户【预受理领卡请求】中提交notify_url参数,必须为https协议。如果链接无法访问,商户将无法接收到微信通知。 通知url必须为直接可访问的url,不能携带参数。示例: “https://pay.weixin.qq.com/wxpay/pay.action”

通知规则

用户领取优惠卡后,微信会把用户领卡信息发送给商户,商户需要接收处理,并返回应答。出于安全的考虑,我们对数据进行加密,商户需要先对通知数据进行解密,才能得到用户领卡信息。

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

通知报文

用户领卡结果通知是以POST 方法访问商户设置的通知url,通知的数据以JSON 格式通过请求主体(BODY)传输。通知的数据包括了加密的支付结果详情。
(注:由于涉及到回调加密和解密,商户必须先设置好apiv3密钥后才能解密回调通知,apiv3密钥设置文档指引详见APIv3密钥设置指引

参数解密

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

  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形式的资源对象。

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

通知参数

参数名 变量 类型[长度限制] 必填 描述
通知ID id string[1,36] 通知的唯一ID。
示例值:EV-2018022511223320873
通知创建时间 create_time string[1,32] 通知创建的时间,格式为yyyyMMddHHmmss(标准iso8601时间格式)
遵循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年05月20日13点29分35秒。
示例值:2015-05-20T13:29:35+08:00
通知类型 event_type string[1,32] 通知的类型, 用户领卡通知的类型为:DISCOUNT_CARD.USER_ACCEPTED
示例值:DISCOUNT_CARD.USER_ACCEPTED
通知数据类型 resource_type string[1,32] 通知的资源数据类型,用户领卡通知为encrypt-resource。
示例值:encrypt-resource
+通知数据 resource object 通知资源数据
json格式,见示例
参数名 变量 类型[长度限制] 必填 描述
加密算法类型 algorithm string[1,32] 对支付结果数据进行加密的加密算法,目前只支持AEAD_AES_256_GCM。
示例值:AEAD_AES_256_GCM
数据密文 ciphertext string[1,1048576] Base64编码后的支付结果数据密文
示例值:EV-2018022511223320873
原始回调类型 original_type string[1,64] 原始回调类型为:discount_card
示例值:discount_card
附加数据 associated_data string[1,16] 附加数据
示例值:EV-2018022511223320873
随机串 nonce string[1,32] 加密使用的随机串
示例值:fdasflkja484w
回调摘要 summary string[1,64] 回调摘要
示例值:用户领卡成功

通知签名

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

回调示例

用户领卡结果通知


{
    "id":"EV-2018022511223320873",
    "create_time":"2015-05-20T13:29:35+08:00",
    "resource_type":"encrypt-resource",
    "event_type":"DISCOUNT_CARD.USER_ACCEPTED",
    "resource" : {
        "algorithm":"AEAD_AES_256_GCM",
        "ciphertext": "...",
        "original_type": "discount_card",
        "nonce": "...",
        "associated_data": ""
    },
   "summary":"用户领卡",
}

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


{
    "card_id": "233bcbf407e87789b8e471f251774f95",
    "card_template_id": "87789b2f25177433bcbf407e8e471f95",
    "openid": "oUpF8uMuAJ2pxb1Q9zNjWeS6o",
    "out_card_code": "6e8369071cd942c0476613f9d1ce9ca3",
    "appid": "wxd678efh567hg6787",
    "mchid": "1230000109",
    "time_range": {
        "begin_time": "2020-05-20T13:29:35.120+08:00",
        "end_time": "2020-05-21T13:29:35.120+08:00"
    },
    "state": "ONGOING",
    "create_time": "2020-05-20T13:29:35.120+08:00",
    "objectives" : [ 
	  {
	  "unit" : "次",
	  "name" : "一周购买三次商品",
	  "count" : 1,
	  "description" : "特价商品",
	  "objective_id" : "123456"
	  }, 
	  {
	  "unit" : "次",
	  "name" : "一周购买三次商品",
	  "count" : 1,
	  "description" : "特价商品",
	  "objective_id" : "123456"
	  } 
	],
    "rewards" : [ 
	  {
	  "unit" : "个",
	  "amount" : 100,
	  "count_type" : "COUNT_LIMIT",
	  "name" : "八折优惠",
	  "count" : 1,
	  "description" : "特价商品优惠",
      "reward_id" : "123456",
	  }, 
	  {
	  "unit" : "个",
	  "amount" : 100,
	  "count_type" : "COUNT_LIMIT",
	  "name" : "八折优惠",
	  "count" : 1,
	  "description" : "特价商品优惠",
	  "reward_id" : "123456"
	  } 
	],
	"sharer_openid" : "oUpF8uMuAJ2pxb1Q9zNjWUHsd"
}

用户领卡通知参数

参数名 变量 类型[长度限制] 必填 描述
先享卡ID card_id string[1,64] 先享卡ID,唯一标识一个先享卡。
示例值:233bcbf407e87789b8e471f251774f95
先享卡模板ID card_template_id string[1,64] 先享卡卡模板ID,唯一定义此资源的标识。创建模板后可获得。
示例值:87789b2f25177433bcbf407e8e471f95
用户标识 openid string[1,128] 微信用户在商户对应appid下的唯一标识
示例值:oUpF8uMuAJ2pxb1Q9zNjWeS6o
商户领卡号 out_card_code string[1,32] 商户在请求领卡预受理接口时传入的领卡请求号,同一个商户号下必须唯一,要求32个字符内,只能是数字、大小写字母_-|*
示例值:6e8369071cd942c0476613f9d1ce9ca3
公众账号ID appid string[10,32] 微信公众平台分配的与传入的商户号建立了支付绑定关系的appid,可在公众平台查看绑定关系
示例值:wxd678efh567hg6787
商户号 mchid string[1,32] 微信支付分配的商户号
示例值:1230000109
+ 约定时间期限 time_range object 用户领取先享卡之后,约定的生效时间和到期时间。
参数名 变量 类型[长度限制] 必填 描述
约定开始时间 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年05月20日13点29分35秒(需要增加所有跟时间有关的参数的描述)
示例值:2015-05-20T13:29:35.120+08:00
约定结束时间 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年05月20日13点29分35秒(需要增加所有跟时间有关的参数的描述)
示例值:2015-05-20T13:29:35.120+08:00
状态 state string[1,16] 先享卡的守约状态,
ONGOING:约定进行中,表示用户在约定有效期内,尚未完成所有目标时,守约状态为约定进行中。
SETTLING:约定到期核对中,在约定有效期结束后的一段时间,商户可对卡记录进行校对并做必要调整,守约状态为约定到期核对调整中。
FINISHED:已完成约定,表示用户在约定有效期内,已完成所有目标,守约状态为已完成约定。
UNFINISHED:未完成约定,表示用户在约定有效期到期后,最终未完成所有约定目标,或用户提前退出约定,守约状态为未完成约定。
示例值:ONGOING
创卡时间 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年05月20日13点29分35秒(需要增加所有跟时间有关的参数的描述)
示例值:2015-05-20T13:29:35.120+08:00
+ 目标列表 objectives array 用户先享卡目标列表
参数名 变量 类型[长度限制] 必填 描述
目标ID objective_id string[1,32] 由先享卡平台生成,唯一标识一个先享卡目标。商户需要记录该目标ID,进行同步用户记录。
示例值:123456
目标名称 name string[1,20] 目标的名称
示例值:一周购买三次商品
目标数量 count int 履约目标需要完成的数量,必须大于0。
示例值:1
目标单位 unit string[1,5] 目标的单位
示例值:次
目标描述 description string[1,50] 对先享卡目标的补充信息。
示例值:特价商品
+ 优惠列表 rewards array 用户先享卡优惠列表
参数名 变量 类型[长度限制] 必填 描述
优惠ID reward_id string[1,32] 由先享卡平台生成,唯一标识一个先享卡优惠。商户需要记录该优惠ID,进行同步用户记录。
示例值:123456
优惠名称 name string[1,20] 优惠名称
示例值:八折优惠
优惠数量类型 count_type string[1,18] 优惠数量的类型标识,枚举值:
COUNT_UNLIMITED:不限数量
COUNT_LIMIT:有限数量
示例值:COUNT_LIMIT
优惠数量 count int 本项优惠可使用的数量,必须大于0。
示例值:1
优惠单位 unit string[1,5] 优惠的单位
示例值:个
优惠金额 amount int64 1、优惠金额,此项优惠对应的优惠总金额,单位:分,必须大于0。
2、此项优惠已享累计金额≤创建模板时配置的此项奖励的奖励金额,
例如:优惠为【满10元减3元优惠券4张】时,用户一次消费使用了2张优惠券,优惠金额为本次优惠总金额6元,优惠数量为本次使用优惠的优惠券数量2张
示例值:100
优惠描述 description string[1,50] 对先享卡优惠的补充信息
示例值:特价商品优惠
邀请者用户标识 sharer_openid string[1,128] 微信用户在商户对应appid下的唯一标识。
仅当此卡是通过“邀请有礼”渠道领卡时,会返回此字段;指此先享卡是通过此[邀请者]邀请领卡成功的。当此先享卡完成约定时,商户可给此[邀请者]下发应邀请有礼的奖励
示例值:oUpF8uMuAJ2pxb1Q9zNjWUHsd

通知应答

商户后台在正确处理回调之后,需要返回200或者204的HTTP状态码。其他的状态码,微信支付均认为通知失败,并按照前述的策略定期发起通知。

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


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


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


技术咨询

文档反馈