更新时间：2025-03-06 16:22:03文档更新记录 >配置项检测工具收藏订阅更新我的文档设置接入检测（即可查看检测结果）若有未通过的接入检测项，接口将无法调通去登录返回文档完成 接入准备 后，商家/服务商 可根据本文指引快速接入 支付券 产品。说明：●支付券 产品支持自研商家/服务商通过 自研应用 或 第三方应用 代调用、自调用方式，调用 api 接入，各模式配置详情可查看 接入准备。1 完整接口时序图2 接入支付宝门店（可选）支付宝提供了 蚂蚁门店管理 产品，商家/服务商可通过接口创建支付宝门店获取门店 id（shop_id）并进行门店管理，后续可指定支付券支持在对应门店进行核销。注意：接入蚂蚁门店管理产品：●服务商 需根据 完成开通产品、代运营授权。●不支持 服务商 自调用，需通过 代调用 openapi（传入 app_auth_token）方式接入。●支付券场景下创建门店时必须传入 business_address#longitude（经度） 及 business_address#latitude（纬度）且使用 ，否则支付券无法在支付宝投放展示。3 创建支付券商家/服务商可按以下指引调用接口，接入支付券，进行 创建、激活 操作。注意：接口方式目前仅支持创建满减券，如需创建其他类型优惠券，请登录 进行创建。商家/服务商调用 创建成功后可获取到 activity_id（支付券活动 id），此时支付券为“已创建”(草稿)状态，需要激活后才可发放使用。注意：●券的图片需要通过调用 上传， 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（相对时间）时，券可核销有效期以 中 event_time（领券时间，精确到秒）加本接口设置的有效时间规则（精确到天）为准： [ event_time wait_days_after_receive,event_time wait_days_after_receive valid_days_after_receive ]。3.1 预充值场景3.2 免充值场景4 激活支付券商家/服务商需调用 对 已创建（草稿）状态的支付券进行激活。注意：●如果创建券时选择过 voucher_budget_supply_info.budget_type = recharge 预充值，调用 会返回充值链接 ，制券方需点击此链接完成充值（充值链接有效期 3 天，超期未支付需重新调用激活接口获取新充值链接）。●激活支付券接口仅提交激活支付券活动申请，结果需以 异步通知为准，可查看下文 消息通知 > 支付券通知 > 活动发布通知。展示效果对应参数展示效果如下图所示。5 管理支付券活动商家/服务商可按如下指引调用接口，接入支付券 查询活动详情，修改活动，追加活动预算，终止支付券 操作。5.1 修改支付券商家/服务商可调用 延长支付券领取结束日期、增加支持门店等。注意：●修改仅适用于发布后修改，活动发布前草稿态，商家/服务商自行保存在本地。●创建时配置了shop_ids（门店列表）修改时才允许修改门店，创建时未配置 shop_ids（门店列表）修改时不允许修改门店。●shop_ids（门店列表）只允许增加不允许减少。传入本参数后支付宝将在已有门店列表基础上去重、新增，未传本参数则保持不变。券核销规则中的支付券可使用范围。●publish_end_time（券发放结束时间）只能延期，不能提前结束。●本接口仅提交修改支付券活动申请，结果需以 异步通知为准，可查看下文 消息通知 > 支付券通知 > 活动修改通知。5.1.1 修改可用范围5.1.2 修改核销规则5.1.3 修改发放规则5.2 追加预算商家/服务商需调用 提交支付券预算信息，完成预算追加操作。注意：●仅支持 发布成功（即接收到 通知）、未过期、未终止 的活动追加支付券发券上限，以此追加活动预算。●本接口 voucher_quantity 表示追加以后的券的总数量。例如，活动本来发放 200 张券，现需追加 100 张，总共发放 300 张券，则 voucher_quantity 应传入 300。●如果创建券时选择过 voucher_budget_supply_info.budget_type = recharge 预充值，调用 会返回充值链接 ，制券方需点击此链接完成充值（充值链接有效期 3 天，超期未支付需重新调用追加预算接口获取新充值链接）。●本接口仅提交预算申请，结果需以 异步通知为准，可查看下文 消息通知 > 支付券通知 > 追加预算通知。●追加前后可通过 返回的 voucher_send_rule_info#quantity 查看券活动总数量。5.3 终止发券若支付券活动开始后，商家需提前终止活动。商家/服务商可调用 终止发券，支付宝将同步在各领券展示渠道隐藏对应券信息，并切换支付券活动状态为 finished（已停止）。注意：●本接口仅提交终止支付券活动申请，结果需以 的通知内容为准，可查看下文 消息通知 > 支付券消息通知 > 终止发券通知。●终止发券后用户不能再领券，已终止的活动不能重新激活。6 推广支付券商家/服务商接入并验收支付券产品功能后，可通过 私域营销 产品在商家小程序中进行营销推广。7 领取券用户领取支付券后，支付宝将通过异步通知发送领取信息给商家/服务商。7.1 领取支付券商家/服务商需根据 私域营销 产品指引，使用 领券组件插件 引导用户在小程序中领取支付券。7.1.1 用户端流程示例8 核销支付券用户领取券后，可以通过支付宝收款渠道（付款码/小程序等）进行券核销，支付宝同步切换用户卡包中优惠券状态为 已核销。注意：●优惠券核销与否，以商家设置核销规则为准。●终止支付券活动 ，已领取的支付券在有效范围内仍可核销。●用户手动删除卡包中的支付券 后，则该券不可核销。●核销问题可通过下述方式进行排查。○用户排查：商家可尝试自行领取支付券，核销后如出现问题，在 支付宝app 搜索 优惠小蜜 按操作指引进行排查。○商家排查：登录 商家平台 使用 进行排查。9 消息通知商家/服务商创建、修改及用户领取支付券等场景，支付宝都将通过 from 蚂蚁消息通知 向商家应用或第三方应用 应用网关 推送异步通知消息，同步对应操作结果。若商家/服务商网络环境比较复杂，例如：通过统一网关间连互联网，推荐使用网络兼容性更好的标准 http(s) 协议进行对接。9.1 第一步：订阅消息商家/服务商需根据 订阅消息 指引，为接入支付券的 商家应用 或 第三方应用 订阅如下消息接口。注意：●仅完成订阅后才会收到支付宝发送的对应异步通知消息。●商家/服务商可通过消息通知中 msg_method 参数判断消息类型。消息接口（英文/中文名）作用同步支付券活动发布结果。同步支付券活动修改结果。同步支付券活动预算追加结果。同步支付券活动终止结果。同步支付券用户领取结果。同步支付券用户核销结果。9.2 第二步：验签商家/服务商使用支付宝 sdk 可根据 数据验签 指引，使用应用密钥信息验证异步通知消息来源是否为支付宝。9.3 第三步：反馈消息接收结果收到异步通知后，商家/服务商需返回 success 表示消息获取成功，支付宝就会停止发送异步通知。如果返回 fail 或其它值，表示消息获取失败，支付宝会根据 投递重试策略 重新发送消息到应用网关地址。说明：在接收异步消息后，进行验签，如果验签成功输出 success，验签失败返回 fail，重新接收异步消息进行处理。响应值描述是否重试fail消息获取失败重试success消息获取成功不重试9.4 支付券消息通知9.4.1 活动发布通知商家/服务商发起的支付券发布成功后，支付宝将通过 发送活动创建成功时间等信息给商家/服务商。消息示例9.4.2 追加预算通知商家/服务商发起的支付券活动发券数量上限修改成功后，支付宝将通过 发送通过时间等信息给商家/服务商。消息示例9.4.3 活动修改通知商家/服务商发起的支付券活动成功，支付宝将通过 发送活动修改成功时间等信息给商家/服务商。消息示例9.4.4 领取通知用户在支付宝在私域插件领取支付券时，支付宝将通过 发送领券用户 user_id 或 open_id（支付宝用户 id）、voucher_id（优惠券id）等信息给商家/服务商。消息示例9.4.5 活动终止通知商家/服务商发起的终止活动成功后，支付宝将通过 发送终止时间等信息给商家/服务商。消息示例
