完成接入准备后，商家/服务商可根据本文指引快速接入 支付券 产品。

说明：

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

支付券 支持沙箱调试。

完整接口时序图

接入支付宝门店（可选）

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

**注意：**接入蚂蚁门店管理产品：

服务商 需根据代商家接入说明完成开通产品、代运营授权。

不支持 服务商 自调用，需通过代调用 OpenAPI（传入 app_auth_token）方式接入。

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

接入支付券

创建支付券

商家/服务商可按以下指引调用接口，接入支付券，进行创建、激活操作。

商家/服务商调用 alipay.marketing.activity.voucher.create（创建支付券）创建成功后可获取到 activity_id（支付券活动 ID），此时支付券为“已创建”(草稿)状态，需要激活后才可发放使用。

注意：

券的图片需要通过调用 alipay.marketing.material.image.upload（营销图片资源上传接口）上传， voucher_display_info#voucher_image（券详情页封面图）对应 file_key 为 PROMO_VOUCHER_IMAGE ，voucher_display_info#voucher_detail_images (券详细图列表) 对应 file_key 为 PROMO_VOUCHER_DETAIL_IMAGE。

券核销规则的有效期计算逻辑，可通过 voucher_use_rule#voucher_valid_period（日期区间内可以使用优惠）参数控制：

type = ABSOLUTE （绝对时间）时，券可核销有效期以 [ valid_begin_time,valid_end_time ] 区间为准。

type = RELATIVE（相对时间）时，券可核销有效期以 alipay.marketing.activity.message.received（券领取通知）中 event_time（领券时间，精确到秒）加本接口设置的有效时间规则（精确到天）为准： [ event_time + wait_days_after_receive,event_time + wait_days_after_receive + valid_days_after_receive ]。

激活支付券

商家/服务商需调用 alipay.marketing.activity.voucher.publish（激活支付券）对 已创建（草稿）状态的支付券进行激活。

注意：

如果创建券时选择过 voucher_budget_supply_info.budget_type = RECHARGE 预充值，调用 alipay.marketing.activity.voucher.publish（激活支付券）会返回充值链接，制券方需点击此链接完成充值（充值链接有效期 3 天，超期未支付需重新调用激活接口获取新充值链接）。

激活支付券接口仅提交激活支付券活动申请，结果需以 alipay.marketing.activity.message.created（券活动创建通知）异步通知为准，可查看下文 消息通知 > 支付券通知 > 活动发布通知。

展示效果

alipay.marketing.activity.voucher.create（创建支付券）对应参数展示效果如下图所示。

管理支付券活动

商家/服务商可按如下指引调用接口，接入支付券 查询活动详情，修改活动，追加活动预算，终止支付券 操作。

修改支付券

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

注意：

修改仅适用于发布后修改，活动发布前草稿态，商家/服务商自行保存在本地。

创建时配置了shop_ids（门店列表）修改时才允许修改门店，创建时未配置 shop_ids（门店列表）修改时不允许修改门店。

shop_ids（门店列表）只允许增加不允许减少。传入本参数后支付宝将在已有门店列表基础上去重、新增，未传本参数则保持不变。券核销规则中的支付券可使用范围。

publish_end_time（券发放结束时间）只能延期，不能提前结束。

本接口仅提交修改支付券活动申请，结果需以 alipay.marketing.activity.message.modified（券活动修改通知）异步通知为准，可查看下文 消息通知 > 支付券通知 > 活动修改通知。

追加预算

商家/服务商需调用 alipay.marketing.activity.voucher.append（追加支付券预算）提交支付券预算信息，完成预算追加操作。

注意：

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

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

如果创建券时选择过 voucher_budget_supply_info.budget_type = RECHARGE 预充值，调用 alipay.marketing.activity.voucher.append（追加支付券预算）会返回充值链接，制券方需点击此链接完成充值（充值链接有效期 3 天，超期未支付需重新调用追加预算接口获取新充值链接）。

本接口仅提交预算申请，结果需以 alipay.marketing.activity.message.appended（券活动预算追加通知）异步通知为准，可查看下文 消息通知 > 支付券通知 > 追加预算通知。

追加前后可通过 alipay.marketing.activity.voucher.query（查询支付券详情）返回的 voucher_send_rule_info#quantity 查看券活动总数量。

终止发券

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

注意：

本接口仅提交终止支付券活动申请，结果需以 alipay.marketing.activity.message.stopped（券活动停止通知）的通知内容为准，可查看下文 消息通知 > 支付券消息通知 > 终止发券通知。

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

推广支付券

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

领取券

用户领取支付券后，支付宝将通过异步通知发送领取信息给商家/服务商。

领取支付券

商家/服务商需根据私域营销产品指引，使用 领券组件插件 引导用户在小程序中领取支付券。

用户端流程示例

核销支付券

用户领取券后，可以通过支付宝收款渠道（付款码/小程序等）进行券核销，支付宝同步切换用户卡包中优惠券状态为 已核销。

注意：

优惠券核销与否，以商家设置核销规则为准。

终止支付券活动 ，已领取的支付券在有效范围内仍可核销。

用户手动删除卡包中的支付券 后，则该券不可核销。

消息通知

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

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

第一步：订阅消息

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

注意：

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

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

消息接口（英文/中文名）	作用
alipay.marketing.activity.message.created（券活动创建通知）	同步支付券活动发布结果。
alipay.marketing.activity.message.modified（券活动修改通知）	同步支付券活动修改结果。
alipay.marketing.activity.message.appended（券活动预算追加通知）	同步支付券活动预算追加结果。
alipay.marketing.activity.message.stopped（券活动停止通知）	同步支付券活动终止结果。
alipay.marketing.activity.message.received（券领取通知）	同步支付券用户领取结果。
alipay.marketing.activity.message.used（券核销消息）	同步支付券用户核销结果。

第二步：验签

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

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

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

**说明：**在接收异步进行验签，如果验签成功输出 success，验签失败返回 fail，重新接收异步进行处理。

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

支付券消息通知

活动发布通知

商家/服务商发起的支付券发布成功后，支付宝将通过 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==

追加预算通知

商家/服务商发起的支付券活动发券数量上限修改成功后，支付宝将通过 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.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.message.received（券领取通知）发送领券用户 user_id（支付宝用户 ID）、voucher_id（优惠券ID）等信息给商家/服务商。

消息示例

ISV_GATEWAY_URL?charset=GBK&biz_content=
{
"id":"RECEIVED_2021042400826001508407723739","activity_id":"2016042700826004508401111111","event_time":"1619338271","voucher_id":"voucher_id","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.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==

接入指南

完整接口时序图#

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

接入支付券#

创建支付券#

激活支付券#

展示效果#

管理支付券活动#

修改支付券#

追加预算#

终止发券#

推广支付券#

领取券#

领取支付券#

用户端流程示例#

核销支付券#

消息通知#

第一步：订阅消息#

第二步：验签#

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

支付券消息通知#

活动发布通知#

消息示例#

追加预算通知#

消息示例#

活动修改通知#

消息示例#

领取通知#

消息示例#

活动终止通知#

消息示例#

完整接口时序图

接入支付宝门店（可选）

接入支付券

创建支付券

激活支付券

展示效果

管理支付券活动

修改支付券

追加预算

终止发券

推广支付券

领取券

领取支付券

用户端流程示例

核销支付券

消息通知

第一步：订阅消息

第二步：验签

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

支付券消息通知

活动发布通知

消息示例

追加预算通知

消息示例

活动修改通知

消息示例

领取通知

消息示例

活动终止通知

消息示例