发放代金券API

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


商户平台/API完成制券后,可使用发放代金券接口发券。通过调用此接口可发放指定批次给指定用户,发券场景可以是小程序、H5、APP等。

注意:

• 商户可在H5活动页面、商户小程序、商户APP等自有场景内调用该接口完成发券,商户默认只允许发放本商户号(调用发券接口的商户号)创建的代金券,如需发放其他商户商户创建的代金券,请参考常见问题Q1。

接口说明

适用对象:直连商户 服务商 渠道商

请求URL:https://api.mch.weixin.qq.com/v3/marketing/favor/users/{openid}/coupons

请求方式:POST

频率限制:500/s

处理耗时:100ms

接口规则:https://wechatpay-api.gitbook.io/wechatpay-api-v3


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

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

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


请求参数

参数名 变量 类型[长度限制] 必填 描述
批次号 stock_id string[1,20] body 微信为每个批次分配的唯一id。
校验规则:必须为代金券(全场券或单品券)批次号,不支持立减与折扣。
示例值:9856000
用户openid openid string[1,128] path openid信息,用户在appid下的唯一标识。
校验规则:该openid需要与接口传入中的appid有对应关系。
示例值:2323dfsdf342342
商户单据号 out_request_no string[1,128] body 商户此次发放凭据号(格式:商户id+日期+流水号),可包含英文字母,数字,|,_,*,-等内容,不允许出现其他不合法符号,商户侧需保持唯一性。
示例值: 89560002019101000121
公众账号ID appid string[1,128] body 微信为发券方商户分配的公众账号ID,接口传入的所有appid应该为公众号的appid(在mp.weixin.qq.com申请的),不能为APP的appid(在open.weixin.qq.com申请的)。
校验规则:
1、该appid需要与接口传入中的openid有对应关系;
2、该appid需要与调用接口的商户号(即请求头中的商户号)有绑定关系,若未绑定,可参考该指引完成绑定(商家商户号与AppID账号关联管理

示例值:wx233544546545989
创建批次的商户号 stock_creator_mchid string[1,20] body 批次创建方商户号。
校验规则:接口传入的批次号需由stock_creator_mchid所创建。
示例值:8956000
指定面额发券,面额 coupon_value uint64 body 指定面额发券场景,券面额,其他场景不需要填,单位:分。
校验规则:仅在发券时指定面额及门槛的场景才生效,常规发券场景请勿传入该信息。
示例值:100
指定面额发券,券门槛 coupon_minimum uint64 body 指定面额发券批次门槛,其他场景不需要,单位:分。
校验规则:仅在发券时指定面额及门槛的场景才生效,常规发券场景请勿传入该信息。
示例值:100

请求示例


{
  "stock_id": "9856000",
  "out_request_no": "89560002019101000121",
  "appid": "wx233544546545989",
  "stock_creator_mchid": "8956000"
}

    
{
JAVA示例代码
}
    

返回参数

参数名 变量 类型[长度限制] 必填 描述
代金券id coupon_id string[1,20] 发放给用户的代金券id。
示例值:9867041

返回示例


{
  "coupon_id": "9867041"
}
                                

    http://2323weixin.qq.com
                                

错误码公共错误码

状态码 错误码 描述 解决方案
400 PARAM_ERROR appid必填 请输入appid
PARAM_ERROR openid必填 请输入openid
PARAM_ERROR 批次号必填 请输入批次号
PARAM_ERROR 商户号必填 请输入商户号
PARAM_ERROR 非法的批次状态 请检查批次状态,仅支持发放状态为“运营中”的代金券批次
APPID_MCHID_NOT_MATCH 商户号与appid不匹配 调用接口的商户号需与接口传入的APPID有绑定关系,请参考常见问题Q4
INVALID_REQUEST openid与appID不匹配 openid与appid需有对应关系
INVALID_REQUEST 非法的商户号 请检查商户号准确性
INVALID_REQUEST 调用频率过高 请降低api调用频率
INVALID_REQUEST 活动已结束或未激活 请检查批次状态
403 MCH_NOT_EXISTS 商户号不合法 请检查商户号准确性
NOT_ENOUGH 批次预算不足 批次预算已发放完,请补充批次预算
NOT_ENOUGH 发券超过单天限额 已超过该批次设置的单天发放限制额度,无法发放
NOT_ENOUGH 账户余额不足,请充值 商户号余额不足,无法继续发券,请充值
RULE_LIMIT 用户已达最大领券次数 该用户已达到该批次的领取上限,请参考常见问题Q6
RULE_LIMIT 被自然人规则拦截 该自然人已达到该批次的领取上限,请参考常见问题Q6
USER_ACCOUNT_ABNORMAL 用户非法 用户命中微信支付风控模型,请参考常见问题Q5
REQUEST_BLOCKED 商户无权发券 该批次不支持其他商户发放,请参考常见问题Q1
REQUEST_BLOCKED 批次不支持跨商户发券 该批次不支持其他商户发放,请参考常见问题Q1
REQUEST_BLOCKED 用户被限领拦截 该用户已达到该批次的领取上限,请参考常见问题Q6
REQUEST_BLOCKED 不能在api渠道发放 请检查批次信息,仅支持发放微信支付代金券,不支持发放立减与折扣
REQUEST_BLOCKED 不支持指定面额发券 仅在发券时指定面额及门槛的场景才生效,常规发券场景请勿传入该信息
REQUEST_BLOCKED 仅在广告场景下发放批次 该批次已在朋友圈广告发放,不支持在其他渠道发放
404 RESOURCE_NOT_EXISTS 批次不存在 请检查批次及制券商户号信息
429 FREQUENCY_LIMIT_EXCEED 接口限频 请降低api调用频率

版本说明

关闭
V1.0
2019年09月27日
1. 发放代金券接口上线

技术咨询

反馈有奖