摇优惠-商家券开发指引

更新时间：2025.05.29

1、开发前准备

1.1、设置安全联系人

微信支付日常安全监测发现技术异常时，会向安全联系人和超级管理员发送风险提醒。请商户超级管理员尽快设置技术同事为安全联系人，确保能及时接收异常信息评估业务风险，详见安全联系人设置指引。

1.2、熟悉微信支付接口规则

正式进入开发前，开发者需要先阅读基本规则、签名和验签规则了解调用微信支付接口的基本规则和签名规则。

1.3、准备开发参数

在发起接口请求时，开发者需传入必要参数，如商户号、appid、密钥及证书序列号等，获取方式详见：普通商户模式开发必要参数说明。

注意

服务商模式下，参数结构与普通商户模式有区别，其中请求参数中增加了子商户号、子商户appid等信息，具体请参考：服务商模式开发必要参数说明。

2、详细开发指引

注意

摇一摇有优惠的具体开放准入要求可与对接行业运营负责人了解。
商家若是线下场景有涉及品牌门店的使用情况下，为了提供更加精准的POI推荐，建议使用门店功能，即在下单接口（例如JSAPI支付/小程序支付/APP支付/H5支付）回传门店信息到store_info，有关商家如何获取门店信息请参考《品牌门店开发指引》。

2.1接入必要接口

商家必须要实现以下的接口接入。

创建商家券批次

需在商家内部系统中根据业务需求制作商家券优惠批次，可通过「创建商家券」接口创建商家券，微信支付生成商家券批次后并返回商家券批次号给到商家。

注意

满足以下条件的券批次才可创建「摇一摇有优惠」活动，商家侧需要做兼容处理：

【批次类型】若摇优惠活动为单品类型（例如单个商品优惠，或N个商品多选一优惠），则商家券批次类型必须是换购券(EXCHANGE)。若是全场类型活动，则商家券批次类型必须是固定面额满减券（NORMAL）或折扣券（DISCOUNT）。
【发放规则】券的批次剩余个数stock_send_rule.max_coupons需>=1万。
【发放规则】不允许设置stock_send_rule.max_coupons_by_day单天发放个数限制。
【核销规则】核销方式coupon_use_rule.use_method必须为线上小程序核销（MINI_PROGRAMS）。
【券code模式】创建商家券批次时目前仅支持系统分配code模式（WECHATPAY_MODE）和预存code模式（MERCHANT_UPLOAD），不支持商户发放时指定券code模式。（MERCHANT_API）。
【事件通知配置】notify_config.notify_appid字段为必填项，用于回调通知时，计算返回操作用户的OpenID（诸如领券用户），支持小程序or公众号的AppID。

创建回调地址

适用于设置接收商家券相关事件通知的URL，可接收摇一摇有优惠的领券事件通知。

需要设置接收通知的URL，并在商户平台开通营销事件推送的能力，即可接收到相关通知。具体指引可参考「设置商家券回调地址」

领券回调

用户在领券完成后，微信将领券结果和用户信息发送给商家。具体的回调通知字段参考「领券事件回调通知」。

对领券回调 resource 对象进行解密后，得到的资源对象示例：

1{   
2    "event_type":"EVENT_TYPE_BUSICOUPON_SEND",
3    "coupon_code":"1227944959000000911017",
4    "stock_id":"1286950000000039",
5    "send_time":"2019-12-17T10:35:53+08:00",
6    "openid":"odXnH1CJjeQoWTld48db-pnxs-Wg",
7    "unionid":"oOuyajgxj0oVwjocSoQm6mp7PGKw",
8    "send_channel":"BUSICOUPON_SEND_CHANNEL_SHAKE", 
9    "send_merchant":"98568888",
10  	"act_id":"1234",
11  	"attach_info":""
12}

注意

如需测试回调通知逻辑，请使用H5/小程序发券插件；
如需测试摇一摇逻辑，需要实现全部接口逻辑后，找对接的运营同事协助代发起摇一摇测试活动，体验摇一摇领券。

针对摇一摇领券事件回调，字段变动说明如下：

字段名	描述
send_channel	BUSICOUPON_SEND_CHANNEL_SHAKE，摇一摇领券对应的枚举值
act_id	字符串类型，对应微信支付后台创建的摇一摇活动ID

创建摇一摇活动

当前摇一摇活动为微信支付行业运营代创建，商家需同步优惠券批次、商品信息、投放信息至行业运营，由行业运营统一进行活动的创建和管理，具体可以参考《提报批次、商品和活动信息》。如需帮助，请联系与贵司对接的微信支付行业运营负责人。

用户核销（核销商家券&支付下单&关联订单API）

用户在下单时勾选使用商家券后，商家需调用「关联订单信息」接口将券与订单信息关联，以便后续参与摇奖和返佣激励等统计操作，关联成功后，再调用「核销用户的券」进行核销，并且进行后续的下单支付流程。

注意

关联订单时，券必须为未核销状态。商家应先关联订单信息，然后核销用户的券。核销成功后，再进行下单唤起实际支付的流程。
关联订单信息传入的商户单号需要与实际支付时下单的商户单号保持一致。
若商家的使用场景涉及品牌门店时，建议在对应的下单接口（例如JSAPI支付/小程序支付/APP支付/H5支付）回传门店信息到store_info字段中。如何获取有关的门店信息可参考：《品牌门店开发指引》。

取消关联订单信息

若用户未成功下单或已支付订单出现需要取消或关联错误的单号、券的情况下，商家可以调用该「取消关联订单信息」接口，解除已关联的商家券与订单信息的关系。

注意

建议取消前调用查询接口，查到当前关联的商户单号并确认后，再进行取消操作，可以通过「根据过滤条件查询用户的券/查询用户券详情」接口查询到的关联商户订单号（associate_out_trade_no）确认。

申请退券

针对用户已核销的券需要进行退券的流程时，商家需要在退款之后调用「申请退券」接口，接口调用成功后，券在用户卡包内正常展示，摇一摇会场对应的券状态同步修改为可核销，用户仍可在有效期内正常使用该优惠券，若用户的券在过期状态下退款，可不用调用该退券API。

查询批次详情

商家可通过该「查询商家券批次详情」接口查询已创建的商家券批次详情信息。

修改预算

当商家有需求，需要修改批次对应的单天发放上限数量或者批次最大发放数量或后续活动调整预算时，可以通过调用「修改批次预算」接口进行修改。

修改商家券信息

当商家有需求，需要修改商家券的基本信息内容时，例如券的适用商品范围、核销规则等信息，建议接入该接口。商家可以通过调用「修改商家券基本信息」接口进行修改。

2.2根据场景可选接入的接口

以下接口，建议商家应根据自身业务场景，进行接入。

按条件过滤用户的券

用户在进入商家小程序进行准备使用商家券的情况下，商家需要调用「根据过滤条件查询用户的券」查询当前用户名下拥有的商家券信息，用于计算用户当前优惠信息。

上传预存code信息

当商家在创建批次券的时候，如商家已有自己的优惠券系统，需要使用自己业务的code码时，可以选择为预存CODE（MERCHANT_UPLOAD）的模式。此时，商家需要先调用该「上传预存CODE」接口上传信息

注意

当券在发放时，微信支付自动从已导入的code中随机取值（不能指定），派发给用户。

使券失效

当商家发现用户领取的券存在错误说明或使用时间不准确等情况时，可以通过调用「使券失效」接口来进行券的失效设置。

注意

失效接口仅支持单个批次和单个券code码。如果需要失效多个批次的券code码，商家需进行多次请求。

文档是否有帮助

更多支持

开发文档(服务商)开发文档(V2版)开发者社区微信开放平台微信公众平台腾讯客服