---
url: "https://pay.weixin.qq.com/doc/v3/merchant/4012285674.md"
title: "小程序发券插件"
doc_id: 4012285674
---

>更新时间：2025.02.19

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



## 接口说明

支持商户： 【普通商户】

接口规则： 本接口使用V2版本接口规则，详见[V2接口规则](https://pay.weixin.qq.com/doc/v2/merchant/4011986592.md)内容

## 小程序接入插件操作

插件版本号：latest

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

注意：2.0.2以下插件版本将不再支持发券。请将插件版本号设置为“latest" 或当前最新版本，点击查看版本[更新记录](https://mp.weixin.qq.com/wxopen/pluginbasicprofile?action=intro&appid=wxf3f436ba9bd4be7b&token=1260157248&lang=zh_CN)。

### 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

插件在用户点击后成功获取到优惠券信息触发的事件函数名称，使用方法可参考《[自定义组件文档](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/)》的自定义组件触发事件

注意：查询到优惠券信息不代表用户一定能够看到优惠券弹窗或者发券成功，如果参数send\_coupon\_result中没有券发送成功（券状态码不为SUCCESS），用户会被告知领券失败

* * *

`bind:userconfirm / binduserconfirm` 选填 string

用户点击弹窗中的确认收券按钮后触发的事件函数名称，可用作跳转到优惠券的使用界面

* * *

`suggest_immediate_use` 选填 boolean

提示优惠券是否要立即使用，如果为true，弹窗中的确认按钮内的文字为“立即使用”，如果为false，则显示为“我知道了”，参数默认值为false

注意：此参数对用户是否立即使用没有约束力，需要商家在用户确认领券事件内自行约束。如果此参数设为true，请在binduserconfirm事件中引导用户使用优惠券

* * *

`send_coupon_params` 必填 array

发券参数，一次最多10张

数组

`stock_id` 必填  string(20)

微信支付券批次ID

* * *

`out_request_no` 必填  string(64)

发券凭证，可包含英文字母，数字，｜，\_，\*，-等内容，不允许出现其他不合法符号，需在单个批次单个用户下确保唯一性

* * *

`coupon_code`  选填 string(128)

券code，如果是商家券，且批次是发放时指定code的类型，则发券时必填coupon\_code；支付券无需填写。

* * *

`create_coupon_merchant`  选填 string(15)

创建支付券的商户号；如果是支付券，则是必填项；商家券无需填写

* * *

`customize_send_time`  选填 string(32)

商家券在商户业务系统里的实际领取时间，仅针对有设置相对领取时间的批次生效（即批次有设置“生效后N天内有效”或“领取后N天开始生效”时间字段）。传入后，将使用传入的时间点，做为商家券领取时间来计算有效期，而非用户在微信支付系统中点击领取的时间 。

遵循[rfc3339](https://datatracker.ietf.org/doc/html/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秒。

目前只支持商家券、支付券暂不支持

* * *

`sign` 必填  string(64)

签名计算值。

签名方式：HMAC-SHA256。

签名规则：详见[《V2 签名规则》](https://pay.weixin.qq.com/doc/v2/merchant/4011986592.md)

[参与签名字段说明](https://pay.weixin.qq.com/doc/v3/merchant/4012285674.md#%E5%8F%82%E4%B8%8E%E7%AD%BE%E5%90%8D%E5%AD%97%E6%AE%B5%E8%AF%B4%E6%98%8E)

* * *

`send_coupon_merchant` 必填  string(15)

发券商户号

#### 参与签名字段说明

注意

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，设置路径：【微信商户平台-->账户中心-->账户设置-->API安全-->设置API密钥】

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

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

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

6. 更多规则详见《[V2签名规则](https://pay.weixin.qq.com/doc/v2/merchant/4011986592.md)》


`send_coupon_merchant` 必填  string(15)

发券商户号

* * *

`stock_id{n}` 必填  string(20)

微信支付券批次ID，{n}为下标，从0开始，例如stock\_id0

* * *

`out_request_no{n}` 必填  string(64)

发券凭证，{n}为下标，从0开始，例如out\_request\_no0。可包含英文字母，数字，｜，\_，\*，-等内容，不允许出现其他不合法符号，需在单个批次单个用户下确保唯一性

* * *

`coupon_code{n}` 选填  string(128)

券code，如果批次是发放时指定code的类型，则发券时必填coupon\_code{n}为下标，从0开始，例如stock\_id0

* * *

`customize_send_time{n}` 选填  string(32)

商家券在商户业务系统里的实际领取时间，仅针对有设置相对领取时间的批次生效（即批次有设置“生效后N天内有效”或“领取后N天开始生效”时间字段）。传入后，将使用传入的时间点，做为商家券领取时间来计算有效期，而非用户在微信支付系统中点击领取的时间 。

遵循[rfc3339](https://datatracker.ietf.org/doc/html/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秒。

目前只支持商家券、支付券暂不支持

* * *

`create_coupon_merchant{n}` 选填  string(15)

创建支付券的商户号； {n}为下标，从0开始，例如create\_coupon\_merchant0。 如果是支付券，则是必填项； 商家券无需填写

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

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

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

## 返回处理

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

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

### 返回示例

```
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 | 发券频率过高 | 提示报错，引导用户稍后操作。例如“活动太过火爆，请稍后再领取 |
| SYSTEMERROR | 插件版本过低 | 当前小程序发券插件版本过低，请更新至2.0.2以上版本 |

### 发券结果（send\_coupon\_result）中的错误码

| 错误码 | 描述 | 解决方案 |
| --- | --- | --- |
| SUCCESS | 该张券发券成功 | 提示用户领取成功/改变前端领券按钮状态 |
| FAILED | 该张券发券失败，查看message中的具体错误信息 | 提示用户领券失败，请开发者查看message中具体的错误信息并进行修复处理 |
| NOTENOUGH | 总预算用完 | 提示用户领券失败，请增加批次预算 |
| DAYLIMIT | 用户达到单天限领 | 提示用户领券失败，如需继续发放，可调整该批次单天发放上限 |
| NATURELIMIT | 用户自然人限领 | 提示用户领券失败，可提示用户检查其所有微信号领券情况，并请商户留意刷单风险 |
| MAXQUOTA | 用户领取张数达到上限 | 提示用户领券失败，该用户领取数量已达上限 |
| DUPREQUEST | 已通过该发券凭证给用户发券 | 提示用户领取成功/改变前端领券按钮状态 |
| NOTRUNNING | 批次状态非运营中 | 提示用户领券失败，并检查批次状态<br>如果批次是暂停状态，需重启后方可发放<br>如果批次已过期，请更换批次 |
| EXPIRED | 该批次已过期 | 请更换在有效期内的批次，再进行发放 |
| NOTMONEY | 账户余额不足 | 请检查批次号是否正确 |
| USERLIMIT | 用户已超限领额度 | 提示用户已超限领额度 |
| FREQUENCYLIMIT | 超过频率限制 | 可稍后重试 |
| USERREJECT | 用户主动拒绝领取 | 根据用户领取结果改变前端领券按钮状态 |