核销用户的券

更新时间:2023.08.16

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

# 接口说明

支持商户:
【普通服务商】【渠道商】
请求方式:
【POST】/v3/marketing/busifavor/coupons/use
请求域名:
【主域名】
https://api.mch.weixin.qq.com
使用该域名将访问就近的接入点
【备域名】
https://api2.mch.weixin.qq.com
使用该域名将访问异地的接入点 ,指引点击查看

# 请求参数

    Header HTTP头参数
  • Authorization 必填 string
    请参考 签名认证 生成认证信息
  • Accept 必填 string
    请设置为 application/json
  • Content-Type 必填 string
    请设置为 application/json
    Body 包体参数
  • coupon_code 必填 string
    【券code】 券的唯一标识
  • stock_id 选填 string
    【批次号】 微信为每个商家券批次分配的唯一ID,当你在创建商家券接口中的coupon_code_mode参数传值为MERCHANT_API或者MERCHANT_UPLOAD时,则核销接口中该字段必传,否则该字段可不传
  • appid 必填 string
    【公众账号ID】 支持传入与当前调用接口商户号有绑定关系的AppID。支持小程序AppID与公众号AppID。核销接口返回的OpenID会在该传入AppID下进行计算获得。
    校验规则:传入的AppID得是与调用方商户号(即请求头里面的商户号)有绑定关系的AppID或传入的AppID得是归属商户号有绑定关系的AppID
  • use_time 必填 string
    【请求核销时间】 商户请求核销用户券的时间。 遵循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秒。
  • use_request_no 必填 string(128)
    【核销请求单据号】 每次核销请求的唯一标识,商户需保证唯一
  • openid 选填 string
    【用户标识】 用户的唯一标识,做安全校验使用,非必填。
    校验规则:传入的OpenID得是调用方商户号(即请求头里面的商户号)有绑定关系的AppID获取的OpenID或传入的OpenID得是归属商户号有绑定关系的AppID获取的OpenID。获取OpenID文档

请求示例

POST

# 应答参数

    200OK
  • stock_id 必填 string
    【批次号】 批次ID
  • openid 必填 string
    【用户标识】 用户在该公众号内的唯一身份标识。
  • wechatpay_use_time 必填 string
    【系统核销券成功的时间】 系统成功核销券的时间,遵循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秒。

应答示例

200 OK

# 错误码

# 公共错误码

状态码 错误码 描述 解决方案
400 PARAM_ERROR 参数错误 请根据错误提示正确传入参数
400 INVALID_REQUEST HTTP 请求不符合微信支付 APIv3 接口规则 请参阅 接口规则
401 SIGN_ERROR 验证不通过 请参阅 签名常见问题
500 SYSTEM_ERROR 系统异常,请稍后重试 请稍后重试

# 业务错误码

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