开发指引
更新时间：2025.04.111、开发前准备
1.1、设置安全联系人
微信支付日常安全监测发现技术异常时，会向安全联系人和超级管理员发送风险提醒。请商户超级管理员尽快设置技术同事为安全联系人，确保能及时接收异常信息评估业务风险，详见安全联系人设置指引。
1.2、熟悉微信支付接口规则
1.3、准备开发参数
在发起接口请求时，开发者需传入必要参数，如商户号、appid、密钥及证书序列号等，获取方式详见：普通商户模式开发必要参数说明。
2.整体业务开发流程概览
3. 业务流程图
业务流程时序图
|
4.详细步骤说明
4.1. 创建商家券
商户可以通过该接口创建商家券。微信支付生成商家券批次后并返回商家券批次号给到商户，商户可调用小程序发券、H5发券接口发放该批次商家券。
通过创建商家券接口生成商家券批次号，支持满减券、换购券、折扣券三种类型。
必填参数包括券名称、面额、使用门槛、有效期、适用商品，商户LOGO需通过-图片上传(营销专用)接口获取。
创券接口关键参数说明：
stock_name：商家券批次名称。
belong_merchant：商家券批次归属商户号。
coupon_use_rule.coupon_available_time.available_begin_time：商家券批次开始时间，遵循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秒。
coupon_use_rule.coupon_available_time.available_end_time：商家券批次结束时间，遵循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秒。
stock_send_rule.max_coupons：商家券批次最多发放次数。
stock_send_rule.max_coupons_per_user：活动期间每个用户可领个数，当开启了自然人限领（stock_send_rule.natural_person_limit=true）时，多个微信号同属于一个身份证时会视为同一用户。
stock_send_rule.max_amount：最大发券预算，当营销经费no_cash选择预充值false时，激活批次时会从制券商户的余额中扣除预算，请保证账户金额充足，单位：分max_amount需要等于coupon_amount（面额） × max_coupons（发放总上限）。
stock_send_rule.prevent_api_abuse：是否开启防刷拦截，若开启防刷拦截，当用户命中恶意、小号、机器、羊毛党、黑产等风险行为时，无法成功发放商家券。
商家券样式图
4.2 商户发券和用户领券
1、摇一摇有优惠是一种线下场景营销工具，通过摇一摇活动，即时发放商家券，为商户提供低成本、高互动性的用户触达方式，进一步降低营销门槛，提升线下流量转化效率。
具体请参考摇一摇有优惠
2、支付有礼是面向符合条件的微信支付商户开放的营销能力，用户在商家使用微信支付后可以领取微信支付代金券，下次回店消费只要符合用券条件即可自动抵扣优惠，能有效帮助商户拉动顾客二次购买或完成线下门店－线上商城的连接。
具体请参考支付有礼
4.3 查询商家券批次详情
商户可通过该接口查询已创建的商家券批次详情信息。
4.4 上传预存code
商家券的code码可由微信后台随机分配，同时支持商户自定义。如商家已有自己的优惠券系统，可直接使用自定义模式。即商家预先向微信支付上传券code，当券在发放时，微信支付自动从已导入的code中随机取值（不能指定），派发给用户。
4.5 核销用户的券
在用户满足优惠门槛后，商户可通过核销用户的券接口核销用户微信卡包中具体某一张商家券。
调用核销用户的券接口，传入用户OpenID、券批次号及券码完成核销。
需确保制券商户号与核销商户号一致，且用户AppID与券配置匹配。
4.6 根据过滤条件查询用户的券
商户自定义筛选条件（如创建商户号、归属商户号、发放商户号等），查询指定微信用户卡包中满足对应条件的所有商家券信息。
4.7 查询用户券详情
商户可通过该接口查询微信用户卡包中某一张商家券的详情信息。
4.8 设置商家券事件通知地址
用于设置接收商家券相关事件通知的URL，可接收商家券相关的事件通知、包括发放通知等。需要设置接收通知的URL，并在商户平台开通营销事件推送的能力，即可接收到相关通知。
营销事件推送：点击开通产品权限。由商家券批次创建方登录商户平台，操作开通
营销事件推送
配置回调URL
在商户平台开通营销事件推送权限，设置接收商家券发放、核销等通知的URL。
支持实时处理业务回调，如发放成功通知、核销成功通知等。
开通营销事件推送能力
开通营销事件推送能力说明：
用于设置接收商家券相关事件通知的URL，可接收商家券相关的事件通知（商家/服务商创建、修改及用户领取商家券等场景的消息）。
微信会通过商户设置的商家券事件通知地址向商家设置的应用网关地址，POST 方式推送异步通知消息。设置商家券事件通知地址
营销事件推送：点击开通产品权限。 由商家券批次创建方登录商户平台，操作开通
|
4.9 获取商家券事件通知地址
使用场景：用于查询设置的通知URL
限制条件：仅可以查询由请求商户号设置的商家券通知URL
4.10 关联订单信息
适用场景：将有效态（未核销）的商家券与订单信息关联，用于后续参与摇奖&返佣激励等操作的统计
前置条件：已为用户发券，且调用查询接口查到用户的券code、批次ID等信息
注意事项：仅对有关联订单需求的券进行该操作
是否支持幂等：是
4.11 取消关联订单信息
适用场景：取消商家券与订单信息的关联关系
前置条件：已调用关联接口为券创建过关联关系
注意事项：建议取消前调用查询接口，查到当前关联的商户单号并确认后，再进行取消操作
是否支持幂等：是
4.12 修改批次预算
商户可以通过该接口修改批次单天发放上限数量或者批次最大发放数量
4.13 修改商家券基本信息
商户可以通过该接口修改商家券基本信息
前置条件： 已创建商家券批次，且修改时间位于有效期结束时间前
4.14 申请退券
商户可以在退款之后调用退券API，调用了该接口后，券在用户卡包内正常展示，用户可在有效期内正常使用该优惠券。
若券过期状态下退款，可不用调用该退券API。
前置条件：券的状态为USED
4.15 使券失效
失效一张券，券被失效后无法再被核销
4.16 图片上传（营销专用）
通过本接口上传图片后可获得图片url地址。图片url可在微信支付营销相关的API使用，包括商家券、代金券、支付有礼等。
4.17 领券事件回调通知
回调URL： 该链接是通过设置商家券事件通知地址API提交notify_url参数设置，必须为HTTPS协议。如果链接无法访问，商户将无法接收到微信通知。 通知URL必须为直接可访问的URL，不能携带参数。
通知规则
领券完成后，微信会把相关领券结果和用户信息发送给商户，商户需要接收处理，并按照文档规范返回应答。出于安全的考虑，我们对支付结果数据进行了加密，商户需要先对通知数据进行解密，才能得到支付结果数据。
对后台通知交互时，如果微信收到应答不是成功或超时，微信认为通知失败，微信会通过一定的策略定期重新发起通知，尽可能提高通知的成功率，但微信不保证通知最终能成功。（通知频率为60s/次 - 总计11次 ）
通知报文
领券结果通知是以POST 方法访问商户设置的通知URL，通知的数据以JSON 格式通过请求主体（BODY）传输。通知的数据包括了加密的支付结果详情。
|
4.18 合规与风险控制
合规性要求
券有效期不得短于7天，禁止使用“最低价”等夸大宣传词汇。
核销需限制单用户领取数量（如每人限领5张）。
风险监控
监控接口调用频率，异常交易需及时回传数据并排查。
总结
商家券开发流程可概括为：创建批次→发放→核销→管理→事件推送。建议优先完成小程序发券插件集成和营销事件配置，再根据业务需求选择券类型（满减/折扣/换购）
5、商家券批次和券状态流转图
商家券批次：
1、商户调用创建商家批次接口成功后，商户可以调用查询商家券批次详情接口来确认批次状态。
2、当批次状态处于未审核(UNAUDIT)时，微信侧会对批次进行审核，若审核失败，批次创建失败。
3、当微信侧成功审核批次后，批次状态会从未审核(UNAUDIT)流转为运行中(RUNNING)。
4、商户可在批次创建后对运行中的批次调用修改商家券基本信息接口，使批次暂停发放。暂停批次后，批次状态会从运行中(RUNNING)流转为暂停发放(PAUSED)。
5、当批次状态为运行中(RUNNING)时，如果批次可用时间到期，微信侧会自动终止批次，批次状态会从运行中(RUNNING)流转为已停止(STOPED)。
6、此状态为终态：STOPPED。
商家券：
1、商户调用创建商家批次接口成功后，商户可以调用查询用户券详情接口来确认券状态。
2、当批次创建成功后，券状态会流转为可用(SENDED)。
3、当券被成功核销后，券状态会从未可用(SENDED)流转为已核销(USED)。
4、商户可在批次创建后对可用的券调用使券失效接口，使券失效。券失效后，券券状态会从可用(SENDED)流转为已失效(DEACTIVATED)。
5、当券状态为可用(SENDED)时，如果券可用时间到期，微信侧会自动终止券，券券状态会从可用(SENDED)流转为已过期(EXPIRED)。
6、当券状态为可用(SENDED)时，如果券被删除，券状态会从可用(SENDED)流转为已删除(DELETED)如果券被删除，券状态会从可用(SENDED)流转为已删除(DELETED)。
7、以下状态为终态：USED、EXPIRED、DELETED、DEACTIVATED。
