发券时指定券码模式指商家/服务商通过在支付宝平台创建商家券活动，通过私域营销产品推广至商家小程序，在商家小程序进行 券活动运营（券活动领取引导）、发券、券运营（已领券核销引导），同步核销券状态 到支付宝

说明：此模式暂不支持沙箱调试。

接入支付宝门店（可选）

支付宝提供了蚂蚁门店管理产品，商家/服务商可通过接口创建支付宝门店获取门店 ID（shop_id）并进行门店管理，后续可支持商家券在指定的应门店进行核销。

注意：

服务商需引导商家完成产品开通。

商家券场景下创建门店时，必须传入 business_address.longitude（经度）及 business_address.latitude（纬度）且使用高德经纬度查询，否则商家券无法在支付宝投放展示。

订阅消息

设置接收消息的应用网关地址

商家/服务商创建、修改及用户领取商家券等场景，支付宝都将通过 From 蚂蚁消息服务向商家应用或第三方应用应用网关推送异步通知消息，同步对应操作结果。

若商家/服务商网络环境比较复杂，如：通过统一网关间连互联网，推荐使用网络兼容性更好的标准 http(s) 协议进行对接。

订阅消息接口

商家/服务商需根据订阅消息指引，为接入商家券的 商家应用 或 第三方应用 订阅如下消息接口。

注意：

仅完成订阅后才会收到支付宝发送的对应异步通知消息。

商家/服务商可通过消息通知中 msg_method 参数判断消息类型。

消息接口英文名	消息接口中文名	作用
alipay.marketing.activity.message.created	商家券活动创建通知	同步商家券活动创建结果。
alipay.marketing.activity.message.appended	商家券活动库存追加通知	同步商家券活动库存追加结果。
alipay.marketing.activity.message.modified	商家券活动修改通知	同步商家券活动修改结果。
alipay.marketing.activity.message.stopped	商家券活动停止通知	同步商家券领取停止结果。
alipay.marketing.activity.message.received	商家券领取通知	同步用户领取商家券及对应券码信息。

接入商家券

接口时序图

创建商家券活动

商家/服务商需调用 alipay.marketing.activity.ordervoucher.create（创建商家券活动）创建活动（支持创建满减券、折扣券、特价券），获取 activity_id（活动 ID）。不同券类型优惠规则说明可查看商家券类型。

示例代码

完整的 JSON 数据可复制+请求

重要入参说明：

参数名称	参数说明
out_biz_no	商户创建券活动外部编号，确保唯一
merchant_access_mode	商户接入模式：商户自接入模式：SELF_MODE服务商代接入模式：AGENCY_MODE
activity_base_info	活动基础信息 activity_base_info.code_mode=MERCHANT_API 发券时指定券码
voucher_send_mode_info.voucher_send_rule_info	券发放规则
`voucher_send_rule_info.voucher_quantity` 必须大于 0，用于指定当前发放预算总数。
voucher_available_scope_info	券可用范围
单品券：`voucher_available_scope_info.voucher_available_goods_info.goods_name`
全场券：不传 `goods_name` 即为全场优惠券
voucher_use_rule_info.voucher_use_time_info	券核销限制，券核销时间
`period_type`券有效期类型period_type = ABSOLUTE （绝对时间）；period_type = RELATIVE（相对时间）券绝对时间和券相对时间二选一
voucher_use_rule_info.voucher_use_time_info.absolute_period_info	若 period_type = ABSOLUTE（绝对时间），券可核销有效期以 `[ absolute_period_info.valid_begin_time,absolute_period_info.valid_end_time ]` 区间为准。
voucher_use_rule_info.voucher_use_time_info.relative_period_info	若 period_type = RELATIVE（相对时间），券可核销有效期以 alipay.marketing.activity.message.received（商家券领取通知接口）中 event_time （领券时间，精确到秒）加本接口设置的有效时间规则（精确到天）为准： `event_time + relative_period_info.wait_days_after_receive`，event_time + relative_period_info.wait_days_after_receive +``relative_period_info.valid_days_after_receive
voucher_customer_guide_info.voucher_use_guide_info	券引导详情，券核销引导
use_guide_mpde=OFFLINE_CODE ：线下扫码核销，商家券将在支付宝卡包中展示券码
use_guide_mpde=MINI_APP：小程序核销，商家券将在支付宝卡包中展示“去使用”按钮，引导用户跳转至商家小程序页面（mini_app_use_guide_info.mini_app_url 小程序链接，mini_app_use_guide_info.mini_app_service_codes 小程序服务）

展示效果

alipay.marketing.activity.ordervoucher.create（创建商家券活动接口）对应参数展示效果如下图所示。

券活动消息通知

第一步：POST方式接收活动创建通知

商家/服务商发起的商家券创建完成后，支付宝将通过 alipay.marketing.activity.message.created（券活动创建通知）发送活动创建成功时间等信息给商家/服务商。

消息示例

ISV_GATEWAY_URL?charset=GBK&biz_content=
{
"id":"CREATED_2021042400826001508407723739","activity_id":"2016042700826004508401111111","event_time":"12342425435232423","out_biz_no":"abscd123341"
}
&msg_method=alipay.marketing.activity.message.created&utc_timestamp=1516797622752&version=1.1&sign_type=RSA2&notify_id=d275fec564e62af6bedbcee73f3f05fi5x&app_id=2013121700999429&sign=I+Y/lvqYUEEc10EPdpntRhFIQ==

第二步：验签

商家/服务商可使用支付宝 SDK 可根据数据验签指引，使用应用密钥信息验证异步通知消息来源是否为支付宝。

第三步：反馈消息接收结果

收到异步通知完成验签后，商家/服务商需返回 success 这 7 个字符给支付宝，表示消息获取成功，支付宝就会停止发送异步通知。如果返回 fail 或其它值，表示消息获取失败，支付宝会根据投递重试策略重新发送消息到应用网关地址。

**说明：**完成异步通知验签时，如果验签成功返回 success 这 7 个字符，验签失败返回 fail，重新接收异步进行处理。

响应值	描述	是否重试
fail	消息获取失败	重试
success	消息获取成功	不重试

推广商家券

商家/服务商接入并验收商家券产品后，可通过私域营销产品在商家小程序中进行营销推广。

注意：发券时指定券码 模式生成的商家券仅支持在商家小程序推广。

领取商家券

本流程简单描述商家/服务商接入并验收商家券产品后，使用领券插件领取商家券，具体操作查看私域营销接入指南。

用户端流程示例

商家券领取通知

用户在支付宝推广渠道领取商家券时，支付宝将通过alipay.marketing.activity.message.received（券领取通知）发送领券用户 user_id（支付宝用户 ID）、voucher_code（优惠券码）等信息给商家/服务商。

消息示例

ISV_GATEWAY_URL?charset=GBK&biz_content=
{
"id":"RECEIVED_2021042400826001508407723739","activity_id":"2016042700826004508401111111","event_time":"1619338271","voucher_code":"voucher_code","receive_user_id":"2088xxxxx"
}
&msg_method=alipay.marketing.activity.message.received&utc_timestamp=1516797622752&version=1.1&sign_type=RSA2&notify_id=d275fec564e62af6bedbcee73f3f05fi5x&app_id=2013121700999429&sign=I+Y/lvqYUEEc10EPdpntRhFIQ==

**注意：**消息处理可查看券活动消息通知。

使用商家券

用户领取商家券后，支付宝将通过异步通知发送券码等信息给商家/服务商。商家/服务商可按如下指引调用接口，接入商家券核销等操作。

接口时序图

核销商家券

用户使用商家券进行支付后，商家/服务商需在自身系统核销优惠券，同时调用alipay.marketing.activity.ordervoucher.use（同步券核销状态）通知支付宝核销优惠券。接口将同步返回核销结果，支付宝同步切换用户卡包中优惠券状态为 已核销。

注意：

优惠券核销时间以 biz_dt（外部优惠券的核销时间）为准。

终止商家券活动 或 用户手动删除卡包中的商家券 后，已领取的商家券在有效范围内仍可核销。

管理商家券活动

商家/服务商可按如下指引调用接口，接入商家券 修改活动、追加预算、停止发券、退回券 操作。

修改活动

商家/服务商可调用alipay.marketing.activity.ordervoucher.modify（修改商家券活动基本信息）延长商家券活动领取结束日期、增加支持门店等。

重要入参说明：

参数名称	参数说明
voucher_available_scope_info.voucher_available_geography_scope_info.available_geography_shop_info	券可用范围，券可用地理位置,有两种门店模式，创建指定模式后，修改时不可切换模式
`available_shop_ids` 券可用门店列表
`available_geography_all_shop.exclude_shop_ids` 券不可使用的门店列表
voucher_available_scope_modify_type	修改可用范围类型
voucher_available_scope_modify_type=MODIFY_ALL则代表覆盖修改全量门店，门店不可减少，传入本参数后支付宝将在已有门店列表基础上去重、新增，未传本参数则保持不变
voucher_available_scope_modify_type=ADD，则代表追加修改，原有门店数量不变，增量追加
voucher_available_scope_modify_type=REMOVE，则代表减少修改，原有门店数量增量减少
voucher_send_mode_info.voucher_send_rule_info	券发放模式信息详情,券发放规则
`voucher_send_rule_info.publish_end_time`券发放结束时间，仅支持延期，不支持提前结束。

券活动修改通知

商家/服务商发起的商家券活动修改完成后，支付宝将通过 alipay.marketing.activity.message.modified（券活动修改通知）发送活动修改成功时间等信息给商家/服务商。

消息示例

ISV_GATEWAY_URL?charset=GBK&biz_content=
{
"id":"MODIFIED_2021042400826001508407723739","activity_id":"2016042700826004508401111111","event_time":"1619338271","out_biz_no":"abscd123341"
}
&msg_method=alipay.marketing.activity.message.modified&utc_timestamp=1516797622752&version=1.1&sign_type=RSA2&notify_id=d275fec564e62af6bedbcee73f3f05fi5x&app_id=2013121700999429&sign=I+Y/lvqYUEEc10EPdpntRhFIQ==

**注意：**消息处理可查看券活动消息通知。

追加库存

若商家/服务商创建商家券成功后还希望增加商家券码数量，可通过alipay.marketing.activity.ordervoucher.append（修改商家券活动发券数量上限）接口传入需要追加库存的商家券 activity_id（活动 ID）、及库存信息进行操作。

接口时序图

注意：

仅支持 创建成功（即接收到 alipay.marketing.activity.message.created（券活动创建通知）通知）、未过期、未停止 的活动追加商家券发券上限，以此追加活动预算。

本接口 voucher_quantity 表示追加以后的券的总数量。例如，活动本来发放 200 张券，现需追加 100 张，总共发放 300 张券，则 voucher_quantity 应传入 300。

上传后，可通过 alipay.marketing.activity.ordervoucher.query（查询商家券活动），查询 voucher_send_rule_info.quantity 有效券码数量是否符合预期。

商家券活动预算追加通知

商家/服务商发起的商家券库存数量上限修改完成后，支付宝将通过alipay.marketing.activity.message.appended（券活动预算追加通知）发送通过时间等信息给商家/服务商。

消息示例

ISV_GATEWAY_URL?charset=GBK&biz_content=
{
"id":"APPENDED_2021042400826001508407723739","activity_id":"2016042700826004508401111111","event_time":"1619338271","out_biz_no":"20210420cy2112xzyx010"
}
&msg_method=alipay.marketing.activity.message.appended&utc_timestamp=1516797622752&version=1.1&sign_type=RSA2&notify_id=d275fec564e62af6bedbcee73f3f05fi5x&app_id=2013121700999429&sign=I+Y/lvqYUEEc10EPdpntRhFIQ==

**注意：**消息处理可查看券活动消息通知。

停止发券

若商家券活动开始后，商家需提前停止活动。商家/服务商可调用 alipay.marketing.activity.ordervoucher.stop（停止商家券活动）停止发券，支付宝将同步在各领券展示渠道隐藏对应券信息，并切换商家券活动状态为 FINISHED（已停止）。

注意：

停止发券后用户不能再领券，已停止的活动不能重新激活。

券活动停止通知

商家/服务商发起的停止发券完成后，支付宝将通过 alipay.marketing.activity.message.stopped（券活动停止通知）发送停止发券时间等信息给商家/服务商。

消息示例

ISV_GATEWAY_URL?charset=GBK&biz_content=
{
"id":"STOPPED_2021042400826001508407723739","activity_id":"2016042700826004508401111111","event_time":"12342425435232423","out_biz_no":"abscd123341"
}
&msg_method=alipay.marketing.activity.message.stopped&utc_timestamp=1516797622752&version=1.1&sign_type=RSA2&notify_id=d275fec564e62af6bedbcee73f3f05fi5x&app_id=2013121700999429&sign=I+Y/lvqYUEEc10EPdpntRhFIQ==

**注意：**消息处理可查看券活动消息通知。

退回商家券

若用户使用优惠券完成支付后发起退款操作，商家/服务商可调用alipay.marketing.activity.ordervoucher.refund（取消券核销状态）在退款时进行退券，接口将同步返回退券结果。

注意：

仅支持 已核销 的券进行退券操作。

如果优惠券过期后，发起退券操作，该接口返回成功，优惠券退回后仍不可用。

如果优惠券在支付宝卡包已删除，发起退券操作，该接口返回成功，优惠券在支付宝卡包仍然是删除状态。

发券时指定券码模式

接入支付宝门店（可选）#

订阅消息#

设置接收消息的应用网关地址#

订阅消息接口#

接入商家券#

接口时序图#

创建商家券活动#

示例代码#

展示效果#

券活动消息通知#

第一步：POST方式接收活动创建通知#

消息示例#

第二步：验签#

第三步：反馈消息接收结果#

推广商家券#

领取商家券#

用户端流程示例#

商家券领取通知#

消息示例#

使用商家券#

接口时序图#

#

核销商家券#

管理商家券活动#

修改活动#

券活动修改通知#

消息示例#

追加库存#

接口时序图#

商家券活动预算追加通知#

消息示例#

停止发券#

券活动停止通知#

消息示例#

退回商家券#

接入支付宝门店（可选）

订阅消息

设置接收消息的应用网关地址

订阅消息接口

接入商家券

接口时序图

创建商家券活动

示例代码

展示效果

券活动消息通知

第一步：POST方式接收活动创建通知

消息示例

第二步：验签

第三步：反馈消息接收结果

推广商家券

领取商家券

用户端流程示例

商家券领取通知

消息示例

使用商家券

接口时序图

核销商家券

管理商家券活动

修改活动

券活动修改通知

消息示例

追加库存

接口时序图

商家券活动预算追加通知

消息示例

停止发券

券活动停止通知

消息示例

退回商家券