商户进件
特约商户进件
基础支付
JSAPI支付
APP支付
H5支付
Native支付
小程序支付
合单支付
付款码支付
经营能力
支付即服务
点金计划
行业方案
平台收付通(商户进件)
平台收付通(普通支付)
平台收付通(合单支付)
平台收付通(分账)
平台收付通(补差)
平台收付通(退款)
平台收付通(余额查询)
平台收付通(商户提现)
平台收付通(注销申请)
平台收付通(注销后提现)
平台收付通(跨境付款)
平台收付通(下载账单)
智慧商圈
微信支付分停车服务
电子发票
营销工具
代金券
商家券
委托营销
支付有礼
小程序发券插件
H5发券
图片上传(营销专用)
现金红包
资金应用
分账
连锁品牌分账
风险合规
商户开户意愿确认
消费者投诉2.0
商户违规通知回调
其他能力
图片上传
视频上传
微信支付平台证书

H5发券API

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


微信支付为商户提供H5发券接口,可在H5页面为指定用户发放指定批次的微信支付商家券。推荐使用 JSAPI H5发券功能,两者区别如下:
1. JSAPI H5发券功能 发券后会回调领券结果给到商家,方便商家做对应的处理;该H5发券不回调信息给商家,依赖商家主动去查询。
2. 支持小程序嵌套H5场景的发券,该H5发券不支持在小程序内进行调用。
原理:H5发券的领券页面是带有weixin域名的一个H5页面,不支持在商家小程序调用(因为商家没有这个域名的备案资质);而jsapi发券的领券页面是原生页面,不受小程序框架约束。

接口说明

适用对象: 服务商

接口规则:本接口使用V2版本接口规则,详见V2接口规则内容

H5接入操作

1、发券方式

用户在商户H5页面触发领券操作后,通过Url跳转,由商户H5重定向至指定微信支付H5页面(https://action.weixin.qq.com/busifavor/getcouponinfo)并添加指定参数,用户在微信支付H5页面中点击领券后,将自动给用户发券。
注:每一个H5领券域名后,都需添加#wechat_redirect,否则会报错,返回268435461错误码


https://action.weixin.qq.com/busifavor/getcouponinfo?stock_id=1234567890000000&out_request_no=201911280000&sign=D0D028212D200DC9DASDFSDFFD3676BEAD03046DC3A2E82A64C784EFFAF&send_coupon_merchant=123456789&open_id=oiSFDIOoijdsf#wechat_redirect

2、URL中参数

商户需在Url中携带用户信息及批次信息方可正常发券,具体参数如下:

参数名 变量 类型[长度限制] 必填 描述
批次号 stock_id string[1,20] 微信支付商家券批次号
发券凭证 out_request_no string[1,128] 发券凭证(示例格式:商户 id+日期+流水号),可包含英文字母、数字,不允许出现其他不合法符号,商户侧需保证发放凭据号唯一性
签名 sign string 签名计算值。 
签名方式:HMAC-SHA256。 
签名规则:详见《V2 签名规则》
参与签名字段说明
注意:为了安全,签名必须在后台服务器计算,禁止在H5中计算,签名 key 为微信支付 apiv2 的 signkey
示例值:9A0A8659F005D6984697E2CA0A9CF3B79A0A8659F005D6984697E2CA0A9CF3B7
发券商户号 send_coupon_merchant string[8,15] 调用发券接口的商户号
用户openid open_id string[1,128] 目标发券的用户openid
校验规则:
1,可用归属商户号绑定的APPID获取的openid
2,可用发券商户绑定的APPID获取的openid
获取openid请查看文档
自定义领取时间 customize_send_time{n} string[1,32] 商家券在商户业务系统里的实际领取时间,仅针对有设置相对领取时间的批次生效(即批次有设置“生效后N天内有效”或“领取后N天开始生效”时间字段)。传入后,将使用传入的时间点,做为商家券领取时间来计算有效期,而非用户在微信支付系统中点击领取的时间 。
遵循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
券 code coupon_code string[1,128] 如果批次配置了 code 模式为“商户发放时接口指定券 code”,则必填,其他模式无需填写
示例值:75345199

参与签名字段说明

参数名 变量 类型[长度限制] 必填 描述
批次号 stock_id string[1,20] 微信支付券批次id
示例值:123
发券凭证 out_request_no string[1,128] 发券凭证, 可包含英文字母,数字,|,_,*,-等内容,不允许出现其他不合法符号,需在单个批次单个用户下确保唯一性
示例值:1234567
发券商户号 send_coupon_merchant string[8,15] 发券商户号
示例值:10016226
用户openid open_id string[1,128] 目标发券的用户openid
示例值:10011212261
券 code coupon_code string[1,128] 如果批次配置了 code 模式为“商户发放时接口指定券 code”,则必填,其他模式无需填写
示例值:75345199

coupon_code=75345199&open_id=ow8uG5EM11Cnm&out_request_no=20191204550002&send_coupon_merchant=232323234&stock_id=12111100000001&key=3a5bc16abcdd22222

返回处理

由于H5发券采用的是Url重定向的形式,故无法直接将发券结果返回给商户。
建议商户调用【根据过滤条件查询用户券】接口及【查询用户单张券详情】接口,查询发券接口。


举例:用户领券完成并返回商家H5后,商家可自行触发刷新事件,使用【根据过滤条件查询用户券】接口,通过创建商户号、批次号、openid,查询用户是否已成功领取指定批次券,以及领取券的具体code。

错误码

如果发券失败,错误码将在发券结果页面展示给用户及开发者,开发者可根据该页面展示的错误码查询失败原因。


为保证用户体验,部分易懂的错误原因将直接展示给用户。


发券结果(send_coupon_result)中的错误码


错误码 描述 解决方案
268455936 发券参数错误,请检查发券参数 请检查发券参数
272758302,272756756 批次已过期 请检查批次时间
272758303,272756737,272757763 批次预算不足 请检查批次预算
272756738 该批次已达到单天发放上限 请检查批次单天发放上限
272756740 用户领取券张数已达上限 请检查用户领取情况
272756753 用户已领取过这张券 请检查用户领取情况
272756739 自然人限领拦截 请停止发放给该用户
272756743 批次状态不合法,检查该批次是否处于运营中 请检查批次状态
272756762  指定Code发券模式下, 当前发券Code已被使用 请更换Code后重试
272755722 批次不存在 请检查批次号是否正确
272755713 用户安全防刷拦截(潜在羊毛党、黑产用户) 请停止发放给该用户
272758292 未获取到用户信息,需重试 请检查用户信息是否正确
272758286 openid不正确 请检查openid是否正确
272758293 签名错误 请检查签名是否正确
272758295,272758304 系统超时,请重试 请稍后重试
272756755 发券商户号必须为制券商户号或券归属商户号 请检查发券商户号是否为制券商户号或券归属商户号
272756757 用户openid对应的appid必须与发券商户号有绑定关系 请检查用户openid对应的appid与发券商户号是否有绑定关系
268435461 H5领券域名参数错误 每一个H5领券域名后,都需添加#wechat_redirect,请检查是否添加
272756767 指定Code发券模式下, 没有填写指定Code信息 请检查发券参数,检查是否有填写Coupon_code
272757252 无权限操作 请检查调用发券接口的发券商户号与批次号之间的关系,是否未批次的创建方或归属方或有合作授权关系
272756761 上传的Code已用完 发券批次的券Code模式是上传自定义Code,请检查上传的Code是否充足


技术咨询

文档反馈