更新时间：2024-06-06 10:02:05文档更新记录 >收藏订阅更新我的文档设置返回文档完成 后，商家/服务商可根据本文指引快速接入商家券 上传自定义券码模式。说明：●商家券 支持自研商家/服务商通过 自研、代调用、代运营 模式调用 api 接入，各模式配置详情可查看 接入准备。●上传自定义券码模式 创建的商家券活动，支持通过 引流转化（原“日常推广-优惠券”）、私域营销 推广至支付成功页、商家小程序等流量场景。●商家券-上传自定义券码模式 支持沙箱调试，详情可查看 。1 完整接口时序图2 接入代运营授权服务商代商家创建支付宝门店前，需根据商家身份完成如下操作。注意：自研商家无需进行代运营授权。2.1 间连商家入驻适用商家：仅间连商家服务商需补全商家信息至 m3，详情可查看 间连分级商户入驻接入指南。后续服务商通过 代运营授权 操作，在获取商家代运营授权同时，可将 m3 商家自动升级为 m4。2.2 代运营授权适用商家：间连商家、直连商家服务商需向商家发起营销代运营授权申请，商家在支付宝上授权后，服务商才能代商家进行创建营销活动等操作，详情可查看 服务商代运营基础。注意：调用 （向商户发起代运营操作接口）时， operate_type（操作类型）参数传入 operation_auth（授权操作）类型。3 接入支付宝门店（可选）支付宝提供了 蚂蚁门店管理，商家/服务商可通过接口创建支付宝门店获取门店 id（shop_id）并进行门店管理，后续可支持商家券在指定的应门店进行核销。注意：●服务商需引导商家完成产品开通和代运营授权。●商家券场景下创建门店时，必须传入 business_address#longitude（经度）及 business_address#latitude（纬度）且使用 ，否则商家券无法在支付宝投放展示。4 接入商家券4.1 创建商家券活动商家/服务商可按如下指引调用接口，接入商家券 创建活动、上传券码、追加预算 操作。4.1.1 接口时序图4.1.2 第一步：创建活动商家/服务商需调用 alipay.marketing.activity.ordervoucher.create（创建商家券活动接口）创建活动（支持创建满减券、折扣券、特价券），获取 activity_id（活动 id）。不同券类型优惠规则说明可查看 商家券类型。注意：●通过 code_mode 参数，选择 merchant_upload，则为 上传自定义券码模式 模式。●商家/服务商可配置对应优惠券为 全场优惠券（所有商品可用）或 单品优惠券（指定商品可用），通过是否传入 voucher_use_rule#券类型#goods_name 参数决定是全场还是单品，不传 goods_name 即为全场优惠券，传入即为单品优惠券，其中：○满减券（fix_voucher）、折扣券（discount_voucher）支持配置为 全场优惠券 或 单品优惠券。○特价券（special_voucher）仅支持配置为 单品优惠券。●券核销规则的有效期计算逻辑，可通过 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]。●商家券核销引导需传入 customer_guide#voucher_use_guide（券核销引导）：○offline_code_use_guide：线下扫码核销，设置为 true 时商家券将在支付宝卡包中展示券码。○mini_app_use_guide：小程序核销，设置为 true 时商家券将在支付宝卡包中展示“去使用”按钮，引导用户跳转至商家小程序页面（mini_app_path）。●本接口仅提交商家券活动创建申请，活动创建结果以 （商家券活动创建通知）为准，可查看下文 消息通知 > 商家券通知 > 活动创建通知。还可通过 （查询商家券活动接口），传入 activity_id 查询确认。展示效果alipay.marketing.activity.ordervoucher.create（创建商家券活动接口）对应参数展示效果如下图所示。4.1.3 第二步：上传券码创建商家券活动成功后，商家/服务商可调用 （同步商家券券码接口）将商家/服务商系统自定义的优惠券码上传至支付宝。用户领券时，支付宝将从中随机选取券码给用户。注意：●本接口单次仅能导入 1000 个券码，支持循环或者并发导入券码，券码总量不能超过 99 万。●上传券码后，商家/服务商可通过 （统计商家券券码数量接口），查询有效券码数量是否符合预期。●创建商家券活动成功后（可查看上文 第一步：创建活动）才可上传券码。4.1.4 第三步：提交预算商家/服务商需调用 （修改商家券活动发券数量上限）修改商家券活动发券数量上限信息，并以此作为活动预算，提交并通过后商家券活动才会生效。注意：●若创建商家券时 code_mode=merchant_upload，本接口 voucher_quantity 值需要与导入码的总数量保持一致。●本接口仅提交修改上限申请，结果需以 （商家券活动预算追加通知）为准，可查看下文 消息通知 > 商家券通知 > 发券数量上限修改通知。4.2 管理商家券活动商家/服务商可按如下指引调用接口，接入商家券 修改活动、追加预算、停止发券 操作。4.2.1 接口时序图4.2.2 修改活动商家/服务商可调用 alipay.marketing.activity.ordervoucher.modify（修改商家券活动基本信息接口）延长商家券活动领取结束日期、增加支持门店等。注意：●shop_ids（门店列表）仅支持增加不支持减少。传入本参数后支付宝将在已有门店列表基础上去重、新增，未传本参数则保持不变。●publish_end_time（券发放结束时间）仅支持延期，不支持提前结束。●本接口仅提交修改商家券活动申请，结果需以 （商家券活动修改通知接口）为准，可查看下文 消息通知 > 商家券通知 > 活动修改通知。4.2.3 追加预算若商家/服务商创建商家券成功后还希望增加商家券码数量，可通过上文 上传券码、提交预算 指引，传入需要追加预算的商家券 activity_id（活动 id）、券码及预算信息进行操作。注意：●仅支持 创建成功（即接收到 （商家券活动创建通知接口）通知）、未过期、未停止 的活动追加商家券发券上限，以此追加活动预算。●本接口 voucher_quantity 表示追加以后的券的总数量。例如，活动本来发放 200 张券，现需追加 100 张，总共发放 300 张券，则 voucher_quantity 应传入 300。●上传后可通过 （查询商家券活动接口），查询有效券码数量是否符合预期。●追加商家券码后还需通过 提交预算 完成追加预算操作。4.2.4 停止发券若商家券活动开始后，商家需提前终止活动。商家/服务商可调用 （停止商家券活动接口）停止发券，支付宝将同步在各领券展示渠道隐藏对应券信息，并切换商家券活动状态为 finished（已停止）。注意：●本接口仅提交停止商家券活动申请，结果需以 （商家券活动停止通知）为准，可查看下文 消息通知 > 商家券消息通知 > 活动停止通知。●停止发券后用户不能再领券，已停止的活动不能重新激活。4.3 推广商家券4.3.1 商家营销推广商家/服务商可接入 商家营销推广，将商家券推广至自己的收单账号收款的 支付成功页（后续将增加其它推广渠道），用户在支付成功页可直接领取商家券并自动放入卡包。4.3.2 私域营销商家/服务商接入并验收商家券后，可通过 私域营销 在商家小程序中进行营销推广。4.4 使用商家券用户领取商家券后，支付宝将通过异步通知发送券码等信息给商家/服务商。商家/服务商可按如下指引调用接口，接入商家券核销、退券等操作。4.4.1 接口时序图4.4.2 领取商家券用户在支付宝各渠道领取商家券后将自动添加至支付宝卡包，同时支付宝将通过 （商家券领取通知接口），向商家/服务商应用的 应用网关 发送领券通知。商家/服务商可据此获取领券用户 user_id 或 open_id（支付宝用户 id）、voucher_code（优惠券码）等信息。通知详情可查看下文 消息通知 > 商家券消息通知 > 领取通知。4.4.3 核销商家券用户使用商家券进行支付后，商家/服务商需在自身系统核销优惠券，同时调用 （同步券核销状态接口）通知支付宝核销优惠券。接口将同步返回核销结果，支付宝同步切换用户卡包中优惠券状态为 已核销。注意：●优惠券核销时间以 biz_dt（外部优惠券的核销时间）为准。●停止商家券活动 或 用户手动删除卡包中的商家券 后，已领取的商家券在有效范围内仍可核销。4.4.4 退回商家券若用户使用优惠券完成支付后发起退款操作，商家/服务商可调用 （取消核销状态接口）在退款时进行退券，接口将同步返回退券结果。注意：●仅支持 已核销 的券进行退券操作。●如果优惠券过期后，发起退券操作，该接口返回成功，优惠券退回后仍不可用。●如果优惠券在支付宝卡包已删除，发起退券操作，该接口返回成功，优惠券在支付宝卡包仍然是删除状态。5 消息通知商家/服务商创建、修改及用户领取商家券等场景，支付宝都将通过 from 蚂蚁消息服务 向商家应用或第三方应用 应用网关 推送异步通知消息，同步对应操作结果。若商家/服务商网络环境比较复杂，如：通过统一网关间连互联网，推荐使用网络兼容性更好的标准 http(s) 协议进行对接。5.1 第一步：订阅消息商家/服务商需根据 订阅消息 指引，为接入商家券的 商家应用 或 第三方应用 订阅如下消息接口。注意：●仅完成订阅后才会收到支付宝发送的对应异步通知消息。●商家/服务商可通过消息通知中 msg_method 参数判断消息类型。消息接口英文名消息接口中文名作用alipay.marketing.activity.message.created商家券活动创建通知同步商家券活动创建结果。alipay.marketing.activity.message.appende商家券活动预算追加通知同步商家券活动预算追加结果。alipay.marketing.activity.message.modified商家券活动修改通知同步商家券活动修改结果。alipay.marketing.activity.message.stopped商家券活动停止通知同步商家券领取停止结果。alipay.marketing.activity.message.received商家券领取通知同步用户领取商家券及对应券码信息。5.2 第二步：验签商家/服务商可使用支付宝 sdk 可根据 数据验签 指引，使用应用密钥信息验证异步通知消息来源是否为支付宝。5.3 第三步：反馈消息接收结果收到异步通知完成验签后，商家/服务商需返回 success 表示消息获取成功，支付宝就会停止发送异步通知。如果返回 fail 或其它值，表示消息获取失败，支付宝会根据 投递重试策略 重新发送消息到应用网关地址。说明：完成异步通知验签时，如果验签成功返回 success，验签失败返回 fail，重新接收异步进行处理。响应值描述是否重试fail消息获取失败重试success消息获取成功不重试5.4 商家券消息通知5.4.1 活动创建通知商家/服务商发起的商家券创建申请通过审核后，支付宝将通过 （商家券活动创建通知接口）发送活动创建成功时间等信息给商家/服务商。消息示例5.4.2 发券数量上限修改通知商家/服务商发起的商家券活动发券数量上限修改申请通过审核后，支付宝将通过 （商家券活动预算追加通知）发送通过时间等信息给商家/服务商。消息示例5.4.3 活动修改通知商家/服务商发起的商家券活动修改申请通过审核后，支付宝将通过 （商家券活动修改通知接口）发送活动修改成功时间等信息给商家/服务商。消息示例5.4.4 领取通知用户在支付宝推广渠道领取商家券时，支付宝将通过 （商家券领取通知接口）发送领券用户 user_id 或 open_id（支付宝用户 id）、voucher_code（优惠券码）等信息给商家/服务商。消息示例5.4.5 活动停止通知商家/服务商发起的停止发券申请通过审核后，支付宝将通过 （商家券活动停止通知接口）发送停止发券时间等信息给商家/服务商。消息示例6 沙箱调试沙箱环境是支付宝开放平台为开发者提供的与生产环境完全隔离的联调测试环境，开发者在沙箱环境中完成的调用不会对生产环境中的数据造成任何影响。商家券已支持沙箱环境调试，配置详情可查看 。
