查询代金券信息

接口请求链接

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

请求参数

字段名 变量名 必填 示例值 类型 说明
代金券id coupon_id 1565 String 代金券id
用户openid openid onqOjjrXT-776SpHnfexGm1_P7iE String Openid信息,用户在appid下的openid。
公众账号ID appid wx5edab3bdfba3dc1c String(32) 微信为发券方商户分配的公众账号ID,接口传入的所有appid应该为公众号的appid(在mp.weixin.qq.com申请的),不能为APP的appid(在open.weixin.qq.com申请的)。
商户号 mch_id 10000098 String(32) 微信为发券方商户分配的商户号
批次号 stock_id 58818 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>121512345</appid>
<coupon_id>121512345456</coupon_id>
<mch_id>10010405</mch_id>
<nonce_str>1417575784</nonce_str>
<openid>onqOjjrXT-776SpHnfexGm1_P7iE</openid>
<sign>16F1415792512A5C340170B35F6C60E6</sign>
</xml>

返回参数

字段名 变量名 必填 示例值 类型 说明
返回状态码 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) 微信为发券方商户分配的商户号
子商户号 sub_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 1567 String 代金券批次Id
代金券id coupon_id 4242 String 代金券id
代金券面额 coupon_value 4 Unsinged int 代金券面值,单位是分
代金券使用门槛 coupon_minimum 10 Unsinged int 代金券使用最低限额,单位是分
代金券名称 coupon_name 测试代金券 String 代金券名称
代金券状态 coupon_state SENDED String 代金券状态:SENDED-可用,USED-已实扣,EXPIRED-已过期
代金券描述 coupon_desc 微信支付-代金券 String 代金券描述
实际优惠金额 coupon_use_value 0 Unsinged int 代金券实际使用金额
优惠剩余可用额 coupon_remain_value 4 Unsinged int 代金券剩余金额:部分使用情况下,可能会存在券剩余金额
发放来源 send_source FULL_SEND String 代金券发放来源:FULL_SEND-满送 NORMAL-普通发放场景
是否允许部分使用 is_partial_use 1 String 该代金券是否允许部分使用标识:1-表示支持部分使用

返回参数示例:

成功示例

<xml>
  <return_code>SUCCESS</return_code>
  <appid>wx5edab3bdfba3dc1c</appid>
  <mch_id>10000098</mch_id>
  <nonce_str>1417586982</nonce_str>
  <sign>841B3002FE2220C87A2D08ABD8A8F791</sign>
  <result_code>SUCCESS</result_code>
  <coupon_stock_id>1717</coupon_stock_id>
  <coupon_id>1442</coupon_id>
  <coupon_value>5</coupon_value>
  <coupon_minimum>10</coupon_minimum>
  <coupon_name>测试代金券</coupon_name>
  <coupon_state>SENDED</coupon_state>
  <coupon_desc>微信支付-代金券</coupon_desc>
  <coupon_use_value>0</coupon_use_value>
  <coupon_remain_value>5</coupon_remain_value>
  <send_source>FULL_SEND</send_source>
</xml>

失败示例

<xml>
  <return_code>SUCCESS</return_code>
  <appid>wx5edab3bdfba3dc1c</appid>
  <mch_id>10000098</mch_id>
  <nonce_str>1417586982</nonce_str>
  <sign>841B3002FE2220C87A2D08ABD8A8F791</sign>
  <result_code>SUCCESS</result_code>
  <err_code>PARAM_ERROR</err_code>
  <err_code_des>你已领取过包</err_code_des>
  <coupon_stock_id>1717</coupon_stock_id>
  <coupon_id>1442</coupon_id>
  <coupon_value>5</coupon_value>
  <coupon_mininum>10</coupon_mininum>
  <coupon_name>测试代金券</coupon_name>
  <coupon_state>USED</coupon_state>
  <coupon_desc>微信支付-代金券</coupon_desc>
  <coupon_use_value>0</coupon_use_value>
  <coupon_remain_value>5</coupon_remain_value>
  <send_source>FULL_SEND</send_source>
</xml>

错误码

错误代码 描述 解决方案
COUPON_NOT_FOUND 券没有查找成功 确认券id、用户openid的正确性
SIGN_ERROR 签名错误 验证签名有误
COUPON_STOCK_ID_NOT_VALID 批次id不正确 确认批次id正确性以及和商户id的所属关系是否正确
REQ_PARAM_XML_ERR 输入的参数xml格式有误 检查输入的xml格式是否正确
COUPON_STOCK_ID_EMPTY 批次id为空 确认批次id正确传入
MCH_ID_EMPTY 商户id为空 确认商户id正确传入
CODE_2_ID_ERR 商户id有误 确认商户id是否正确并合法
GET_COUPON_STOCK_FAIL 获取批次信息失败 确认批次id信息正确
COUPON_STOCK_NOT_FOUND 批次信息不存在 确认批次id信息正确