H5发券

更新时间:2024.01.29

微信支付为商户提供H5发券接口,可在H5页面为指定用户发放指定批次的微信支付商家券。推荐使用 JSAPI H5发券功能,两者区别如下:

  1. JSAPI H5发券功能 发券后会回调领券结果给到商家,方便商家做对应的处理;该H5发券不回调信息给商家,依赖商家主动去查询。
  2. 支持小程序嵌套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 必填 string(20)
    微信支付商家券批次号
  • out_request_no 必填 string(128)
    发券凭证(示例格式:商户ID+日期+流水号),可包含英文字母、数字,不允许出现其他不合法符号,商户侧需保证发放凭据号唯一性
  • sign 必填 string
    签名计算值。
    签名方式:HMAC-SHA256。
    签名规则:详见《V2 签名规则》
    参与签名字段说明
  • send_coupon_merchant 必填 string(15)
    调用发券接口的商户号
  • open_id 必填 string(128)
    目标发券的用户OpenID
    校验规则:
    1,可用归属商户号绑定的AppID获取的OpenID
    2,可用发券商户绑定的AppID获取的OpenID
    获取OpenID请查看文档
  • customize_send_time{n} 选填 string(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秒。
  • coupon_code 选填 string(128)
    如果批次配置了 code 模式为“商户发放时接口指定券 code”,则必填,其他模式无需填写

# 参与签名字段说明

  • stock_id 必填 string(20)
    微信支付券批次ID
  • out_request_no 必填 string(128)
    发券凭证, 可包含英文字母,数字,|,_,*,-等内容,不允许出现其他不合法符号,需在单个批次单个用户下确保唯一性
  • send_coupon_merchant 必填 string(15)
    调用发券接口的商户号
  • open_id 必填 string(128)
    目标发券的用户OpenID
  • coupon_code 选填 string(128)
    如果批次配置了 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是否充足