支付宝卡包产品介绍
支付宝卡包产品介绍
[TOC]
1.产品介绍
什么是支付宝卡包（alipass）?
支付宝卡包（alipass），是支付宝公司推出的一款可以管理电子凭证的产品，该产品聚合来自各类生活服务的票据凭证，包括优惠券、折扣券、代金券、换购券、电影票、演出票、火车票、机票。
1.1 产品能力
产品特色
产品生命周期：
使用场景
企业或者个人开发者可以通过支付宝提供的开放接口，把卡券添加到支付宝卡包，用户可以通过小程序查看卡券，同时支持跳转到支付宝卡包页面，在卡包中查看并使用商户同步进来的卡券。
应用案例
电子门票使用流程
产品关联推荐
- 商家方面，覆盖面比较广，涉及到所有发核券的商家均可使用。
- 公共事业方面，也可以拓展，如：电子地铁票等。
准入条件
- 公司运营稳定，具有一定的客户群。具体考核将参考公司运营时长、规模、用户数来做出综合判定；
- 公司具备一定的技术能力，能够独立完成技术对接；
- 支持合作后的服务联动处理，数据反馈和异议处理。
计费模式
免费接口，暂未收取费用。
2.接入指引
2.1 添加支付宝卡包
在小程序“开发管理”详情页的“功能列表”中添加“支付宝卡包”
2.2接入支付宝卡包
卡包术语介绍
以下是支付宝卡包接口开发过程中需要了解的常用概念：
| 名称 | 描述 |
|---|---|
| 模板/卡券模板（template） | 模板包含了开发者设计的卡券的样式、内容信息。基于此模板的样式，开发者可以向用户发放卡券，一个模板可以对应多个卡券，模板内容样式的变化会引起卡券的变化。 |
| 模板编号（templateId） | 模板的唯一标识，由创建模板成功后，接口返回给商户，基于此参数创建卡券。 |
| 卡券ID（passId） | 卡券ID，唯一代表一张卡券。可以多个卡券ID对应一个模板。由卡券创建成功后返回。 |
2.3接口调用
使用说明
商家通过开放平台提供的alipass接口，可完成从卡券模板设计到卡券实体构造整个流程。
1.创建卡券模版：
2.创建卡券：
接口调用流程
支付宝卡券整体接口调用流程：
创建卡券模板
- 模板设计：推荐使用卡券平台（https://alipassprod.alipay.com），在线编辑获取JSON模板
-
详细可参见：支付宝卡包API详细说明
- 接口列表：创建卡券模板接口（alipay.pass.template.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");
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":[]"
+ "}}}"说明：
- 模板中的自定义参数以双
$符号标志，即$serialNumber$表示自定义参数名为serialNumber，供发放卡券时使用 -
unique_id参数支付宝有唯一性校验，请保证每次请求该值唯一；
- API详细文档：创建卡券模板接口
发放卡券
- 接口列表：发放卡券接口（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"}}";
说明：
- tpl_params中的json节点即为模板创建时设置的自定义参数（即模板中定义的 $xxxx$ ），每次发券可以自己定义内容，且其中的serialNumber支付宝有唯一性校验，每次请求请保证唯一性，不要重复
- tpl_id：调用模板创建接口成功后返回模板ID，该ID用于发放券票
- recognition_info:真实存在的支付宝交易，需要提供该交易的外部订单号和对应的商户PID
- channelID：可设置为APPID（从创建应用处获取）或者PID
- API详细文档：发放卡券接口
核销卡券
- 接口列表：更新卡券接口（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":"已使用"}"
+ "}"说明：
-
channl_id取发放卡券时候设置的值 -
serial_number取发放成功的卡券的值
- API详细文档：更新卡券接口
卡券模板更新
接口列表：更新模板接口（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":[]" + "}}}"说明：
-
tpl_id即为需要修改的模板id，从创建模板接口中调用成功之后获取； -
tpl_content即为创建模板是的json内容，并修改其中需要更新的节点和内容；- API详细文档：更新模板接口
小程序跳转到卡包列表或详情页
当用户领取卡券后，可在小程序中展示券、票，可引导用户点击跳转到支付宝卡包页面
- API详细调用文档：跳转卡包接口
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 | 打开当前用户领取某张票的详情页 |
