支付宝卡包

产品介绍

什么是支付宝卡包（alipass）?支付宝卡包（alipass），是支付宝公司推出的一款可以管理电子凭证的产品，该产品聚合来自各类生活服务的票据凭证，包括优惠券、折扣券、代金券、换购券、电影票、演出票、火车票、机票。1.png

2.png

产品特色

产品生命周期：3.bmp

使用场景

企业或者个人开发者可以通过支付宝提供的开放接口，把卡券添加到支付宝卡包，用户可以通过小程序查看卡券，同时支持跳转到支付宝卡包页面，在卡包中查看并使用商户同步进来的卡券。4.png

应用案例

以电子门票的使用为例，用户在使用电子门票时的流程如下图所示：

支付宝卡包 - 图5

支付宝卡包 - 图6

产品关联推荐

  • 商家方面，覆盖面比较广，涉及到所有发核券的商家均可使用。
  • 公共事业方面，也可以拓展，如：电子地铁票等。

准入条件

  • 公司运营稳定，具有一定的客户群。具体考核将参考公司运营时长、规模、用户数来做出综合判定；
  • 公司具备一定的技术能力，能够独立完成技术对接；
  • 支持合作后的服务联动处理，数据反馈和异议处理。

计费模式

免费接口，暂未收取费用。

接入介绍

添加支付宝卡包

在小程序“开发管理”详情页的“功能列表”中添加“支付宝卡包”。

5.PNG

卡包术语介绍

以下是支付宝卡包接口开发过程中需要了解的常用概念：

名称描述
模板/卡券模板（template）模板包含了开发者设计的卡券的样式、内容信息。基于此模板的样式，开发者可以向用户发放卡券，一个模板可以对应多个卡券，模板内容样式的变化会引起卡券的变化。
模板编号（templateId）模板的唯一标识，由创建模板成功后，接口返回给商户，基于此参数创建卡券。
卡券ID（passId）卡券ID，唯一代表一张卡券。可以多个卡券ID对应一个模板。由卡券创建成功后返回。

接口调用

使用说明

商家通过开放平台提供的 alipass 接口，可完成从卡券模板设计到卡券实体构造整个流程。

image

1.创建卡券模版：

image

2.创建卡券：

image

接口调用流程

支付宝卡券整体接口调用流程：

image

创建卡券模板

模板设计：推荐使用卡券平台（https://alipassprod.alipay.com），在线编辑获取 JSON 模板。详细可参见支付宝卡包API详细说明。

接口列表：创建卡券模板接口（alipay.pass.template.add）SDK 调用示例：

  1. /**
  2.  * 新建模板
  3.  * appAuthToken如ISV代替商家调用接口，需将商户授权后获取的app_auth_token带上；如商家自己调用，则传null。
  4.  * bizContent 因该接口业务参数复杂，请详见接口文档
  5.  */
  6.  AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");
  7.  AlipayPassTemplateAddRequest request = new AlipayPassTemplateAddRequest();
  8.  request.putOtherTextParam("app_auth_token", appAuthToken);
  9.  request.setBizContent(bizContent);
  10.  AlipayPassTemplateAddResponse response=alipayClient.execute(request);
  11.  System.out.print(response.getBody());//根据业务处理response

app_auth_token 在 ISV 代替商家调用接口时使用，商家自己调用，可传 null。bizContent Json 串示例：

  1. "{\"unique_id\":\"143512639346821\"," //支付宝对该参数的请求有唯一性校验，请保证每次请求该参数唯一
  2.                 + "\"tpl_content\":"
  3.                 + "{\"logo\":\"https://alipass.alipay.com//temps/free/logo.png\","
  4.                 + "\"strip\":\"https://alipass.alipay.com//temps/free/strip.png\","
  5.                 + "\"icon\":\"http://alipassprod.test.alipay.net/temps/free/icon.png\","
  6.                 + "\"content\":{"
  7.                 + "\"evoucherInfo\":"
  8.                 + "{\"title\":\"风情优惠券\","
  9.                 + "\"type\":\"coupon\","
  10.                 + "\"product\":\"free\","
  11.                 + "\"startDate\":\"$validStartDate$\","
  12.                 + "\"endDate\":\"$validEndDate$\","
  13.                 + "\"operation\":"
  14.                 + "[{\"format\":\"barcode\",\"message\":\"$code$\",\"messageEncoding\":\"UTF-8\",\"altText\":\"$code$\"}],"
  15.                 + "\"einfo\":{"
  16.                 + "\"logoText\":\"$logoText$\","
  17.                 + "\"headFields\":"
  18.                 + "[{\"key\":\"status\",\"label\":\"状态\",\"value\":\"$useStateDesc$\",\"type\":\"text\"}],"
  19.                 + "\"primaryFields\":"
  20.                 + "[{\"key\":\"strip\",\"label\":\"\",\"value\":\"$discountInfo$\",\"type\":\"text\"}],"
  21.                 + "\"secondaryFields\":"
  22.                 + "[{\"key\":\"validDate\",\"label\":\"有效期至：\",\"value\":\"$validEndDate$\",\"type\":\"text\"}],"
  23.                 + "\"auxiliaryFields\":[],"
  24.                 + "\"backFields\":"
  25.                 + "[{\"key\":\"description\",\"label\":\"详情描述\",\"value\":\"1.该优惠有效期：截止至2014年06月18日；\n2.凭此券可以享受以下优惠：\n享门市价优惠\n不与其他优惠同享。详询商家。\",\"type\":\"text\"},"
  26.                 + "{\"key\":\"shops\",\"label\":\"可用门店\",\"value\":\"\",\"type\":\"text\"},"
  27.                 + "{\"key\":\"disclaimer\",\"label\":\"负责声明\",\"value\":\"除特殊注明外，本优惠不能与其他优惠同时享受；本优惠最终解释权归商家所有，如有疑问请与商家联系。提示：为了使您得到更好的服务，请在进店时出示本券。\",\"type\":\"text\"}"
  28.                 + "]},"
  29.                 + "\"remindInfo\":{\"offset\":\"2\"}},"
  30.                 + "\"merchant\":{\"mname\":\"hodewu\",\"mtel\":\"\",\"minfo\":\"\"},"
  31.                 + "\"platform\":{\"channelID\":\"$channelID$\",\"webServiceUrl\":\"\"},"
  32.                 + "\"style\":{\"backgroundColor\":\"RGB(255,126,0)\"},"
  33.                 + "\"fileInfo\":"
  34.                 + "{\"formatVersion\":\"2\",\"canShare\":true,\"canBuy\":false,\"canPresent\":true,\"serialNumber\":\"$serialNumber$\",\"supportTaxi\":\"true\",\"taxiSchemaUrl\":\"alipays://platformapi/startapp?appId=20000130&sourceId=20000030&showTitleBar=YES&showToolBar=NO&showLoading=NO&safePayEnabled=YES&readTitle=YES&backBehavior=back&url=/www/index.html\"},"
  35.                 + "\"appInfo\":"
  36.                 + "{\"app\":{},\"label\":\"\",\"message\":\"\"},"
  37.                 + "\"source\":\"alipassprod\","
  38.                 + "\"alipayVerify\":[]"
  39.                 + "}}}"

说明：

  • 模板中的自定义参数以双 $ 符号标志，即 $serialNumber$ 表示自定义参数名为 serialNumber，供发放卡券时使用。
  • unique_id 参数支付宝有唯一性校验，请保证每次请求该值唯一。
    API详细文档：创建卡券模板接口

发放卡券

接口列表：发放卡券接口（alipay.pass.instance.add）SDK 调用示例：

  1. /**
  2.  * 发放卡券
  3.  * appAuthToken如ISV代替商家调用接口，需将商户授权后获取的app_auth_token带上；如商家自己调用，则传null。
  4.  * bizContent 因该接口业务参数复杂，请详见接口文档 
  5.  */
  6.  AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");
  7.  AlipayPassInstanceAddRequest request = new AlipayPassInstanceAddRequest();
  8.  request.putOtherTextParam("app_auth_token", appAuthToken);
  9.  request.setBizContent(bizContent);
  10.  AlipayPassInstanceAddResponse response = alipayClient.execute(request);
  13.  System.out.print(response.getBody());//根据业务处理response

app_auth_token 在 ISV 代替商家调用接口时使用，商家自己调用，可传 null。bizContent Json 串示例：

  1. "{\"recognition_type\":\"1\","
  2.                 + "\"tpl_id\":\"2016072715135409252622447\","
  3.                 + "\"recognition_info\":{\"partner_id\":\"2088**********10\","
  4.                 + "\"out_trade_no\":\"xiaomoxiaomotest7629500\"}," 
  5.                 + "\"tpl_params\":"
  6.                 + "{"
  7.                 + "\"validStartDate\":\"2016-06-30 20:00:00\","
  8.                 + "\"validEndDate\":\"2016-12-30 20:00:00\","
  9.                 + "\"channelID\":\"2088**********10\","
  10.                 + "\"discountInfo\":\"凭此券即可打8.5折\","
  11.                 + "\"code\":\"20160725762587i\","
  12.                 +"\"useStateDesc\":\"可使用\","
  13.                 +"\"logoText\":\"四季风情85折优惠券\","
  14.                 + "\"serialNumber\":\"xm433367366244615532\"}}";

说明：

  • tpl_params 中的 json 节点即为模板创建时设置的自定义参数（即模板中定义的 $xxxx$ ），每次发券可以自己定义内容，且其中的 serialNumber 支付宝有唯一性校验，每次请求请保证唯一性，不要重复。
  • tpl_id：调用模板创建接口成功后返回模板ID，该ID用于发放券票。
  • recognition_info:真实存在的支付宝交易，需要提供该交易的外部订单号和对应的商户 PID。
  • channelID：可设置为APPID（从创建应用处获取）或者 PID。
    API详细文档：发放卡券接口

核销卡券

接口列表：更新卡券接口（alipay.pass.instance.update）SDK 调用示例

  1. /**
  2.  * 
  3.  * appAuthToken如ISV代替商家调用接口，需将商户授权后获取的app_auth_token带上；如商家自己调用，则传null。
  4.  * bizContent 因该接口业务参数复杂，请详见接口文档
  5.  */
  6.  AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");
  7.  AlipayPassInstanceUpdateRequest request = new AlipayPassInstanceUpdateRequest();
  8.  request.putOtherTextParam("app_auth_token", appAuthToken);
  9.  request.setBizContent(bizContent);
  10.  AlipayPassInstanceUpdateResponse response = alipayClient.execute(request);
  13.  System.out.print(response.getBody());//根据业务处理response

app_auth_token 在 ISV 代替商家调用接口时使用，商家自己调用，可传 null。bizContent Json串示例：

  1. "{\"status\":\"USED\","
  2.                 + "\"channel_id\":\"2088**********10\"," 
  3.                 + "\"serial_number\":\"xm433367366244615532\","
  4.                 + "\"tpl_params\":"
  5.                 + "{\"useStateDesc\":\"已使用\"}"
  6.                 + "}"

说明：

  • channl_id：取发放卡券时候设置的值
  • serial_number： 取发放成功的卡券的值
    API详细文档：更新卡券接口

卡券模板更新

接口列表：更新模板接口（alipay.pass.template.update）SDK 调用示例：

  1. /**
  2.  * 更新模板
  3.  * appAuthToken如ISV代替商家调用接口，需将商户授权后获取的app_auth_token带上；如商家自己调用，则传null。
  4.  * bizContent 因该接口业务参数复杂，请详见接口文档 
  5.  */
  6.  AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");
  7.  AlipayPassTemplateUpdateRequest request = new AlipayPassTemplateUpdateRequest();
  8.  request.putOtherTextParam("app_auth_token", appAuthToken);
  9.  request.setBizContent(bizContent);
  10.  AlipayPassTemplateUpdateResponse response = alipayClient.execute(request);
  11.  System.out.print(response.getBody());//根据业务处理response

app_auth_token在 ISV 代替商家调用接口时使用，商家自己调用，可传 null。bizContent Json串示例：

  1. "{\"tpl_id\":\"2016071516121584501489290\"," //支付宝对该参数的请求有唯一性校验，请保证每次请求该参数唯一
  2.                 + "\"tpl_content\":"
  3.                 + "{\"logo\":\"https://alipass.alipay.com//temps/free/logo.png\","
  4.                 + "\"strip\":\"https://alipass.alipay.com//temps/free/strip.png\","
  5.                 + "\"icon\":\"http://alipassprod.test.alipay.net/temps/free/icon.png\","
  6.                 + "\"content\":"
  7.                 + "{\"evoucherInfo\":"
  8.                 + "{\"title\":\"萧萧沫沫优惠券\",\"type\":\"coupon\",\"product\":\"free\",\"startDate\":\"$validStartDate$\",\"endDate\":\"$validEndDate$\",\"operation\":"
  9.                 + "[{\"format\":\"barcode\",\"message\":\"45612346579465\",\"messageEncoding\":\"UTF-8\",\"altText\":\"45612346579465\"}],"
  10.                 + "\"einfo\":{"
  11.                 + "\"logoText\":\"$logoText$\","
  12.                 + "\"headFields\":"
  13.                 + "[{\"key\":\"status\",\"label\":\"状态\",\"value\":\"$useStateDesc$\",\"type\":\"text\"}],"
  14.                 + "\"primaryFields\":"
  15.                 + "[{\"key\":\"strip\",\"label\":\"\",\"value\":\"$discountInfo$\",\"type\":\"text\"}],"
  16.                 + "\"secondaryFields\":"
  17.                 + "[{\"key\":\"validDate\",\"label\":\"有效期至：\",\"value\":\"$validEndDate$\",\"type\":\"text\"}],"
  18.                 + "\"auxiliaryFields\":[],"
  19.                 + "\"backFields\":"
  20.                 + "[{\"key\":\"description\",\"label\":\"详情描述\",\"value\":\"1.该优惠有效期：截止至2014年06月18日；\n2.凭此券可以享受以下优惠：\n享门市价优惠\n不与其他优惠同享。详询商家。\",\"type\":\"text\"},"
  21.                 + "{\"key\":\"shops\",\"label\":\"可用门店\",\"value\":\"\",\"type\":\"text\"},"
  22.                 + "{\"key\":\"disclaimer\",\"label\":\"负责声明\",\"value\":\"除特殊注明外，本优惠不能与其他优惠同时享受；本优惠最终解释权归商家所有，如有疑问请与商家联系。提示：为了使您得到更好的服务，请在进店时出示本券。\",\"type\":\"text\"}"
  23.                 + "]},"
  24.                 + "\"remindInfo\":"
  25.                 + "{\"offset\":\"2\"}},"
  26.                 + "\"merchant\":{\"mname\":\"hodewu\",\"mtel\":\"\",\"minfo\":\"\"},"
  27.                 + "\"platform\":{\"channelID\":\"$channelID$\",\"webServiceUrl\":\"\"},"
  28.                 + "\"style\":{\"backgroundColor\":\"RGB(255,126,0)\"},"
  29.                 + "\"fileInfo\":{\"formatVersion\":\"2\",\"canShare\":true,\"canBuy\":false,\"canPresent\":true,\"serialNumber\":\"$serialNumber$\",\"supportTaxi\":\"true\",\"taxiSchemaUrl\":\"alipays://platformapi/startapp?appId=20000130&sourceId=20000030&showTitleBar=YES&showToolBar=NO&showLoading=NO&safePayEnabled=YES&readTitle=YES&backBehavior=back&url=/www/index.html\"},"
  30.                 + "\"appInfo\":{\"app\":{},\"label\":\"\",\"message\":\"\"},"
  31.                 + "\"source\":\"alipassprod\","
  32.                 + "\"alipayVerify\":[]"
  33.                 + "}}}"

说明：

  • tpl_id 即为需要修改的模板id，从创建模板接口中调用成功之后获取。
  • tpl_content 即为创建模板时的 json 内容，并修改其中需要更新的节点和内容。
    API详细文档：更新模板接口

小程序跳转到卡包列表或详情页

当用户领取卡券后，可在小程序中展示券、票，可引导用户点击跳转到支付宝卡包页面API详细调用文档：跳转卡包接口

API介绍

支付宝卡包API列表

接口名称接口描述
alipay.pass.template.add新建卡券模板
alipay.pass.template.update更新卡券模板
alipay.pass.instance.add发布卡券
alipay.pass.instance.update更新卡券

小程序跳转到支付宝卡包API列表

接口名称接口描述
my.openVoucherList打开支付宝卡包中的“券”列表
my.openMerchantVoucherList打开当前用户领取某个商户的“券”列表
my.openVoucherDetail打开当前用户领取某张券的详情页（非口碑券）
my.openKBVoucherDetail打开当前用户领取某张券的详情页（口碑券）
my.openTicketList打开支付宝卡包中的“票”列表
my.openMerchantTicketList打开当前用户领取某个商户的“票”列表
my.openTicketDetail打开当前用户领取某张票的详情页