文档中心 > 开放平台

开放平台

商户会员卡快速接入

更新时间：2017/07/03 访问次数：50397

第一步：创建应用

要在您的应用中使用支付宝开放产品的接口能力，您需要先去蚂蚁金服开放平台（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调用前需要进行初始化，代码如下：

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
TIPS：ISV/开发者可以通过“第三方应用授权”得到商户授权令牌（app_auth_token）作为请求参数传入，实现代商户发起请求的能力；具体方法请参考 第三方应用授权。

第四步：接口调用

创建会员卡模板

>>接口列表：会员卡模板创建（alipay.marketing.card.template.create）

>>会员卡模板模型介绍

  • 模板基本信息：会员卡名称、会员卡类型、核销方式等基本信息；
  • 模板样式信息：卡包详情页面的会员卡展现效果；
  • 会员权益信息：会员卡模板定义的会员权益是通用权益，其下发行的所有会员卡会继承该模板定义的通用权益；
  • 模板栏位信息：在卡包详情页面展现的会员卡功能栏位；
  • 会员卡属性规则：会员卡属性规则主要用于说明开卡流程中，如何从请求参数中解析会员卡信息。

>>SDK调用示例：

/**
 * 创建会员卡模板
 * @param appAuthToken如ISV代替商户调用接口，需将商户授权后获取的app_auth_token带上；如商户自己调用，则传null。
 * @param bizContent 因该接口业务参数复杂，请详见接口文档
 * @return
 * @throws AlipayApiException 请处理异常
 */
 AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2"); 
 AlipayMarketingCardTemplateCreateRequest request = new AlipayMarketingCardTemplateCreateRequest();
 request.putOtherTextParam("app_auth_token", appAuthToken);
 request.setBizContent(bizContent);
 AlipayMarketingCardTemplateCreateResponse response=alipayClient.execute(request);
 System.out.println(response.getBody());

>>app_auth_token在ISV代替商户调用接口时使用，商户自己调用，可传null。

>>bizContent Json串示例：

"{"
				+ "\"request_id\":\"20160805100000023100679\","
				+ "\"card_type\":\"OUT_MEMBER_CARD\","
				+ "\"biz_no_prefix\":\"prexupdate\","
				+ "\"biz_no_suffix_len\":\"10\","
				+ "\"write_off_type\":\"qrcode\","
				+ "\"template_style_info\":{"
				+ "\"card_show_name\":\"花呗会员卡测试\","
				+ "\"logo_id\":\"OKWBUiWCQ761MdRzP4PvUwAAACM****\","
				+ "\"color\":\"rgb(55,112,179)\","
				+ "\"background_id\":\"OKWBUiWCQ761MdRzP4PvUwAAACMA****\","
				+ "\"bg_color\":\"rgb(55,112,179)\"},"
				+ "\"template_benefit_info\":[{\"title\":\"消费即折扣\","
				+ "\"benefit_desc\":[\"消费即折扣\",\"会员日7折扣\"],"
				+ "\"start_date\":\"2016-08-18 15:17:23\","
				+ "\"end_date\":\"2016-09-14 12:12:12\"}],"
				+ "\"column_info_list\":[{\"code\":\"BENEFIT_INFO\",\"more_info\":{\"title\":\"扩展信息\",\"url\":\"http://www.baidu.com\","
				+ "\"params\":\"{}\"},"
				+ "\"title\":\"专属权益修改\",\"operate_type\":\"openWeb\",\"value\":\"会员权益\"},"
				+"{\"code\":\"BALANCE\",\"title\":\"余额\",\"value\":\"\"},"
	            +"{\"code\":\"TELEPHOME\",\"title\":\"手机号码\",\"value\":\"15000784967\"},"
	            +"{\"code\":\"Point\",\"title\":\"积分\",\"value\":\"100\"}"
				+ "],"
				+ "\"field_rule_list\":[{\"field_name\":\"Balance\",\"rule_name\":\"ASSIGN_FROM_REQUEST\",\"rule_value\":\"Balance\"},"
				+ "{\"field_name\":\"Point\",\"rule_name\":\"CONST\",\"rule_value\":\"100\"}]}"

说明：

1.request_id为请求唯一标识，每次请求请保证唯一性；

2.logo_id和background_id通过支付宝图片资料上传接口（alipay.offline.material.image.upload）获取；

3.logo图片规范：1M以内，格式：bmp，png，jpeg，jpg，gif；尺寸不小于500px*500px的等边矩形；请优选使用商户logo；

   background图片规范：2M以内，格式：bmp，png，jpeg，jpg，gif；尺寸不小于1020px*643px的等边矩形；图片不得有圆角，不得拉伸变形；

4.具体json字段说明，请查看创建会员卡模板

 

会员卡开卡

>>接口列表:会员卡开卡(alipay.marketing.card.open)

>>会员卡模型介绍

会员卡开卡需要根据支付宝端的模板ID，为用户发行商户会员卡。针对商户发行的会员卡，调用会员开卡接口，主要完成商户会员卡的电子化，从而在钱包端展现会员卡，同时将卡信息保存至支付宝系统。

会员卡请求模型主要包含开卡请求基本信息（如外部流水号、会员卡模板等），会员信息，会员卡信息和扩展信息这几个部分。

>>SDK调用示例：

/**
 * 会员卡开卡
 * @param appAuthToken如ISV代替商户调用接口，需将商户授权后获取的app_auth_token带上；如商户自己调用，则传null。
 * @param bizContent 因该接口业务参数复杂，请详见接口文档
 * @return
 * @throws AlipayApiException 请处理异常
 */
 AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2"); 
 AlipayMarketingCardOpenRequest request = new AlipayMarketingCardOpenRequest();
 request.putOtherTextParam("app_auth_token", appAuthToken);
 request.setBizContent(bizContent);
 AlipayMarketingCardOpenResponse response = alipayClient.execute(request,accessToken);
 System.out.println(response.getBody());

>>app_auth_token在ISV代替商户调用接口时使用，商户自己调用，可传null；

>>accessToken通过用户信息授权获取，其中第一步url拼接中scope的值必需设置为auth_ecard；

>>bizContent Json串示例：

"{" 
		+"\"out_serial_no\":\"2016100910482088139\","//唯一标识
		+"\"card_template_id\":\"2016100900000000001410200030****\","//会员卡模板id，通过模板创建接口返回得到 
		+"\"card_user_info\":{" 
		+"\"user_uni_id\":\"20884025********\"," //支付宝userid(一般2088开头)
		+"\"user_uni_id_type\":\"UID\"}," 
		+"\"card_ext_info\":{\"external_card_no\":\"EXT0003\","//商户会员卡卡号
		+ "\"open_date\":\"2016-10-08 14:20:00\",\"valid_date\":\"2020-02-20 21:20:46\",\"level\":\"VIP1\",\"point\":\"88\",\"balance\":\"124.89\"}," 
		+"\"member_ext_info\":{\"name\":\"萧沫\",\"gende\":\"FEMALE\",\"birth\":\"2016-06-27\",\"cell\":\"13000000000\"}}"

说明：

1.out_serial_no为唯一标识号，每次请求保障唯一；

2.card_template_id为模板id，通过会员卡模板创建接口获取；

3.user_uni_id为支付宝账户userid，为2088开头的16为数字，通过用户信息授权获取；

4.具体json字段说明，请查看会员卡开卡

5.开卡成功后，登录到userid对应账号的支付宝钱包内卡券类目下查看发送成功的会员卡；

 

会员卡查询接口

>>接口列表：会员卡查询(alipay.marketing.card.query)

>>SDK调用示例：

/**
 * 会员卡查询
* @param appAuthToken如ISV代替商户调用接口，需将商户授权后获取的app_auth_token带上；如商户自己调用，则传null。
 * @param bizContent 因该接口业务参数复杂，请详见接口文档
 * @return
 * @throws AlipayApiException 请处理异常
 */
 AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2"); 
 AlipayMarketingCardQueryRequest request = new AlipayMarketingCardQueryRequest();
 request.putOtherTextParam("app_auth_token", appAuthToken);
 request.setBizContent(bizContent);
 AlipayMarketingCardQueryResponse response = alipayClient.execute(request);
 System.out.println(response.getBody());

 >>bizContent Json串示例：

"{" 
				+"\"target_card_no\":\"prex0000001781\"," 
				+"\"target_card_no_type\":\"BIZ_CARD\"," 
				+"\"card_user_info\":{" 
				+"\"user_uni_id\":\"20884025********\"," 
				+"\"user_uni_id_type\":\"UID\"" 
				+"}}"

 说明：

1.target_card_no为会员卡业务号，在调用开卡接口成功后支付宝返回的biz_card_no参数的值；

2.user_uni_id为支付宝用户号userid，为2088开头的16位数字；

3.具体json字段说明，请查看会员卡查询

 

会员卡更新接口

>>接口列表：会员卡更新(alipay.marketing.card.update)

>>SDK调用示例：

/**
 * 会员卡更新
* @param appAuthToken如ISV代替商户调用接口，需将商户授权后获取的app_auth_token带上；如商户自己调用，则传null。
 * @param bizContent 因该接口业务参数复杂，请详见接口文档
 * @return
 * @throws AlipayApiException 请处理异常
 */
 AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");
 AlipayMarketingCardUpdateRequest request = new AlipayMarketingCardUpdateRequest();
 request.putOtherTextParam("app_auth_token", appAuthToken);
 request.setBizContent(bizContent);
 AlipayMarketingCardUpdateResponse response = alipayClient.execute(request);
 System.out.println(response.getBody());

>>bizContent Json串示例：

"{"
				+"\"target_card_no\":\"prex0000002507\"," 
				+"\"target_card_no_type\":\"BIZ_CARD\"," 
				+"\"occur_time\":\"2016-09-27 12:12:12\"," 
				+"\"card_info\":{" 
				+"\"open_date\":\"2014-02-20 21:20:46\"," 
				+"\"valid_date\":\"2020-02-20 21:20:46\"," 
				+"\"level\":\"VIP1\"," 
				+"\"point\":\"188\"," 
				+"\"balance\":\"128\"}"
				+"}"

 说明：

1.target_card_no为会员卡业务号，在调用开卡接口成功后支付宝返回的biz_card_no参数的值；

2.具体json字段说明，请查看会员卡更新

 

会员卡删除接口

>>接口列表：会员卡删卡(alipay.marketing.card.delete)

>>SDK调用示例：

/**
 * 会员卡删除
* @param appAuthToken如ISV代替商户调用接口，需将商户授权后获取的app_auth_token带上；如商户自己调用，则传null。
 * @param bizContent 因该接口业务参数复杂，请详见接口文档
 * @return
 * @throws AlipayApiException 请处理异常
 */
 AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");
 AlipayMarketingCardDeleteRequest request = new AlipayMarketingCardDeleteRequest();
 request.putOtherTextParam("app_auth_token", appAuthToken);
 request.setBizContent(bizContent);
 AlipayMarketingCardDeleteResponse response = alipayClient.execute(request);
 System.out.println(response.getBody());

 >>bizCotent Json示例：

"{" 
				+"\"out_serial_no\":\"2016100910482088139\"," 
				+"\"target_card_no\":\"prexupdate0000002781\"," 
				+"\"target_card_no_type\":\"BIZ_CARD\"," 
				+"\"reason_code\":\"USER_UNBUND\"" 
				+"}"

 说明：

1.out_serial_no为开卡时的唯一标识，调用开卡接口时做保存记录；

2.target_card_no为会员卡业务号，调用开卡接口成功后支付宝返回的biz_card_no参数的值；

3.具体json字段说明，请查看会员卡删卡

 

会员卡消费记录同步接口

>>接口列表：会员卡消费记录同步(alipay.marketing.card.consume.sync)

>>SDK调用示例：

/**
 * 会员卡消费记录同步
* @param appAuthToken如ISV代替商户调用接口，需将商户授权后获取的app_auth_token带上；如商户自己调用，则传null。
 * @param bizContent 因该接口业务参数复杂，请详见接口文档
 * @return
 * @throws AlipayApiException 请处理异常
 */
 AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");
 AlipayMarketingCardConsumeSyncRequest request = new AlipayMarketingCardConsumeSyncRequest();
 request.putOtherTextParam("app_auth_token", appAuthToken);
 request.setBizContent(bizContent);
 AlipayMarketingCardConsumeSyncResponse response = alipayClient.execute(request);
 System.out.println(response.getBody());

>>bizContent Json示例：

"{" 
				+"\"target_card_no\":\"prexupdate0000003281\"," 
				+"\"target_card_no_type\":\"BIZ_CARD\"," 
				+"\"trade_type\":\"DEPOSIT\"," 
				+"\"trade_no\":\"201606270000000001\"," 
				+"\"trade_time\":\"2012-11-22 10:47:20\"," 
				+"\"trade_name\":\"预付卡充值100元\"," 
				+"\"trade_amount\":67.5," 
				+"\"act_pay_amount\":23.9," 
				+"\"shop_code\":\"201606270000001\"," 
				+"\"memo\":\"用户门店充值100\"," 
				+"\"use_benefit_list\":[{\"benefit_type\":\"COUPON\",\"amount\":\"10\",\"description\":\"消费1000元，赠送10元代金券\",\"count\":\"5\"}]," 
				+"\"gain_benefit_list\":[{\"benefit_type\":\"COUPON\",\"amount\":\"10\",\"description\":\"消费1000元，赠送10元代金券\",\"count\":\"5\"}]," 
				+"\"card_info\":{\"external_card_no\":\"EXT0009\",\"open_date\":\"2014-02-20 21:20:46\",\"valid_date\":\"2020-02-20 21:20:46\",\"level\":\"VIP1\",\"point\":\"88\",\"balance\":\"124.89\"}," 
				+"\"swipe_cert_type\":\"ALIPAY\"" 
				+"}"

 说明：

1.target_card_no为会员卡业务号，调用开卡接口成功后支付宝返回的biz_card_no参数的值；

2.external_card_no为商户会员卡号，如果在开卡的时候传了，这里就不需要保证和开卡接口中一致；

3.具体json字段说明，请查看会员卡消费记录同步

 

会员卡模板修改接口

>>接口列表：会员卡模板修改(alipay.marketing.card.template.modify)

>>SDK调用示例：

/**
 * 会员卡模板修改
@param appAuthToken如ISV代替商户调用接口，需将商户授权后获取的app_auth_token带上；如商户自己调用，则传null。
 * @param bizContent 因该接口业务参数复杂，请详见接口文档
 * @return
 * @throws AlipayApiException 请处理异常
 */
 AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");
 AlipayMarketingCardTemplateModifyRequest request = new AlipayMarketingCardTemplateModifyRequest();
 request.putOtherTextParam("app_auth_token", appAuthToken);
 request.setBizContent(bizContent);
 AlipayMarketingCardTemplateModifyResponse response=alipayClient.execute(request);
 System.out.println(response.getBody());

bizContent Json示例：

"{"
				+ "\"request_id\":\"201608051001121023100679\","
				+ "\"template_id\":\"20161009000000000014102000300197\","
				+ "\"biz_no_prefix\":\"prexupdate\","
				+ "\"write_off_type\":\"qrcode\","
				+ "\"template_style_info\":{"
				+ "\"card_show_name\":\"花呗会员卡测试\","
				+ "\"logo_id\":\"OKWBUiWCQ761MdRzP4PvUwAAACMAAQED\","
				+ "\"color\":\"rgb(55,112,179)\","
				+ "\"background_id\":\"OKWBUiWCQ761MdRzP4PvUwAAACMAAQED\","
				+ "\"bg_color\":\"rgb(55,112,179)\"},"
				+ "\"template_benefit_info\":[{\"title\":\"消费即折扣\","
				+ "\"benefit_desc\":[\"消费即折扣\",\"会员日7折扣\"],"
				+ "\"start_date\":\"2016-08-18 15:17:23\","
				+ "\"end_date\":\"2016-09-14 12:12:12\"}],"
				+ "\"column_info_list\":[{\"code\":\"BENEFIT_INFO\",\"more_info\":{\"title\":\"扩展信息\",\"url\":\"http://www.baidu.com\","
				+ "\"params\":\"{\\\"cardNo\\\":\\\"$CardNo$\\\"}\"},"
				+ "\"title\":\"专属权益修改\",\"operate_type\":\"openWeb\",\"value\":\"会员权益\"},"
				+"{\"code\":\"BALANCE\",\"title\":\"余额\",\"value\":\"\"},"
	            +"{\"code\":\"TELEPHOME\",\"title\":\"手机号码\",\"value\":\"15000784967\"},"
	            +"{\"code\":\"Point\",\"title\":\"积分\",\"value\":\"100\"}"
				+ "],"
				+ "\"field_rule_list\":[{\"field_name\":\"Balance\",\"rule_name\":\"ASSIGN_FROM_REQUEST\",\"rule_value\":\"Balance\"},"
				+ "{\"field_name\":\"Point\",\"rule_name\":\"CONST\",\"rule_value\":\"100\"}]}"

1.request_id为请求唯一标识，每次请求请保证唯一性；

2.logo_id和background_id通过支付宝图片资料上传接口（alipay.offline.material.image.upload）获取；

3.具体json字段说明，请查看会员卡模板修改

 

会员卡模板查询接口

>>接口列表：会员卡模板查询接口(alipay.marketing.card.template.query)

>>SDK调用示例：

/**
 * 会员卡模板查询
@param appAuthToken如ISV代替商户调用接口，需将商户授权后获取的app_auth_token带上；如商户自己调用，则传null。
 * @param bizContent 因该接口业务参数复杂，请详见接口文档
 * @return
 * @throws AlipayApiException 请处理异常
 */
 AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");
 AlipayMarketingCardTemplateQueryRequest request = new AlipayMarketingCardTemplateQueryRequest();
 request.putOtherTextParam("app_auth_token", appAuthToken);
 request.setBizContent("{"
	    		+"\"template_id\":\""+templateid+"\""
	    		+"}");
 AlipayMarketingCardTemplateQueryResponse response=alipayClient.execute(request);
 System.out.println(response.getBody());

 说明：

1.template_id为模板id，通过会员卡模板创建接口获取

2.具体json字段说明，请查看会员卡模板查询

 

接口调用流程：

支付宝会员卡包含以下接口

接口英文名 接口中文名 接口描述

alipay.marketing.card.template.create

会员卡模板创建

创建会员卡模板

alipay.marketing.card.template.modify

会员卡模板修改

修改会员卡模板

alipay.marketing.card.template.query

会员卡模板查询接口

查询会员卡模板

alipay.marketing.card.open

会员卡开卡

根据会员卡模板，向用户发行指定会员卡，会员卡接口需要用户授权

alipay.marketing.card.update

会员卡更新

更新会员卡信息

alipay.marketing.card.delete

会员卡删卡

删除会员卡，会同步删除支付宝端的卡信息以及钱包端的电子卡

alipay.marketing.card.query

会员卡查询

查询已存在会员卡信息

alipay.marketing.card.consume.sync

会员卡消费记录同步

同步用户的会员卡消费记录，同时更新卡信息

 

1.会员卡模板创建接口

2.会员卡模板修改接口

3.会员卡模板查询接口

4.会员卡开卡接口

5.会员卡删卡接口

6.会员卡消费记录同步接口

 

 

 

 

 

 

FAQ

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