更新时间：2024-06-28 17:19:46收藏订阅更新我的文档设置返回文档商家通过使用用户 id 发券组件能力，在用户确认后，开发者可基于支付宝用户的 id，将优惠券发放至用户支付宝客户端的卡包内。从而实现将用户在商家私域场景内领取的优惠券，同步到支付宝客户端的卡包内，方便用户集中管理自己领取的各类优惠券，同时也可借助卡包的流量促进商家优惠券的使用率。本文主要面向商家/服务商的产品及技术人员，描述用户 uid 发券组件的对接流程。1 整体交互时序图1.1 流程简介●步骤（1）：用户在商家活动页点击领券。●步骤（2）：引导用户通跳转至领券预览页，完成领券授权操作。详情可查看 第三步：用户跳转至领券预览页。●步骤（3）、（4）：组件生成授权 token 并渲染领券页面。●步骤（5）：用户点击 确认领券，触发第（6）步操作。●步骤（6）：组件会调用开发者在模板配置的 merchant.mcallbackurl 接口，开发者在该接口 url 的 query 参数中获取 token（对应步骤（7）中的 user_token），该接口需要实现的功能及要求可查看 第四步：发券组件回调 callback，该步骤如果超时或者失败，领券组件将展示领券失败但发券可能成功。●步骤（7）：开发者获取 token 后，需要调用支付宝发券接口进行发券，可查看 第五步：调用接口发券。●步骤（9）：开发者系统需要将步骤（7）中支付宝发券接口的结果（如成功，需包含券 id passid）在步骤（10）返回给组件，详情可查看下文 返回发券结果。●步骤 （11）、（12）：组件通过步骤（10）返回的结果，查询确认领券结果并展示给用户。●步骤（13）、（14）：领券组件会在展示结果一段时间后自动退出， 商家营销页面可监听页面切回前台事件进行后续处理（刷新、跳转其它页面）。1.2 用户端流程说明：●跳转至领券预览页时 biztype 参数可指定预览页展示类型： svpage : 全屏样式单张优惠券（h5页面）。●用户领券流程中，开发者需唤起发券组件页面，用户操作后，发券组件页面将自动关闭。 2 第一步：设计券模板2.1 设计券模板样式1商家使用支付宝账号登录 ，根据页面提示完成卡券的设计。 说明：卡券背景图 strip 、logo 等图片内容可在平台设计时上传验证是否合规，后续创建模板时需传入图片 url 地址。 2点击 提交 保存设计好的券模板后，在 我的alipass 页面下载券模板文件。 3下载得到券模板 .alipass 后缀的压缩包，用解压软件解压，其中 pass.json 即为模板的主要内容。 2.2 修改券模板参数下载 pass.json 中 json 参数需做如下修改，各参数详情可查看 参数详细说明。2.2.1 修改渠道属性（platform）节点1将 platform 中 channelid 字段值，改为发券的 appid。○channelid 指定模板的所属者，必须修改为模板创建者的 appid。2删除 platform 中 webserviceurl 字段。○历史遗留参数，直接删掉节点即可。2.2.2 修改文件属性（fileinfo）节点将 fileinfo 中 serialnumber 字段值，改为 $serialnumber$ 。serialnumber 指定券模板下发给每个用户的券 id，必须配置成动态参数 $serialnumber$，因为每张券的券 id 应保持唯一性，而每次调用发券接口中都需要指定 serialnumber 参数的值。2.2.3 增加商家属性（merchant）节点1修改 merchant 中 mname 字段，根据商家需求定义展示名称。2添加 merchant 中 mcallbackurl 字段，配置接收 token 的商家页面回调地址，地址必须为 https 协议。注意：merchant 中 mcallbackurl 地址必须为 https 地址。 2.2.4 修改基础属性（evoucherinfo）节点1建议将 evoucherinfo 中 startdate 字段值，配置成动态参数 $validstartdate$ 。2建议将 evoucherinfo 中 enddate 字段值，配置成动态参数 $validenddate$ 。3其它参数需开发者根据实际需求选择是否修改为动态参数。注意：●若将 startdate、enddate、title、mcallbackurl 四个模板元素配置为动态参数，则跳转预览页时必须传入上述参数值用于预览页渲染，否则会报错 预览页渲染失败/系统错误。●动态参数传参规则：以 evoucherinfo -> startdate 参数为例，创建模板时若定义 "startdate":"$validstartdate$" ，则跳转至领券详情页及发券接口动态参数赋值需以占位符为 key 即 "validstartdate"："2020-08-24 00:00:00"。2.2.5 完成以上修改后的 pass.json 数据3 第二步：创建券模板开发者完成上述步骤后，可调用 alipay.pass.template.add（卡券模板创建接口） 创建券模板。3.1 示例代码3.1.1 入参说明●unique_id：当前请求的唯一串号，唯一标示 1 次创建模板的请求，每次创建模板需要生成新的 unique_id。●tpl_content：为 json 对象，传递卡券模板内容信息。○logo：必填，商家 logo 图片地址。因为当前模板下载文件中没有返回 logo 图片地址的值，商家可以选择填入 logo 的公网可访问自定义链接地址。 还可使用 上传图片获取 url 地址（需添加 商家会员卡）。○icon：可选，商家 icon 图片地址。○strip：可选，券背景图片地址。○content：必填，详细模板内容，直接传入上一步中修改完成的 pass.json 内容即可。详情可查看 参数详细说明。3.1.2 响应示例接口响应也对应有 json 格式字串，可查看接口文档。响应参数说明●解析 response 中 result 字串，将 string 类型的 result 转换为 json 对象，取其 tpl_id 即为本次创建的券模板 id。●而 result 中 tpl_params 为动态参数列表，返回在模板文件中配置的所有动态参数名，原则上所有在模板中配置 占位 的动态参数都要在调发券接口发券时传入实际值。如：创建模板时若定义 "startdate":"$validstartdate$" ，则跳转至领券详情页及发券接口动态参数赋值需以占位符为 key 即 "validstartdate"："2020-08-24 00:00:00"。 4 第三步：用户跳转至领券预览页商家完成 卡券模板创建 后，开发者可通过如下三种方式跳转至领券预览页领取优惠券。注意：唤起预览页时，无需在入参中显式指定用户 id，支付宝将直接获取当前登录用户 id。同时，在用户确认领券后，支付宝回调商家，也不会返回用户 id。建议商家利用 extinfo 透传必要的业务串号或上下文，以便第四步确定发券目标用户。4.1 通过 scheme url 方式跳转完整链接示例：alipays://platformapi/startapp?appid=68687143&url=/www/voucher.html?__webview_options__=abv%3dno%26ttb%3dauto&biztype=svpage&templateid=templateid&templateparams=%7b%22startdate%22%3a%222020-08-10+00%3a00%3a00%22%2c%22enddate%22%3a%222020-09-10+00%3a00%3a00%22%7d4.1.1 参数说明跳转至领券前置页只需拼接参数生成跳转链接即可，链接拼接参数包括：●biztype：必填，指定本次领券预览页展示类型。枚举支持：○svpage : 全屏样式单张优惠券（h5页面）。●templateid：必填，券模板 id。●templateparams：模板动态参数。使用说明如下：○创建券模板时若将 startdate、enddate、title、mcallbackurl 四个模板元素配置为动态参数，本参数必填。如：{"startdate":"$validstartdate$"}。拼接跳转链接时，需传入对应参数动态 key 及对应 value 用于预览页渲染展示，如：{"validstartdate":"2020-08-20 00:00:00"}，否则会报错 预览页渲染失败/系统错误，其余动态参数在发券接口传入即可。○serialnumber 为动态参数时仅需发券接口中传入，此处可不填写。●extinfo：选填，扩展信息，商家自定义，页面将值原封不动回传商家回调地址；不用则无需关心，用于实现各种进阶业务需求逻辑，值由商家实时生成、传入并识别。extinfo 参数如果包含中文字符或者其它 url 协议的特殊字符等，由于服务端处理逻辑为直接拼接，因此拼接成 url 参数的时候 extinfo 建议进行 2 次 url 编码。4.2 通过 h5 api 方式跳转4.2.1 示例代码参数说明●biztype：必填，指定本次领券预览页展示类型。 svpage：全屏样式单张优惠券（h5页面）。●templateid：必填，券模板id。●templateparams：模板动态参数。使用说明如下：○创建券模板时若将 startdate、enddate、title、mcallbackurl 四个模板元素配置为动态参数，本参数必填。如：{"startdate":"$validstartdate$"}。拼接跳转链接时，需传入对应参数动态 key 及对应 value 用于预览页渲染展示，如：{"validstartdate":"2020-08-20 00:00:00"}，否则会报错 预览页渲染失败/系统错误，其余动态参数在发券接口传入即可。○serialnumber 为动态参数时仅需发券接口中传入，此处可不填写。●extinfo：选填，扩展信息，商家自定义，页面将值原封不动回传商家回调地址；不用则无需关心，用于实现各种进阶业务需求逻辑，值由商家实时生成、传入并识别。 4.3 通过小程序 jsapi 方式跳转4.3.1 示例代码参数说明●biztype：必填，指定本次领券预览页展示类型。 svpage：全屏样式单张优惠券（h5页面）。●templateid：必填，券模板 id。●templateparams：模板动态参数。使用说明如下：○创建券模板时若将 startdate、enddate、title、mcallbackurl 四个模板元素配置为动态参数，本参数必填。如：{"startdate":"$validstartdate$"}。拼接跳转链接时，需传入对应参数动态 key 及对应 value 用于预览页渲染展示，如：{"validstartdate":"2020-08-20 00:00:00"}，否则会报错 预览页渲染失败/系统错误，其余动态参数在发券接口传入即可。○serialnumber 为动态参数时仅需发券接口中传入，此处可不填写。●extinfo：选填，扩展信息，商家自定义，页面将值原封不动回传商家回调地址 mcallbackurl；不用则无需关心，用于实现各种进阶业务需求逻辑，值由商家实时生成、传入并识别。4.3.2 错误码error说明17000通用错误码，发券失败17001重复调用错误，同时只能允许运行一个发券任务17002参数错误，必填项为空等17003用户主动取消领券操作5 第四步：发券组件回调 callback用户在发券确认页点击 确认领取，发券组件将通过 get 方式向优惠券模板 mcallbackurl 地址发送发券授权 token 数据用于商家调用接口给用户发放优惠券。5.1 回调 callback url 的样例5.2 返回发券结果开发者完成 第五步：调用接口发券 后，需向发券组件返回 json 格式的发券结果，示例如下：参数说明●success：必传，是否成功。●passid：必传，如果发券成功，则必传该字段，后续将用来查询发券结果。●resultdesc：可选，发券结果描述。6 第五步：调用接口发券承接上步，商家系统通过发券组件回调获取了发券授权 token 令牌及其它发券请求参数后，商家后台系统可组装发券参数调用 alipay.pass.instance.add（卡券实例发放接口）发券。6.1 示例代码入参说明●tpl_id：必填，券模板 id。●tpl_params：必填，模板动态参数，创建模板时 serialnumber 必须为动态参数入值，其它参数根据商家业务决定进行传值。●recognition_type：发券（用户信息识别）类型，支付宝卡包暂仅支持 2 基于用户信息识别。●recognition_info：发券用户信息模型，当 recognition_type = "2"时，配置传参如下：○user_id（open_id）：指定本次发券的支付宝 userid（openid）。支付宝用户唯一标识。新商户建议使用open_id替代该字段。对于新商户，user_id 字段未来计划逐步回收，存量商户可继续使用。如使用 open_id，请确认 应用-开发配置-openid配置管理 已启用。无该配置项，可查看 。注意 user_id 务必与调用 appid 对应，否则调用异常。○user_token：本次发券该用户确认领取时生成并传回给商家的发券 token 令牌值。 注意：发券接口参数中传入的 user_token 与 tpl_id 及 user_id（open_id） 背后的用户都必须对应。 6.2 响应示例开发者调用 alipay.pass.instance.add（卡券实例发放接口）发放优惠券后，无论发放结果如何都需向发券组件返回发券结果，示例可查看 返回发券结果。 7 发券结果说明展示领券结果时，发券组件回调 callback 接口最长等待 15s 时间，如果在等待时间内商家没有返回发券成功结果，则领券组件将提示用户领券失败，但是发券可能成功，因此：●商家侧领券结果需以自身系统调用 alipay.pass.instance.add（卡券实例发放接口）结果为准。●用户侧不论商家回调接口向组件返回发券成功、失败还是超时未返回结果，支付宝客户端都会查询支付宝卡包后台最终确认券发放结果并以此为准。即若商家超时未返回发券结果但实际 alipay.pass.instance.add（卡券实例发放接口）发券成功，则用户领券页会展示 领券失败，请稍后重试，但其支付宝卡包中会添加对应优惠券。8 更新卡券实例完成卡券发放后，开发者还可调用 实现指定卡券核销、失效、更新卡券样式内容三大功能。注意：该接口仅支持修改单张卡券实例。8.1 核销卡券功能完成卡券发放后，开发者可调用 进行卡券核销，使卡券在用户的支付宝客户端展示为 已使用 状态。对于支付宝卡券而言，核销操作只是将卡券状态变更为 used（已使用），用户客户端展示为已使用状态，未涉及资金流的核销。仅支持核销有效状态的卡券，若卡券处于卡券删除或者已转赠，不可进行核销操作。8.1.1 http 请求源码示例8.1.2 客户端示例图调用更新卡券接口核销卡券之后，用户在支付宝客户端展示的卡券，将变成已使用状态，并且进入已失效列表。8.2 失效卡券功能完成卡券发放后，开发者可调用 进行卡券失效操作。该功能主要将发放的卡券进行作废操作，卡券将在用户的支付宝客户端消失。8.2.1 http 请求源码示例8.3 更新卡券内容功能完成卡券发放后，开发者可调用 更新卡券样式内容，包括内容（如优惠描述信息和 logotext）、logo、背景图、样式等（要支持更新，必须在模板中将对应字段设置成可变参数）。8.3.1 http 请求源码示例8.3.2 客户端示例图
