支付宝卡包产品介绍
支付宝卡包产品介绍
[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 | 打开当前用户领取某张票的详情页 |
更多建议: