发放代金券

场景介绍

用于商户主动调用接口给用户发放代金券的场景,已做防小号处理,给小号发放代金券将返回错误码。

注意:通过接口发放的代金券不会进入微信卡包

接口请求链接

https://api.mch.weixin.qq.com/mmpaymkttransfers/send_coupon

是否需要证书

请求需要双向证书。 详见证书使用

请求参数

字段名 变量名 必填 示例值 类型 说明
代金券批次id coupon_stock_id 1757 String 代金券批次id
openid记录数 openid_count 1 int openid记录数(目前支持num=1)
商户单据号 partner_trade_no 1000009820141203515766 String 商户此次发放凭据号(格式:商户id+日期+流水号),商户侧需保持唯一性
用户openid openid onqOjjrXT-776SpHnfexGm1_P7iE String Openid信息,用户在appid下的唯一标识
公众账号ID appid wx5edab3bdfba3dc1c String(32) 微信为发券方商户分配的公众账号ID,接口传入的所有appid应该为公众号的appid(在mp.weixin.qq.com申请的),不能为APP的appid(在open.weixin.qq.com申请的)。
商户号 mch_id 10000098 String(32) 微信为发券方商户分配的商户号
操作员 op_user_id 10000098 String(32) 操作员帐号, 默认为商户号
可在商户平台配置操作员对应的api权限
设备号 device_info   String(32) 微信支付分配的终端设备号
随机字符串 nonce_str 1417574675 String(32) 随机字符串,不长于32位
签名 sign 841B3002FE2220C87A2D08ABD8A8F791 String(32) 签名参数,详见签名生成算法
协议版本 version 1.0 String(32) 默认1.0
协议类型 type XML String(32) XML【目前仅支持默认XML】

请求参数示例:

<xml>
<appid> wx5edab3bdfba3dc1c</appid>
<coupon_stock_id>1757</coupon_stock_id>
<mch_id>10010405</mch_id>
<nonce_str>1417574675</nonce_str>
<openid>onqOjjrXT-776SpHnfexGm1_P7iE</openid>
<openid_count>1</openid_count>
<partner_trade_no>1000009820141203515766</partner_trade_no>
<sign>841B3002FE2220C87A2D08ABD8A8F791</sign>
</xml>

CURL请求带证书代码样例:

curl --cert 10010405.pem --key 10010405.key -H

"Content-Type:text/xml" -d

'<xml><mch_id>10010405</mch_id><appid>121512345</appid><nonce_str>1417582740</nonce_str><coupon_stock_id>1757</coupon_stock_id><openid_count>1</openid_count><openid>onqOjjrXT-776SpHnfexGm1_P7iE</openid><partner_trade_no>121512345456</partner_trade_no></xml>' https://api.mch.weixin.qq.com/secapi/promotion/send_coupon/ -i

返回参数

字段名 变量名 必填 示例值 类型 说明
返回状态码 return_code SUCCESS或者FAIL String(16)

SUCCESS/FAIL

此字段是通信标识,非交易标识,交易是否成功需要查看result_code来判断

返回信息 return_msg 成功:返回空” String(128) 返回信息,如非空,为通信错误原因
公众账号ID appid wx5edab3bdfba3dc1c String(32) 微信为发券方商户分配的公众账号ID,接口传入的所有appid应该为公众号的appid(在mp.weixin.qq.com申请的),不能为APP的appid(在open.weixin.qq.com申请的)。
商户号 mch_id 10000098 String(32) 微信为发券方商户分配的商户号
设备号 device_info 123456sb String(32) 微信支付分配的终端设备号,
随机字符串 nonce_str 1417574675 String(32) 随机字符串,不长于32位
签名 sign 841B3002FE2220C87A2D08ABD8A8F791 String(32) 对返回参数签名计算后得到的签名值
业务结果 result_code SUCCESS或者FAIL String(16) SUCCESS/FAIL
错误代码 err_code PARAM_ERROR String(32) 详见业务错误代码章节
错误代码描述 err_code_des 错误描述信息 String(128) 对错误信息的描述
代金券批次id coupon_stock_id 1757 String 创建代金券时生成的批次号,可在商户平台-代金券管理页面查看
返回记录数 resp_count 1 Int 返回记录数
成功记录数 success_count 1或者0 Int 成功记录数
失败记录数 failed_count 1或者0 Int 失败记录数
用户标识 openid onqOjjrXT-776SpHnfexGm1_P7iE String 用户在商户appid下的唯一标识
代金券id coupon_id 1870 String

对一个用户成功发放代金券则返回代金券id,即ret_code为SUCCESS的时候;

如果ret_code为FAILED则填写空串""

返回信息 ret_msg 失败描述信息,例如:“用户已达领用上限” String 返回信息,当返回码是FAILED的时候填写,否则填空串“”

返回参数示例:

成功示例格式:

<xml>
<return_code>SUCCESS</return_code>
<appid>wx5edab3bdfba3dc1c</appid>
<mch_id>10000098</mch_id>
<nonce_str>1417579335</nonce_str>
<sign>841B3002FE2220C87A2D08ABD8A8F791</sign>
<result_code>SUCCESS</result_code>
<coupon_stock_id>1717</coupon_stock_id>
<resp_count>1</resp_count>
<success_count>1</success_count>
<failed_count>0</failed_count>
<openid>onqOjjrXT-776SpHnfexGm1_P7iE</openid>
<ret_code>SUCCESS</ret_code>
<coupon_id>6954</coupon_id>
</xml>

失败示例格式:

<xml>
  <return_code>SUCCESS</return_code>
  <appid>wx5edab3bdfba3dc1c</appid>
  <mch_id>10000098</mch_id>
  <nonce_str>1417579335</nonce_str>
  <sign>841B3002FE2220C87A2D08ABD8A8F791</sign>
  <result_code>FAIL</result_code>
  <err_code>268456007</err_code>
  <err_code_des>你已领取过该代金券</err_code_des>
  <coupon_stock_id>1717</coupon_stock_id>
  <resp_count>1</resp_count>
  <success_count>0</success_count>
  <failed_count>1</failed_count>
  <openid>onqOjjrXT-776SpHnfexGm1_P7iE</openid>
  <ret_code>FAIL</ret_code>
  <ret_msg>你已领取过该代金券<ret_msg/>
  <coupon_id></coupon_id>
</xml>

错误码

错误代码 描述 解决方案
STOCK_NOT_EXIST 批次不存在 请检查请求参数中填写的代金券批次id和商户号是否正确
BLOCKED_BY_SPAMCHK 小号拦截 当前发放用户为小号,根据风险管控规则不允许给小号发放。
DAY_BUDGET_NOT_ENOUGH 批次达到单天发放预算上限 发券数量已经达到单天发放上限,可在商户平台批次详情页修改单天发放预算
USER_AL_GET_COUPON 你已领取过该代金券 用户已领过,正常逻辑报错
NETWORK ERROR 网络环境不佳,请重试 请重试
AL_STOCK_OVER 活动已结束 活动已结束,属于正常逻辑错误
FREQ_OVER_LIMIT 超过发放频率限制,请稍后再试 请求对发放请求做频率控制
PARAM_ERROR 校验参数错误(会返回具体哪个参数错误) 根据错误提示确认参数无误并更正
SIGN_ERROR 签名错误 验证签名有误
CA_ERROR 证书有误 确认证书正确,或者联系商户平台更新证书
REQ_PARAM_XML_ERR 输入参数xml格式有误 检查入参的xml格式是否正确
COUPON_STOCK_ID_EMPTY 批次ID为空 确保批次id正确传入
MCH_ID_EMPTY 商户ID为空 确保商户id正确传入
CODE_2_ID_ERR 商户id有误 检查商户id是否正确并合法
OPEN_ID_EMPTY 用户openid为空 检查用户openid是否正确并合法
ERR_VERIFY_SSL_SERIAL 获取客户端证书序列号失败! 检查证书是否正确
ERR_VERIFY_SSL_SN 获取客户端证书特征名称(DN)域失败! 检查证书是否正确
CA_VERIFY_FAILED 证书验证失败 检查证书是否正确
STOCK_IS_NOT_VALID 抱歉,该代金券已失效 代金券已失效,请确认代金券的有效性,重新请求
STOCK_AMOUNT_NOT_ENOUGH 代金券批次预算不足 商户可为该代金券批次追加预算后继续发券
MCH_NO_AUTH 商户无权限操作 该商户无权限进行该操作,请前往商户平台开通代金券权限
ACCOUNTERROR 帐号行为异常,无法领券 请求的代金券批次已在商户平台开启风险拦截功能,命中的用户无法领券,如需给用户发券,可创建不开启拦截的批次重发,或联系微信支付客服。