微信支付-开发者文档

接口说明

适用对象：直连商户

接口规则： 本接口使用V2版本接口规则，详见V2接口规则内容

小程序接入插件操作

插件版本号：1.4.13（更新时间 2021/06/23）

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

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

1、添加插件配置（引入插件包）

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

JSON


{
  "plugins": {
    "sendCoupon": {
      "version": "1.4.13",
      "provider": "wxf3f436ba9bd4be7b"
    }
  }
}

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

1）在小程序页面配置文件中加入如下配置，引入send-coupon组件：

JSON


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

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

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

签名

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安全-->设置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	批次状态非运营中	提示用户领券失败，并检查批次状态如果批次是暂停状态，需重启后方可发放如果批次已过期，请更换批次
EXPIRED	该批次已过期	请更换在有效期内的批次，再进行发放
NOTMONEY	账户余额不足	请联系制券商户进行充值
USERLIMIT	用户已超限领额度	提示用户已超限领额度
FREQUENCYLIMIT	超过频率限制	可稍后重试

微信支付商户平台

小程序发券插件API