基础支付
JSAPI支付
APP支付
H5支付
Native支付
小程序支付
合单支付
付款码支付
经营能力
微信支付分(免确认模式)
微信支付分(免确认预授权模式)
微信支付分(需确认模式)
微信支付分(公共API)
支付即服务
行业方案
智慧商圈
微信支付分停车服务
营销工具
代金券
商家券
委托营销
消费卡
支付有礼
小程序发券插件
H5发券
图片上传(营销专用)
现金红包
资金应用
付款
分账
风险合规
消费者投诉2.0
其他能力
清关报关
图片上传
视频上传

核销用户券API

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


在用户满足优惠门槛后,商户可通过该接口核销用户微信卡包中具体某一张商家券。

接口说明

适用对象: 直连商户

请求URL:https://api.mch.weixin.qq.com/v3/marketing/busifavor/coupons/use

请求方式:POST

接口频率:500QPS


path 指该参数为路径参数

query 指该参数需在请求URL传参

body 指该参数需在请求JSON传参


请求参数

参数名 变量 类型[长度限制] 必填 描述
券code coupon_code string[1,32] body 券的唯一标识。
示例值:sxxe34343434
批次号 stock_id string[1,20] body 微信为每个商家券批次分配的唯一ID,当你在创建商家券接口中的coupon_code_mode参数传值为MERCHANT_API或者MERCHANT_UPLOAD时,则核销接口中该字段必传,否则该字段可不传
示例值:100088
公众账号ID appid string[1,32] body 支持传入与当前调用接口商户号有绑定关系的appid。支持小程序appid与公众号appid。核销接口返回的openid会在该传入appid下进行计算获得。
校验规则:传入的APPID得是与调用方商户号(即请求头里面的商户号)有绑定关系的APPID或传入的APPID得是归属商户号有绑定关系的APPID
示例值:wx1234567889999
请求核销时间 use_time string[1,32] body 商户请求核销用户券的时间。 遵循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
核销请求单据号 use_request_no string[1,32] body 每次核销请求的唯一标识,商户需保证唯一。
示例值:1002600620019090123143254435
用户标识 openid string[1,128] body 用户的唯一标识,做安全校验使用,非必填。
校验规则:传入的openid得是调用方商户号(即请求头里面的商户号)有绑定关系的APPID获取的openid或传入的openid得是归属商户号有绑定关系的APPID获取的openid。获取openid文档
示例值:xsd3434454567676

请求示例


{
  "coupon_code": "sxxe34343434",
  "stock_id": "100088",
  "appid": "wx1234567889999",
  "use_time": "2015-05-20T13:29:35+08:00",
  "use_request_no": "1002600620019090123143254435",
  "openid": "xsd3434454567676"
}

    
{
JAVA示例代码
}
    

返回参数

参数名 变量 类型[长度限制] 必填 描述
批次号 stock_id string[1,20] 微信为每个商家券批次分配的唯一ID
示例值: 100088
用户标识 openid string[1,128] 用户在公众号内的唯一身份标识。
示例值:dsadas34345454545
系统核销券成功的时间 wechatpay_use_time string[1,32] 系统成功核销券的时间,遵循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

返回示例


> 200 Response
{
  "stock_id": "100088",
  "openid": "dsadas34345454545",
  "wechatpay_use_time": "2015-05-20T13:29:35+08:00"
}
                                

    http://2323weixin.qq.com
                                

错误码公共错误码

状态码 错误码 描述 解决方案
400 PARAM_ERROR 参数错误 查看具体错误信息,调整参数
400 SYSTEM_ERROR 系统错误 请使用相同参数稍后重新调用
400 RESOURCE_ALREADY_EXISTS 批次已存在 查看out_request_no字段是否重复使用
券已被其他订单核销 请通过查询券API确认券是否已被其他订单核销
404 RESOURCE_NOT_EXISTS 查询的资源不存在 请检查查询资源的对应id是否填写正确
403 NOAUTH 无权限 查看具体错误信息,确认是否有权限
400 APPID_MCHID_NOT_MATCH appid与请求方商户无关联关系 appid与请求方商户不匹配,请确认appid与请求方商户是否有关联关系
400 MCH_NOT_EXISTS 商户号不存在 请确认传入的商户号是否正确
404 USER_NOT_EXISTS openid不正确 请确认传入的openid是否正确
500 SYSTEM_ERROR 系统失败 多为网络超时引起,重试
429 FREQUENCY_LIMITED 频率限制 调用太频繁,请降低调用接口频率
403 RULELIMIT 券不在有效期 请确认券是否能在当前时间核销
400 INVALID_REQUEST 发券模式不合法 请更换支持预上传code的批次后重试
上传的自定义code已达上限 请更换一个新的批次后重试


技术咨询

文档反馈