文档中心 > 开放平台

卡包术语介绍

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

名称 描述

模板/卡券模板(template)

模板包含了开发者设计的卡券的样式、内容信息。基于此模板的样式,开发者可以向用户发放卡券,一个模板可以对应多个卡券,模板内容样式的变化会引起卡券的变化。

模板编号(templateId)

模板的唯一标识,由创建模板成功后,接口返回给商户,基于此参数创建卡券。

卡券ID(passId)

卡券ID,唯一代表一张卡券。可以多个卡券ID对应一个模板。由卡券创建成功后返回。

授权访问令牌(app_auth_token)

开发者帮助商户发券场景,如何获取,详见“第三方应用授权”。

第一步:创建应用并获取APPID

要在您的应用中使用支付宝开放产品的接口能力,您需要先去蚂蚁金服开放平台(open.alipay.com),在开发者中心中创建登记您的应用,并提交审核,审核通过后会为您生成应用唯一标识(APPID),并且可以申请开通开放产品使用权限,通过APPID您的应用才能调用开放产品的接口能力。创建应用后,请在【功能信息】中点击【添加功能】,选择【支付宝卡券】,待应用上线后,支付宝卡券的权限即可开通。需要详细了解开放平台创建应用步骤请参考《开放平台应用创建指南》。

第二步:配置密钥

开发者调用接口前需要先生成RSA密钥,RSA密钥包含应用私钥(APP_PRIVATE_KEY)、应用公钥(APP_PUBLIC_KEY)。生成密钥后在开放平台开发者中心进行密钥配置,配置完成后可以获取支付宝公钥(ALIPAY_PUBLIC_KEY)。详情请参考《配置应用环境》。

第三步:搭建和配置开发环境

1. 下载服务端SDK

为了帮助开发者调用开放接口,我们提供了开放平台服务端SDK,包含JAVA、PHP和.NET三个语言版本,封装了签名&验签、HTTP接口请求等基础功能。请先下载对应语言版本的SDK并引入您的开发工程。

各语言版本服务端SDK详细使用说明,请参考《服务端SDK说明》。

2. 接口调用配置

在SDK调用前需要进行初始化,以Java代码为示例如下:

AlipayClient alipayClient = new DefaultAlipayClient(URL, APP_ID, APP_PRIVATE_KEY, FORMAT, CHARSET, ALIPAY_PUBLIC_KEY, SIGN_TYPE);

关键参数说明:

配置参数 示例值解释 获取方式/示例值
URL 支付宝网关(固定) https://openapi.alipay.com/gateway.do
APPID APPID 即创建应用后生成 获取见上面创建应用并获取APPID
APP_PRIVATE_KEY 开发者私钥,由开发者自己生成 获取详见上面配置密钥
FORMAT 参数返回格式,只支持json json(固定)
CHARSET 编码集,支持GBK/UTF-8 开发者根据实际工程编码配置
ALIPAY_PUBLIC_KEY 支付宝公钥,由支付宝生成 获取详见上面配置密钥
SIGN_TYPE 商户生成签名字符串所使用的签名算法类型,目前支持RSA2和RSA,推荐使用RSA2 RSA2

第四步:接口调用

创建卡券模板

>>模板设计:推荐使用卡券平台(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
TIPS:APPID从 创建应用处获取,APP_PRIVATE_KEY和ALIPAY_PUBLIC_KEY从 配置密钥处获取,CHARSET为编码格式,GBK或者UTF-8等

>>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参数支付宝有唯一性校验,请保证每次请求该值唯一;

>>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\"}}";

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

>>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\":\"已使用\"}"
                + "}"

说明:1.channl_id取发放卡券时候设置的值
         2.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\":[]"
                + "}}}"

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

>>API详细文档:更新模板接口

 

接口调用流程

支付宝卡券产品包含以下接口:

接口名称 接口描述

新建模板
alipay.pass.template.add

创建卡券的模板,卡券的样式、内容信息通过该接口提交到支付宝,支付宝会生成模板ID反馈给开发者,用于后续的更新和发布。

更新模板
alipay.pass.template.update

对于已经创建的模板,如果需要修改模板内容,可通过该接口修改,适用于修改模板内容。对于已经发布的模板,如果需要修改内容并同步到用户端,则应使用更新卡券接口。

发布卡券
alipay.pass.instance.add

卡券模板生成后,如需将卡券发布给对应的用户,则调用此接口。

更新卡券
alipay.pass.instance.update

对于已经发布的卡券,如需更新内容,可通过此接口更新,主要用于更新卡券的使用状态。

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

关于沙箱

如何接入沙箱

      沙箱是开放平台提供给开发者用户调试接口的环境,具体操作步骤见 沙箱接入指南

支付宝卡包沙箱接入注意点

      1、支付宝卡包支持沙箱接入;在沙箱调通接口后,必须在线上进行测试与验收,所有返回码及业务逻辑以线上为准;
      2、可使用沙箱钱包查看卡券效果。

FAQ

关于此文档暂时还没有FAQ
返回
顶部
onlineServer