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

小程序发券插件API

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


支持商户在小程序场景内,向指定用户发放指定批次的支付券或商家券。

接口说明

适用对象:服务商

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

小程序接入插件操作


插件版本号:latest(更新时间 2021/06/23)

【推荐】如希望每次默认使用最新版本,可在app.json 文件配置"version": "latest";

如需指定版本,可点击查看更新记录选择版本

1、添加插件配置(引入插件包)

在小程序配置app.json 文件中加入如下配置:


{
  "plugins": {
    "sendCoupon": {
      "version": "latest",
      "provider": "wxf3f436ba9bd4be7b"

    }
  }
} 

2、在小程序页面中引入发券插件

  1)在小程序页面配置文件中加入如下配置,引入send-coupon组件:


{
  "usingComponents": {
    "send-coupon": "plugin://sendCoupon/send-coupon"
  }
} 

  2)在小程序页面的WXML模板中加入如下代码,并填入相关字段,字段说明参见小程序发券插件字段说明表

//page.wxml
<send-coupon
    bind:sendcoupon="getcoupon"
    bind:userconfirm="redirectuser"
    send_coupon_params="{{send_coupon_params}}"
    sign="{{sign}}"
    send_coupon_merchant="{{send_coupon_merchant}}"
    suggest_immediate_use="{{suggest_immediate_use}}"
  >
    <!-- 内部为自定义代码,按钮点击部分的代码写在这里 -->
    <!-- [[以下为示例代码 -->
    <view class="text">领券</view>
    <!-- 以上为示例代码 ]] -->
  </send-coupon>

小程序发券插件字段说明表

参数名 变量 类型[长度限制] 必填 描述
商家发券事件(自定义事件) bind:sendcoupon / bindsendcoupon
【原接口为bindcustomevent,建议更新原接口名称】
string 插件在用户点击后成功获取到优惠券信息触发的事件函数名称,使用方法可参考《自定义组件文档》的自定义组件触发事件
注意:查询到优惠券信息不代表用户一定能够看到优惠券弹窗或者发券成功,如果参数send_coupon_result中没有券发送成功(券状态码不为SUCCESS),用户会被告知领券失败
用户确认领券事件(自定义事件) bind:userconfirm / binduserconfirm string 用户点击弹窗中的确认收券按钮后触发的事件函数名称,可用作跳转到优惠券的使用界面
提示立即使用 suggest_immediate_use

boolean 提示优惠券是否要立即使用,如果为true,弹窗中的确认按钮内的文字为“立即使用”,如果为false,则显示为“我知道了”,参数默认值为false
注意:此参数对用户是否立即使用没有约束力,需要商家在用户确认领券事件内自行约束。如果此参数设为true,请在binduserconfirm事件中引导用户使用优惠券
+发券参数 send_coupon_params array 发券参数,一次最多10张
示例值:
发一张券JSON:
"send_coupon_params":[
{ "stock_id": "98065001",
"out_request_no": "89560002019101000121"
} ]
发多张券JSON:
"send_coupon_params":[
{ "stock_id": "98065001",
"out_request_no": "89560002019101000121" },
{ "stock_id": "98065001",
"out_request_no": "89560002019101000122" } ]
参数名 变量 类型[长度限制] 必填 描述
批次号 stock_id string[1,20] 微信支付券批次id
示例值:abc123
发券凭证 out_request_no string[1,64] 发券凭证,可包含英文字母,数字,|,_,*,-等内容,不允许出现其他不合法符号,需在单个批次单个用户下确保唯一性
示例值:1234567
券code coupon_code string[1,128] 券code,如果是商家券,且批次是发放时指定code的类型,则发券时必填coupon_code;
支付券无需填写。
示例值:asdsada
制券商户号 create_coupon_merchant string[8,15] 创建支付券的商户号;创建支付券的商户号; 如果是支付券,则是必填项; 商家券无需填写
示例值:10016226
自定义领取时间 customize_send_time 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
签名 sign string[1,64]
签名计算值
签名方式:HMAC-SHA256。
签名规则:详见《V2签名规则》
参与签名字段说明
注意:为了安全,签名必须在后台服务器计算,禁止在小程序中计算,签名key为微信支付apiv2的signkey
示例值:9A0A8659F005D6984697E2CA0A9CF3B79A0A8659F005D6984697E2CA0A9CF3B7
发券商户号 send_coupon_merchant string[8,15] 发券商户号
示例值:10016226

参与签名字段说明

注意:

1、当存在发放一张或多张券的情况下,参数名使用下标表示,下标从0开始:
发放一张券示例值:out_request_no0=abc123&send_coupon_merchant=10016226&stock_id0=1234567&key=xxxxx

发放多张券示例值:out_request_no0=abc123&out_request_no1=123abc&send_coupon_merchant=10016226&stock_id0=1234567&stock_id1=2345678&key=xxxxx


2、当 批次是发放时指定code的类型的情况下:
发放一张券示例值:coupon_code0=asdsada&out_request_no0=abc123&send_coupon_merchant=10016226&stock_id0=1234567&key=xxxxx

发放多张券示例值:coupon_code0=asdsada&coupon_code1=asdsada&out_request_no0=abc123&out_request_no1=123abc&send_coupon_merchant=10016226&stock_id0=1234567&stock_id1=2345678&key=xxxxx


3、如果遇到签名失败,请按照下面几项进行检查

  1)签名方式一定要用 HMAC-SHA256

  2)key需要使用apiv2的signkey,设置路径:【微信商户平台(pay.weixin.qq.com)-->账户设置-->API安全-->密钥设置】

  3)确认key的正确性,例如是否是本商户号下的key

  4)签名源串请按照示例参数格式进行拼接,参数顺序按照字典序排列

  5)参数名严格区分大小写

  6)更多规则详见《V2签名规则


参数名 变量 类型[长度限制] 必填 描述
发券商户号 send_coupon_merchant string[8,15] 发券商户号
示例值:10016226
批次号 stock_id{n} string[1,20] 微信支付券批次id,{n}为下标,从0开始,例如stock_id0
示例值:123
发券凭证 out_request_no{n} string[1,64] 发券凭证,{n}为下标,从0开始,例如out_request_no0。
可包含英文字母,数字,|,_,*,-等内容,不允许出现其他不合法符号,需在单个批次单个用户下确保唯一性
示例值:1234567
券code coupon_code{n} string[1,128] 条件选填 券code,如果批次是发放时指定code的类型,则发券时必填coupon_code
{n}为下标,从0开始,例如stock_id0
示例值:asdsada
自定义领取时间 customize_send_time 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
制券商户号 create_coupon_merchant{n} string[8,15] 创建支付券的商户号; {n}为下标,从0开始,例如create_coupon_merchant0。 如果是支付券,则是必填项; 商家券无需填写
示例值:10016226

3、在小程序页面对应的JS逻辑中,获取插件实例并执行初始化操作


javascript
//page.js
Page({
  // 此函数名称可以自定义,跟bindcustomevent绑定的保持一致
  getcoupon: function(params) {
    // 插件返回信息在params.detail
    console.log('getcoupon', params)
  }
})
                            

如果事件绑定正确,在用户点击领券后,会触发领券事件,得到返回之后会调用getcoupon函数。

返回处理

从回调函数参数detail中,获取参数。

参数名 变量 类型[长度限制] 必填 描述
外层错误码 errcode string[1,32]
返回整体错误码
错误信息 msg string[1,128]
返回整体错误信息
+发券结果 send_coupon_result object 发券结果,包含需要发放的每张券的结果信息,是否成功或失败原因
参数名 变量 类型[长度限制] 必填 描述
返回状态码 code string[1,16]
单张券错误码
返回信息 message string[1,128]
单张券错误信息
批次号 stock_id string[1,20] 微信支付券批次id
券code coupon_code string[1,128] 券的唯一标识
发券凭证 out_request_no string[1,64] 发券凭证,可包含英文字母,数字,|,_,*,-等内容,不允许出现其他不合法符号,需在单个批次单个用户下确保唯一性

返回示例


javascript
//获取代码示例
Page({
  data: {
    // ...
  },
  onLoad: function() {
    // ...
  },
  getcoupon: function(params) {
    console.log('getcoupon', params)
    console.log('detail', params.detail)
  }
})

错误码

Detail中errcode返回错误码


错误码 描述 解决方案
OK 调用成功 接口调用成功,具体发券结果(是否发券成功)需查看发券结果(send_coupon_result)中的参数
PARAM_ERROR 参数错误 参数错误,请开发者查看msg中具体的错误信息并进行修复处理
USER_NOT_EXISTS 登录态获取失效 引导用户重试
USER_GET_FAILED 登录态获取失败 报错,提示用户稍后操作
SIGN_ERROR 签名错误 请开发者检查签名正确性
SYSTEMERROR 发券超时 提示报错,提示用户稍后操作
FREQUENCY_LIMITED 发券频率过高 提示报错,引导用户稍后操作。例如“活动太过火爆,请稍后再领取”

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


错误码 描述 解决方案
SUCCESS 该张券发券成功 提示用户领取成功/改变前端领券按钮状态
FAILED 该张券发券失败,查看message中的具体错误信息 提示用户领券失败,请开发者查看message中具体的错误信息并进行修复处理
NOTENOUGH 总预算用完 提示用户领券失败,请增加批次预算
DAYLIMIT 用户达到单天限领 提示用户领券失败,如需继续发放,可调整该批次单天发放上限
NATURELIMIT 用户自然人限领 提示用户领券失败,可提示用户检查其所有微信号领券情况,并请商户留意刷单风险
MAXQUOTA 用户领取张数达到上限 提示用户领券失败,该用户领取数量已达上限
DUPREQUEST 已通过该发券凭证给用户发券 提示用户领取成功/改变前端领券按钮状态
NOTRUNNING 批次状态非运营中 提示用户领券失败,并检查批次状态

  1. 如果批次是暂停状态,需重启后方可发放
  2. 如果批次已过期,请更换批次
EXPIRED 该批次已过期 请更换在有效期内的批次,再进行发放
NOTMONEY 账户余额不足 请联系制券商户进行充值
USERLIMIT 用户已超限领额度 提示用户已超限领额度
FREQUENCYLIMIT 超过频率限制 可稍后重试


技术咨询

文档反馈