H5发券
更新时间:2024.01.29微信支付为商户提供H5发券接口,可在H5页面为指定用户发放指定批次的微信支付商家券。推荐使用 JSAPI H5发券功能,两者区别如下:
- JSAPI H5发券功能 发券后会回调领券结果给到商家,方便商家做对应的处理;该H5发券不回调信息给商家,依赖商家主动去查询。
- 支持小程序嵌套H5场景的发券,该H5发券不支持在小程序内进行调用。
原理:H5发券的领券页面是带有weixin域名的一个H5页面,不支持在商家小程序调用(因为商家没有这个域名的备案资质);而jsapi发券的领券页面是原生页面,不受小程序框架约束。
# 接口说明
支持商户: 【普通商户】
接口规则: 本接口使用V2版本接口规则,详见V2接口规则 (opens new window)内容
# H5接入操作
# 1、发券方式
用户在商户H5页面触发领券操作后,通过URL跳转,由商户H5重定向至指定微信支付H5页面https://action.weixin.qq.com/busifavor/getcouponinfo
并添加指定参数,用户在微信支付H5页面中点击领券后,将自动给用户发券。
注意
每一个H5领券域名后,都需添加#wechat_pay&wechat_redirect,否则会报错,返回268435461错误码
1https://action.weixin.qq.com/busifavor/getcouponinfo?stock_id=1234567890000000&out_request_no=201911280000&sign=D0D028212D200DC9DASDFSDFFD3676BEAD03046DC3A2E82A64C784EFFAF&send_coupon_merchant=123456789&open_id=oiSFDIOoijdsf#wechat_pay&wechat_redirect
# 2、URL中参数
商户需在URL中携带用户信息及批次信息方可正常发券,具体参数如下:
- stock_id 必填微信支付商家券批次号
- out_request_no 必填发券凭证(示例格式:商户ID+日期+流水号),可包含英文字母、数字,不允许出现其他不合法符号,商户侧需保证发放凭据号唯一性
- sign 必填
- send_coupon_merchant 必填调用发券接口的商户号
- open_id 必填目标发券的用户OpenID校验规则:1,可用归属商户号绑定的AppID获取的OpenID2,可用发券商户绑定的AppID获取的OpenID获取OpenID请查看文档
- customize_send_time{n} 选填商家券在商户业务系统里的实际领取时间,仅针对有设置相对领取时间的批次生效(即批次有设置“生效后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秒。
- coupon_code 选填如果批次配置了 code 模式为“商户发放时接口指定券 code”,则必填,其他模式无需填写
# 参与签名字段说明
- stock_id 必填微信支付券批次ID
- out_request_no 必填发券凭证, 可包含英文字母,数字,|,_,*,-等内容,不允许出现其他不合法符号,需在单个批次单个用户下确保唯一性
- send_coupon_merchant 必填调用发券接口的商户号
- open_id 必填目标发券的用户OpenID
- coupon_code 选填如果批次配置了 code 模式为“商户发放时接口指定券 code”,则必填,其他模式无需填写
1coupon_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_pay&wechat_redirect,请检查是否添加 |
272756767 | 指定Code发券模式下, 没有填写指定Code信息 | 请检查发券参数,检查是否有填写Coupon_code |
272757252 | 无权限操作 | 请检查调用发券接口的发券商户号与批次号之间的关系,是否未批次的创建方或归属方或有合作授权关系 |
272756761 | 上传的Code已用完 | 发券批次的券Code模式是上传自定义Code,请检查上传的Code是否充足 |
文档是否有帮助