支付宝卡包产品介绍

由 ✎﹏๓₯㎕ζั͡❦﹏﹏♛ 创建, 最后一次修改 2017-11-08

支付宝卡包产品介绍

[TOC]

1.产品介绍

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

什么是支付宝卡包2

1.1 产品能力

产品特色

产品生命周期: 支付宝卡包产品特色

使用场景

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

应用案例

电子门票使用流程

支付宝卡包电子门票使用流程

支付宝卡包电子门票使用流程2

产品关联推荐

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

准入条件

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

计费模式

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

2.接入指引

2.1 添加支付宝卡包

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

2.2接入支付宝卡包

卡包术语介绍

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

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

2.3接口调用

使用说明

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

1.创建卡券模版: 支付宝卡包创建卡券模版

2.创建卡券: 支付宝创建卡券

接口调用流程

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

创建卡券模板

/**
 * 新建模板
 * appAuthToken如ISV代替商家调用接口,需将商户授权后获取的app_auth_token带上;如商家自己调用,则传null。
 * bizContent 因该接口业务参数复杂,请详见接口文档
 */
 AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");
 AlipayPassTemplateAddRequest request = new AlipayPassTemplateAddRequest();
 request.putOtherTextParam("app_auth_token", appAuthToken);
 request.setBizContent(bizContent);
 AlipayPassTemplateAddResponse response=alipayClient.execute(request);
 System.out.print(response.getBody());//根据业务处理response
  • app_auth_token在ISV代替商家调用接口时使用,商家自己调用,可传null。
  • bizContent Json串示例:
"{\"unique_id\":\"143512639346821\"," //支付宝对该参数的请求有唯一性校验,请保证每次请求该参数唯一
                + "\"tpl_content\":"
                + "{\"logo\":\"https://alipass.alipay.com//temps/free/logo.png\","
                + "\"strip\":\"https://alipass.alipay.com//temps/free/strip.png\","
                + "\"icon\":\"http://alipassprod.test.alipay.net/temps/free/icon.png\","
                + "\"content\":{"
                + "\"evoucherInfo\":"
                + "{\"title\":\"风情优惠券\","
                + "\"type\":\"coupon\","
                + "\"product\":\"free\","
                + "\"startDate\":\"$validStartDate$\","
                + "\"endDate\":\"$validEndDate$\","
                + "\"operation\":"
                + "[{\"format\":\"barcode\",\"message\":\"$code$\",\"messageEncoding\":\"UTF-8\",\"altText\":\"$code$\"}],"
                + "\"einfo\":{"
                + "\"logoText\":\"$logoText$\","
                + "\"headFields\":"
                + "[{\"key\":\"status\",\"label\":\"状态\",\"value\":\"$useStateDesc$\",\"type\":\"text\"}],"
                + "\"primaryFields\":"
                + "[{\"key\":\"strip\",\"label\":\"\",\"value\":\"$discountInfo$\",\"type\":\"text\"}],"
                + "\"secondaryFields\":"
                + "[{\"key\":\"validDate\",\"label\":\"有效期至:\",\"value\":\"$validEndDate$\",\"type\":\"text\"}],"
                + "\"auxiliaryFields\":[],"
                + "\"backFields\":"
                + "[{\"key\":\"description\",\"label\":\"详情描述\",\"value\":\"1.该优惠有效期:截止至2014年06月18日;\n2.凭此券可以享受以下优惠:\n享门市价优惠\n不与其他优惠同享。详询商家。\",\"type\":\"text\"},"
                + "{\"key\":\"shops\",\"label\":\"可用门店\",\"value\":\"\",\"type\":\"text\"},"
                + "{\"key\":\"disclaimer\",\"label\":\"负责声明\",\"value\":\"除特殊注明外,本优惠不能与其他优惠同时享受;本优惠最终解释权归商家所有,如有疑问请与商家联系。提示:为了使您得到更好的服务,请在进店时出示本券。\",\"type\":\"text\"}"
                + "]},"
                + "\"remindInfo\":{\"offset\":\"2\"}},"
                + "\"merchant\":{\"mname\":\"hodewu\",\"mtel\":\"\",\"minfo\":\"\"},"
                + "\"platform\":{\"channelID\":\"$channelID$\",\"webServiceUrl\":\"\"},"
                + "\"style\":{\"backgroundColor\":\"RGB(255,126,0)\"},"
                + "\"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\"},"
                + "\"appInfo\":"
                + "{\"app\":{},\"label\":\"\",\"message\":\"\"},"
                + "\"source\":\"alipassprod\","
                + "\"alipayVerify\":[]"
                + "}}}"

说明:

  1. 模板中的自定义参数以双 $ 符号标志,即 $serialNumber$ 表示自定义参数名为serialNumber,供发放卡券时使用
  2. unique_id参数支付宝有唯一性校验,请保证每次请求该值唯一;

发放卡券

  • 接口列表:发放卡券接口(alipay.pass.instance.add)
  • SDK调用示例:
/**
 * 发放卡券
 * appAuthToken如ISV代替商家调用接口,需将商户授权后获取的app_auth_token带上;如商家自己调用,则传null。
 * bizContent 因该接口业务参数复杂,请详见接口文档 
 */
 AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");
 AlipayPassInstanceAddRequest request = new AlipayPassInstanceAddRequest();
 request.putOtherTextParam("app_auth_token", appAuthToken);
 request.setBizContent(bizContent);
 AlipayPassInstanceAddResponse response = alipayClient.execute(request);

 System.out.print(response.getBody());//根据业务处理response
  • app_auth_token在ISV代替商家调用接口时使用,商家自己调用,可传null
  • bizContent Json串示例:
    "{\"recognition_type\":\"1\","
                + "\"tpl_id\":\"2016072715135409252622447\","
                + "\"recognition_info\":{\"partner_id\":\"2088**********10\","
                + "\"out_trade_no\":\"xiaomoxiaomotest7629500\"}," 
                + "\"tpl_params\":"
                + "{"
                + "\"validStartDate\":\"2016-06-30 20:00:00\","
                + "\"validEndDate\":\"2016-12-30 20:00:00\","
                + "\"channelID\":\"2088**********10\","
                + "\"discountInfo\":\"凭此券即可打8.5折\","
                + "\"code\":\"20160725762587i\","
                +"\"useStateDesc\":\"可使用\","
                +"\"logoText\":\"四季风情85折优惠券\","
                + "\"serialNumber\":\"xm433367366244615532\"}}";

说明:

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

核销卡券

  • 接口列表:更新卡券接口(alipay.pass.instance.update)
  • SDK调用示例
/**
 * 
 * appAuthToken如ISV代替商家调用接口,需将商户授权后获取的app_auth_token带上;如商家自己调用,则传null。
 * bizContent 因该接口业务参数复杂,请详见接口文档
 */
 AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");
 AlipayPassInstanceUpdateRequest request = new AlipayPassInstanceUpdateRequest();
 request.putOtherTextParam("app_auth_token", appAuthToken);
 request.setBizContent(bizContent);
 AlipayPassInstanceUpdateResponse response = alipayClient.execute(request);

 System.out.print(response.getBody());//根据业务处理response
  • app_auth_token在ISV代替商家调用接口时使用,商家自己调用,可传null。
  • bizContent Json串示例:
"{\"status\":\"USED\","
                + "\"channel_id\":\"2088**********10\"," 
                + "\"serial_number\":\"xm433367366244615532\","
                + "\"tpl_params\":"
                + "{\"useStateDesc\":\"已使用\"}"
                + "}"

说明:

  1. channl_id取发放卡券时候设置的值
  2. serial_number取发放成功的卡券的值

卡券模板更新

接口列表:更新模板接口(alipay.pass.template.update)

  • SDK调用示例:
/**
 * 更新模板
 * appAuthToken如ISV代替商家调用接口,需将商户授权后获取的app_auth_token带上;如商家自己调用,则传null。
 * bizContent 因该接口业务参数复杂,请详见接口文档 
 */
 AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");
 AlipayPassTemplateUpdateRequest request = new AlipayPassTemplateUpdateRequest();
 request.putOtherTextParam("app_auth_token", appAuthToken);
 request.setBizContent(bizContent);
 AlipayPassTemplateUpdateResponse response = alipayClient.execute(request);
 System.out.print(response.getBody());//根据业务处理response
  • app_auth_token在ISV代替商家调用接口时使用,商家自己调用,可传null。
  • bizContent Json串示例:
    "{\"tpl_id\":\"2016071516121584501489290\"," //支付宝对该参数的请求有唯一性校验,请保证每次请求该参数唯一
                + "\"tpl_content\":"
                + "{\"logo\":\"https://alipass.alipay.com//temps/free/logo.png\","
                + "\"strip\":\"https://alipass.alipay.com//temps/free/strip.png\","
                + "\"icon\":\"http://alipassprod.test.alipay.net/temps/free/icon.png\","
                + "\"content\":"
                + "{\"evoucherInfo\":"
                + "{\"title\":\"萧萧沫沫优惠券\",\"type\":\"coupon\",\"product\":\"free\",\"startDate\":\"$validStartDate$\",\"endDate\":\"$validEndDate$\",\"operation\":"
                + "[{\"format\":\"barcode\",\"message\":\"45612346579465\",\"messageEncoding\":\"UTF-8\",\"altText\":\"45612346579465\"}],"
                + "\"einfo\":{"
                + "\"logoText\":\"$logoText$\","
                + "\"headFields\":"
                + "[{\"key\":\"status\",\"label\":\"状态\",\"value\":\"$useStateDesc$\",\"type\":\"text\"}],"
                + "\"primaryFields\":"
                + "[{\"key\":\"strip\",\"label\":\"\",\"value\":\"$discountInfo$\",\"type\":\"text\"}],"
                + "\"secondaryFields\":"
                + "[{\"key\":\"validDate\",\"label\":\"有效期至:\",\"value\":\"$validEndDate$\",\"type\":\"text\"}],"
                + "\"auxiliaryFields\":[],"
                + "\"backFields\":"
                + "[{\"key\":\"description\",\"label\":\"详情描述\",\"value\":\"1.该优惠有效期:截止至2014年06月18日;\n2.凭此券可以享受以下优惠:\n享门市价优惠\n不与其他优惠同享。详询商家。\",\"type\":\"text\"},"
                + "{\"key\":\"shops\",\"label\":\"可用门店\",\"value\":\"\",\"type\":\"text\"},"
                + "{\"key\":\"disclaimer\",\"label\":\"负责声明\",\"value\":\"除特殊注明外,本优惠不能与其他优惠同时享受;本优惠最终解释权归商家所有,如有疑问请与商家联系。提示:为了使您得到更好的服务,请在进店时出示本券。\",\"type\":\"text\"}"
                + "]},"
                + "\"remindInfo\":"
                + "{\"offset\":\"2\"}},"
                + "\"merchant\":{\"mname\":\"hodewu\",\"mtel\":\"\",\"minfo\":\"\"},"
                + "\"platform\":{\"channelID\":\"$channelID$\",\"webServiceUrl\":\"\"},"
                + "\"style\":{\"backgroundColor\":\"RGB(255,126,0)\"},"
                + "\"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\"},"
                + "\"appInfo\":{\"app\":{},\"label\":\"\",\"message\":\"\"},"
                + "\"source\":\"alipassprod\","
                + "\"alipayVerify\":[]"
                + "}}}"

    说明:

  1. tpl_id即为需要修改的模板id,从创建模板接口中调用成功之后获取;
  2. tpl_content即为创建模板是的json内容,并修改其中需要更新的节点和内容;

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

当用户领取卡券后,可在小程序中展示券、票,可引导用户点击跳转到支付宝卡包页面

3.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 打开当前用户领取某张票的详情页
W3Cschool app 编程微课功能上线
二维码
建议反馈
二维码