支付宝小程序：进阶功能-优惠券礼包

商家可接入支付宝卡包功能通过券包发券组件与批量发券接口以券包形式向用户批量发放优惠券，打造专属优惠券大礼包类营销活动，如：用户完成连续七日购买商品，可一次领取多张商家优惠券，相比单张优惠券更具吸引力。

商家需先完成 基础功能 > 设计券并创建模板 并接入支付宝为商家提供的券包发券组件，即可实现以券包的形式多张优惠券同时发放给用户的能力。多张优惠券会在用户领取页面以一个券包的形式展示，用户确认领取后，开发者可基于支付宝 userId 及授权 token，将券包中的所有优惠券发放至用户支付宝卡包。

注意：

券包发放组件中，每张券都有对应的回调地址 mcallbackUrl 用于接收支付宝返回的领券用户支付宝 userId 及授权 token。支付宝在调用商家回调地址返回数据时，会选取预览页第一张券对应的 mcallbackUrl 作为回调的 URL。因此，为了保证发券成功，请务必保证券包中的所有券模版的 mcallbackUrl 一致。

券包：即券包发券组件中的券列表总称。

券包发券组件（批量发券组件）：即支付宝提供给商家获取用户 user_id、授权 token 以券包形式向用户批量放优惠券工具。

说明：

领券预览页样式不可修改。

商家完成 基础功能 > 设计券样式 并 创建模板 后，可按如下步骤接入支付宝为商家提供的批量发券组件，为用户发放券包。

1. 用户在商家营销页面点击领券；触发批量发券组件接口，对用户进行券包发放；

2. 组件生成授权 token 并渲染领券页面；

3. 用户点击 确认领券，组件会以 POST 方式将领券用户 user_id 及授权 user_token 发送至券模板设置的 merchant.mcallbackUrl 地址。开发者收到回调后需尽快调用批量发券接口向用户发送券包，该步骤如果超时或者失败，组件将展示领券失败但发券可能成功。详情参见下文 发券结果说明；

4. 开发者系统需要将支付宝批量发券接口发券结果返回给组件，详情参见下文第二步 返回发券结果；

5. 批量发券组件会自动向支付宝卡包后台查询券包发放结果并展示给用户；

6. 批量发券组件会在展示结果一段时间时候自动退出，商家营销页面可监听页面切回前台事件进行后续处理（刷新、跳转其他页面）。

商家完成 基础功能 > 设计券并创建模板 后，开发者可通过如下三种方式引导用户跳转至券包预览页领取优惠券包，券包预览页样式不可修改。

说明：

• 为方便查看以下示例已将 JSON 格式化，Encode 时请压缩。

• 每个券包最多包含 5 张券数据。

[    {        "templateId": "2019081511472260425514466",        "order": 1,        "extInfo": "extInfo",        "templateParams": {            "logoText": "5元代金券",            "validStartDate": "2019-04-17 19:00:00",            "validEndDate": "2020-01-22 00:00:00",            "mcallbackUrl": "https://www.alipay.com"        }    },    {        "templateId": "2019081511472260425514466",        "order": 2,        "extInfo": "extInfo",        "templateParams": {            "logoText": "10元代金券",            "validStartDate": "2019-04-17 19:00:00",            "validEndDate": "2020-01-22 00:00:00",            "mcallbackUrl": "https://www.alipay.com"        }    }]

• templateId：必填，券模板ID。

• order：必填，券顺序索引，标识券在券包中的顺序，order 值必须是大于 0 的整数， 且不同的券对应的 order 不能重复。后续批量发券接口 order 必须与此处顺序一致。

• templateParams：选填，模板动态参数，若创建模板时有动态参数则必填。

  • 创建券模板时若将 startDate、endDate、title、mcallbackUrl 四个模版元素配置为动态参数，则此处必须传入上述参数值用于预览页渲染，否则会报错 "预览页渲染失败/系统错误"。

  • serialNumber 为动态参数此处可不传值，在批量发券接口传入即可。

• extInfo：可选，扩展信息，若创建模板时使用到该参数必填。

// 压缩 itemList json 并进行整体 URLEncode 编码，数据示例如下String itemList = "[{"templateId":"2019081511472260425514466","order":1,"extInfo":"extInfo","templateParams":{"logoText":"5元代金券","validStartDate":"2019-04-17 19:00:00","validEndDate":"2020-01-22 00:00:00","mcallbackUrl":"https://www.alipay.com"}},{"templateId":"2019081511472260425514466","order":2,"extInfo":"extInfo","templateParams":{"logoText":"10元代金券","validStartDate":"2019-04-17 19:00:00","validEndDate":"2020-01-22 00:00:00","mcallbackUrl":"https://www.alipay.com"}}]";String encodeItemList = new String(URLEncoder.encode(itemList, "utf-8"));

/www/voucher.html?__webview_options__=abv%3dNO%26ttb%3dauto&bizType=giftPage&userId=领券用户user_id&title=券包标题&subTitle=券包副标题&itemList=URL编码后的券包 itemList JSON数据

• bizType：必填，指定本次领券预览页展示类型，券包发券固定为 giftPage。

• userId：必填，券包发放的目标用户 userId。

• title：必填，券包标题，长度不得超过 7 字。

• subTitle：必填，券包副标题，长度不得超过10字。

• itemList：必填，指定券包包含的券数据，券包最多包含 5 张券。

注意：拼接生成原始链接后，还需整体做一次 URLEncode。

alipays://platformapi/startapp?appId=68687143&url=%2fwww%2fvoucher.html%3f__webview_options__%3dabv%253dNO%2526ttb%253dauto%26bizType%3dgiftPage%26userId%3d2088302449179665%26title%3d%e6%a0%87%e9%a2%98%26subTitle%3d%e5%89%af%e6%a0%87%e9%a2%98%26itemList%3d%255b%257b%2522templateId%2522%253a%25222019081511472260425514466%2522%252c%2522order%2522%253a1%252c%2522extInfo%2522%253a%2522extInfo%2522%252c%2522templateParams%2522%253a%257b%2522logoText%2522%253a%25225%25e5%2585%2583%25e4%25bb%25a3%25e9%2587%2591%25e5%2588%25b8%2522%252c%2522validStartDate%2522%253a%25222019-04-17%2b19%253a00%253a00%2522%252c%2522validEndDate%2522%253a%25222020-01-22%2b00%253a00%253a00%2522%252c%2522mcallbackUrl%2522%253a%2522https%253a%252f%252fwww.alipay.com%2522%257d%257d%252c%257b%2522templateId%2522%253a%25222019081511472260425514466%2522%252c%2522order%2522%253a2%252c%2522extInfo%2522%253a%2522extInfo%2522%252c%2522templateParams%2522%253a%257b%2522logoText%2522%253a%252210%25e5%2585%2583%25e4%25bb%25a3%25e9%2587%2591%25e5%2588%25b8%2522%252c%2522validStartDate%2522%253a%25222019-04-17%2b19%253a00%253a00%2522%252c%2522validEndDate%2522%253a%25222020-01-22%2b00%253a00%253a00%2522%252c%2522mcallbackUrl%2522%253a%2522https%253a%252f%252fwww.alipay.com%2522%257d%257d%255d

	alipays://platformapi/startapp?appId=68687143&url=

发放优惠券

• bizType：必填，指定本次领券预览页展示类型，券包发券固定为 giftPage。

• userId：必填，券包发放的目标用户 userId。

• title：必填，券包标题，长度不得超过 7 字。

• subTitle：必填，券包副标题，长度不得超过10字。

• itemList：JSON格式券包数组，不超过 5 个。

  • templateId：必填，券模板ID。

  • extInfo：选填，扩展信息，如创建模板接口中使用则必填。

  • order：必填，券顺序索引，标识券在券包中的顺序，order 值必须是大于 0 的整数， 且不同的券对应的 order 不能重复。后续批量发券接口 order 必须与此处顺序一致。

  • templateParams：选填，模板动态参数。

    • 创建券模板时若将 startDate、endDate、title、mcallbackUrl 四个模版元素配置为动态参数，则此处必须传入上述参数值用于预览页渲染，否则会报错 "预览页渲染失败/系统错误"。

    • serialNumber 为动态参数此处可不填写，仅需批量发券接口中传入。

my.call('addCoupon', {  bizType: 'giftPage',  title: '标题',  subTitle: '副标题',  itemList: [{"templateId":"2019041914323202306418702111","order":1,"templateParams":{"content":"科技园路.","startTime":"2019-05-04","endTime":"2019-05-09","amount":"20"},"extInfo":"扩展信息，透传"},{"templateId":"2019041914323202306418702111","order":2,"extInfo":"扩展信息，透传"}],  userId: '20881021240756571223',}, function(result) {  console.log('小程序 call addCoupon'+JSON.stringify(result));});

• bizType：必填，指定本次领券预览页展示类型，券包发券固定为 giftPage。

• userId：必填，券包发放的目标用户 userId。

• title：必填，券包标题，长度不得超过 7 字。

• subTitle：必填，券包副标题，长度不得超过10字。

• itemList：JSON格式券包数组，不超过 5 个。

  • templateId：必填，券模板ID。

  • extInfo：选填，扩展信息，如创建模板接口中使用则必填。

  • order：必填，券顺序索引，标识券在券包中的顺序，order 值必须是大于 0 的整数， 且不同的券对应的 order 不能重复。后续批量发券接口 order 必须与此处顺序一致。

  • templateParams：选填，模板动态参数。

    • 创建券模板时若将 startDate、endDate、title、mcallbackUrl 四个模版元素配置为动态参数，则此处必须传入上述参数值用于预览页渲染，否则会报错 "预览页渲染失败/系统错误"。

    • serialNumber 为动态参数此处可不填写，仅需批量发券接口中传入。

用户在券包预览页点击 立即领取，券包发放组件会以 POST 方式将领券用户 user_id 及授权 user_token 等信息发送至券模板设置的 merchant.mcallbackUrl 地址。

开发者收到回调后需尽快调用批量发券接口向用户发送券包，该步骤如果超时或者失败，券包发放组件将展示领券失败（真实的发券结果取决于调用支付宝批量发券接口是否成功）。

注意：

• 地址必须为 https 协议，表单提交为 POST 方式，请求的数据 body 体为非格式化的 JSON 数据。

• 券包发放组件中，每张券都有对应的 mcallbackUrl，客户端在调用商家回调接口发券的时候，会选取预览页第一张券对应的 mcallbackUrl 作为回调的 URL。因此，为了保证发券成功，请务必保证券包中的所有券模版的 mcallbackUrl 一致。

(为方便查看，已格式化)

{   "user_id":"userid",   "user_token":"token",   "tpl_list": [       {           "tpl_id": "2018090311310949602265287",           "tpl_params": {               "startDate": "2019-04-17 19:00:00",               "endDate": "2020-10-22 00:00:00"           },           "order": 1,           "extInfo": ""       },       {           "tpl_id": "2019031413493844688789557",           "tpl_params": {},           "order": 2,           "extInfo": ""       }   ]}

参数说明：

• user_token：必填，用户授权 token。

• user_id：必填，领取券包的用户 ID。

• tpl_list：必填，券信息列表。

• order：必填，券顺序索引，与跳转到券包预览页传参中的 order 值一致，后续调用批量发券接口需与此保持一致。

• tpl_id：必填，卡券模板 ID。

• tpl_params：可选，模板动态参数。

• extInfo：可选，扩展信息。

开发者完成?第三步：批量发券?后，需向发券组件返回 JSON 格式的发券结果，示例如下：

?

{"success":"true","result":"成功/失败"}

参数说明：

• success：必传，是否成功。

• result：必传，发券结果描述，“成功”或“失败”。

商家系统回调地址获取了 token 令牌以及券列表请求参数后，可调用 alipay.user.pass.instancebatch.add(卡券实例批量发放接口)批量给领券用户发券。

注意：

• 批量发券接口会保证券包中的券实列全部发放成功或全部发放失败，不存在部分券发放成功、部分券发放失败的情况。

• 接口调用失败时，对应的错误码和错误信息以接口响应 result 字段中的 errorCode 和 errorMsg 为准。

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");        AlipayUserPassInstancebatchAddRequest request = new AlipayUserPassInstancebatchAddRequest();        request.setBizContent("{" +        ""instance_op_list": [" +         "{" +         ""tpl_id": "2018090311310949602265287", " +         ""order": 1, " +         ""tpl_params": "{"serialNumber":"20190731142900161test","endDate":"2020-10-22 00:00:00"," +         ""startDate":"2019-04-17 19:00:00","logo":"XXX"}"" +         "}," +         "{" +         ""tpl_id": "2019031413493844688789557", " +         ""order": 2, " +         ""tpl_params": "{"serialNumber":"20190731142900162test","endDate":"2020-10-22 00:00:00"," +         ""startDate":"2019-04-17 19:00:00","logo":"XXX"}"" +         "}" +         "],"+     // 对象识别类型，固定为 2， 表示按UserId发券。        ""recognition_type":"2"," +      // 领券用户信息        ""recognition_info":"{"user_id":"2088302449179665","user_token":"d81ca68b6811678960f1c7bd44792b11"}"" +        " }");        AlipayUserPassInstancebatchAddResponse response = alipayClient.execute(request);        if(response.isSuccess()){        System.out.println("调用成功");        } else {        System.out.println("调用失败");        }

• recognition_type：对象识别类型，券包批量发券模式下固定为 2。

• recognition_info：json 字符串类型，表示领券用户信息，包含：

  • user_id：指定本次领券的支付宝 userId。

  • user_token：本次领券用户确认领取时生成并传回给商家的发券授权 token 令牌值。

• instance_op_list：array 类型，表示本次批量发券包含的所有券实例，每张券实例需要传入的参数如下：

  • tpl_id：券实例对应的券模板 id

  • order： 指定该张券在券包中的顺序，order 值为大于 0 的整数，各券实例的 order 不能重复。发券时的顺序需和券包预览页的券顺序保持一致。建议直接使用券包发券组件回调至 mcallbackUrl 地址 POST 请求体中对应券的 order 值，不能修改。

  • tpl_params：JSON 字符串类型，模板中定义的占位动态参数，应全部通过此参数传入实际值。

更多参数及响应示例详情参见 alipay.user.pass.instancebatch.add(卡券实例批量发放接口)文档。

展示领券结果时，回调 callback 接口该接口最长等待 15s 时间，如果在等待时间内该接口没有返回结果，则领券组件将提示用户领券失败，但是发券可能成功，因此：

• 商家侧领券结果需以自身系统调用 alipay.user.pass.instancebatch.add(卡券实例批量发放接口)结果为准。

• 用户侧不论商家回调接口向组件返回发券成功、失败还是超时未返回结果，支付宝客户端都会查询支付宝卡包后台最终确认券包发放结果并以此为准。

即若商家超时未返回发券结果但实际?alipay.user.pass.instancebatch.add(卡券实例批量发放接口)发券成功，则用户领券页会展示 “领券失败，请稍后重试”，但其支付宝卡包中会添加对应优惠券。