完成接入准备后，商家/服务商可根据本文指引快速接入商家券 上传自定义券码模式。

说明：

商家券 产品支持自研商家/服务商通过自研、代调用 模式调用 API 接入，各模式配置详情可查看 接入准备。

商家券 产品 上传自定义券码模式 支持沙箱调试，详情可查看沙箱调试。

上传自定义券码模式 创建的商家券活动，在商家小程序进行 券活动运营（券活动领取引导）、发券、券运营（已领券核销引导），最终完成核销。

支持通过引流转化（原“日常推广-优惠券”）推广到支付宝多个公域渠道等公域流量场景。

支持通过私域营销推广至商家小程序等私域流量场景。

支持通过支付有礼推广至私域流量场景。

接入支付宝门店（可选）

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

注意：

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

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

产品接入核心模块

订阅消息

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

商家/服务商创建、修改及用户领取商家券等场景的消息，支付宝会通过 From 蚂蚁消息服务向商家自研应用或第三方应用设置的应用网关地址，POST 方式推送异步通知消息。

若商家/服务商网络环境比较复杂，如：通过统一网关间连互联网，推荐使用网络兼容性更好的标准 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_UPLOAD表示上传自定义券码
voucher_available_scope_info	券可用范围
单品券：`voucher_available_scope_info.voucher_available_goods_inofo.goods_name`
全场券：不传`goods_name`即为全场优惠券
voucher_deduct_info	券优惠抵扣信息
`voucher_type` 券类型满减券: FIX_VOUCHER折扣券: DISCOUNT_VOUCHER特价券: SPECIAL_VOUCHER兑换券: EXCHANGE_VOUCHER满减券（FIX_VOUCHER）、折扣券（DISCOUNT_VOUCHER）支持配置为全场优惠券或单品优惠券。特价券（SPECIAL_VOUCHER）仅支持配置为单品优惠券。
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_mode=OFFLINE_CODE：线下扫码核销，商家券将在支付宝卡包中展示券码
use_guide_mode=MINI_APP：小程序核销，商家券将在支付宝卡包中展示去使用按钮，引导用户跳转至商家小程序页面（mini_app_use_guide_info.mini_app_url 小程序链接，mini_app_use_guide_info.mini_app_service_codes 小程序服务）

展示效果

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

第二步：上传券码

创建商家券活动成功后，商家/服务商可调用 alipay.marketing.activity.ordervoucher.codedeposit（同步商家券券码）将商家/服务商系统自定义的优惠券码上传至支付宝。用户领券时，支付宝将从中随机选取券码给用户。

注意：

本接口单次仅能导入 1000 个券码，支持循环或者并发导入券码，券码总量不能超过 500 万。

上传券码后，商家/服务商可通过alipay.marketing.activity.ordervoucher.codecount（统计商家券券码数量），查询有效券码数量是否符合预期。

创建商家券活动成功后，以 alipay.marketing.activity.message.created（券活动创建通知）为准（可查看上文 第一步：创建活动）才可上传券码。

第三步：提交库存

商家/服务商需调用 alipay.marketing.activity.ordervoucher.append（修改商家券活动发券数量上限）修改商家券活动券库存数量上限信息，提交并通过后商家券活动才会生效。

注意：

若创建商家券时 activity_base_info.code_mode=MERCHANT_UPLOAD，本接口 voucher_quantity 值需要与导入码的总数量保持一致。

本接口仅提交修改上限申请，结果需以alipay.marketing.activity.message.appended（券活动预算追加通知）为准，可查看下文 券活动消息通知 > 券活动库存数量上限修改通知。

券活动消息通知

第一步：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.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.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==

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

追加库存

若商家/服务商创建商家券成功后还希望增加商家券码数量，可通过上文 上传券码（活动时上传自定义券码模式必选）、提交库存 指引，传入需要追加库存的商家券 activity_id（活动 ID）、券码及库存信息进行操作。

接口时序图

注意：

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

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

追加券码后，商家/服务商可通过alipay.marketing.activity.ordervoucher.codecount（统计商家券券码数量），查询有效券码数量是否符合预期。

追加商家券码后还需通过 提交库存 完成追加预算操作。

商家券活动预算追加通知

消息示例

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方式接收券活动创建通知

消息示例

第二步：验签

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

券活动库存数量上限修改通知

消息示例

推广商家券

引流转化

私域营销

支付有礼

领取商家券

商家券领取通知

消息示例

使用商家券

接口时序图

核销商家券

管理商家券活动

修改活动

券活动修改通知

消息示例

追加库存

接口时序图

商家券活动预算追加通知

消息示例

停止发券

券活动停止消息通知

消息示例

退回商家券