文档中心 > 开放平台

开放平台

支付宝卡包快速接入

更新时间：2017/03/30 访问次数：50826

卡包术语介绍

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

名称 描述

模板/卡券模板（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
有用(11) 我要提问
文档标签:
卡券
返回
顶部
阿里巴巴集团 | 淘宝网 | 天猫 | 聚划算 | 全球速卖通 | 阿里巴巴国际交易市场 | 1688 | 阿里妈妈 | 阿里旅行·去啊 | 阿里云计算 | YunOS | 阿里通信 | 万网 | 高德 | 优视 | 友盟 | 酷盘 | 虾米 | 天天动听 | 来往 | 钉钉 | 11Main | 支付宝
关于淘宝 合作伙伴 营销中心 联系客服 开放平台 诚征英才 联系我们 网站地图 法律声明 © 2016 Taobao.com 版权所有
网络文化经营许可证：文网文[2010]040号 | 增值电信业务经营许可证：浙B2-20080224-1 | 信息网络传播视听节目许可证：1109364号