基础功能
配置会员卡模板
创建卡模板
注意事项
请求示例
{
"request_id":"20160805100000023100679", //请求ID,商家自定义,创建不同的模板,需要保证request_id不同
"card_type":"OUT_MEMBER_CARD", //固定为OUT_MEMBER_CARD
"biz_no_prefix":"prex", // 支付宝业务卡号生成规则:biz_no_prefix(商家指定)卡号前缀 + biz_no_suffix位的(实时生成)卡号
"biz_no_suffix_len":"20",// 建议设置成20,生成卡号biz_card_no 长度为:前缀(biz_no_prefix)+20
"write_off_type":"qrcode", // 静态二维码,码值为最终发卡指定的external_card_no
"spi_app_id":"2014072300007148",
"template_style_info":{
"card_show_name":"商家会员卡",
"logo_id":"1T8Pp00AT7eo9NoAJkMR3AAAMA****", //由alipay.offline.material.image.upload上传
"background_id":"OKWBUiWCQ761MdRzP4PvUwAAACM****",
"bg_color":"rgb(55,112,179)"
},
"column_info_list":[
{
"code":"COLUMN_INFO_1",
"more_info":{
"url":"https://www.alipay.com"
},
"title":"栏位信息1",
"operate_type":"openWeb"
},
{
"code":"COLUMN_INFO_2",
"more_info":{
"url":"https://www.alipay.com"
},
"title":"栏位信息2",
"operate_type":"openWeb"
},
{
"code":"COLUMN_INFO_3",
"more_info":{
"url":"https://www.alipay.com"
},
"title":"栏位信息3",
"operate_type":"openWeb"
},
{
"code":"BALANCE",
"title":"余额"
},
{
"code":"Point",
"title":"积分"
}
],
"field_rule_list":[
{
"field_name":"Balance",
"rule_name":"ASSIGN_FROM_REQUEST",
"rule_value":"Balance"
},
{
"field_name":"Point",
"rule_name":"ASSIGN_FROM_REQUEST",
"rule_value":"Point"
}
],
"card_action_list":[
{
"code":"CARD_ACTION_1",
"text":"行动点1",
"url_type":"url",
"url":"https://www.alipay.com"
},
{
"code":"CARD_ACTION_2",
"text":"行动点2",
"url_type":"url",
"url":"https://www.alipay.com"
}
]
}
关键参数说明
传参注意事项
展示效果

上传卡模板图片文件
image_id
(图片资源 id)。注意事项
1.
2.
3.
请求示例
package com.java.sdk.demo;
import com.alipay.v3.ApiException;
import com.alipay.v3.ApiClient;
import com.alipay.v3.util.model.AlipayConfig;
import com.alipay.v3.Configuration;
import com.alipay.v3.api.AlipayOfflineMaterialImageApi;
import com.alipay.v3.model.*;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
public class AlipayOfflineMaterialImageApiUpload {
public static void main(String[] args) throws ApiException {
ApiClient defaultClient = Configuration.getDefaultApiClient();
// 初始化alipay参数(全局设置一次)
AlipayConfig alipayConfig = new AlipayConfig();
alipayConfig.setServerUrl("https://openapi.alipay.com");
alipayConfig.setAppId("<-- 请填写您的AppId,例如:2019091767145019 -->");
alipayConfig.setPrivateKey("<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->");
alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->");
defaultClient.setAlipayConfig(alipayConfig);
AlipayOfflineMaterialImageApi api = new AlipayOfflineMaterialImageApi();
AlipayOfflineMaterialImageUploadModel data = new AlipayOfflineMaterialImageUploadModel();
data.setImageName("海底捞");
data.setImagePid("2088021822217233");
data.setImageType("jpg或mp4");
File imageContent = new File("文件路径");
try {
AlipayOfflineMaterialImageUploadResponseModel response = api.upload(data, imageContent);
} catch (ApiException e) {
AlipayOfflineMaterialImageUploadDefaultResponse errorObject = (AlipayOfflineMaterialImageUploadDefaultResponse) e.getErrorObject();
System.out.println("调用失败:" + errorObject);
}
}
}
响应示例
{
"image_url":"http://dl.django.t.taobao.com/rest/1.0/image?fileIds=V9rfg69SSimLZg5wDA3yEgAAACMA...",
"image_id":"hOTQ1lT1TtOjcxGflvnUXgAAACMAAQED"
}
配置卡模板开卡表单
template_id
(会员卡模板 ID)为对应的会员卡模板配置开卡页面表单,规定用户领取会员卡时需填写的个人信息,例如:姓名、性别、手机号等。请求示例
package com.java.sdk.demo;
import com.alipay.v3.ApiException;
import com.alipay.v3.ApiClient;
import com.alipay.v3.util.model.AlipayConfig;
import com.alipay.v3.Configuration;
import com.alipay.v3.api.AlipayMarketingCardFormtemplateApi;
import com.alipay.v3.model.*;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
public class AlipayMarketingCardFormtemplateApiSet {
public static void main(String[] args) throws ApiException {
ApiClient defaultClient = Configuration.getDefaultApiClient();
// 初始化alipay参数(全局设置一次)
AlipayConfig alipayConfig = new AlipayConfig();
alipayConfig.setServerUrl("https://openapi.alipay.com");
alipayConfig.setAppId("<-- 请填写您的AppId,例如:2019091767145019 -->");
alipayConfig.setPrivateKey("<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->");
alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->");
defaultClient.setAlipayConfig(alipayConfig);
AlipayMarketingCardFormtemplateApi api = new AlipayMarketingCardFormtemplateApi();
AlipayMarketingCardFormtemplateSetModel data = new AlipayMarketingCardFormtemplateSetModel();
OpenFormFieldDO fields = new OpenFormFieldDO();
fields.setOptional("{\n\n \"common_fields\": [\n\n \"OPEN_FORM_FIELD_GENDER\"\n\n ]\n\n }");
fields.setRequired("{\n\n \"common_fields\": [\n\n \"OPEN_FORM_FIELD_MOBILE\"\n\n ]\n\n }");
data.setFields(fields);
data.setTemplateId("20170228000000000210102000300974");
try {
Object response = api.set(data);
} catch (ApiException e) {
AlipayMarketingCardFormtemplateSetDefaultResponse errorObject = (AlipayMarketingCardFormtemplateSetDefaultResponse) e.getErrorObject();
System.out.println("调用失败:" + errorObject);
}
}
}
前端集成开卡组件

订购开卡插件
前端引入插件
第一步:声明插件
{
"plugins": {
"alipassToolKit": { // 请自定义插件名称
"version": "*", // 目前只支持设置 * 拉取当前上架最新版本
"provider": "2021001107697072" // 固定值,插件 ID
}
}
}
第二步:使用插件
.axml 示例代码
<!-- .axml -->
<view class="action">
<button type="ghost" class="btn-integration" onTap="onOpenCard">领取会员卡</button>
</view>
.js 示例代码
// .js
onOpenCard(){
var plugin = requirePlugin("alipassToolKit") // 引用名称需与 app.json 中定义名称相同
let params = {
cardParams:{//开卡入参,
templateId:'xxx', // 开卡的卡模板ID
templateAppId:'xxx', // 卡模板ID 所关联的 AppId
outString:'xxx',//商家自定义透传信息
pageType:'half',//默认是 half
},
callback: function (res) {
console.log('======', res)
if (res.success === true) {
console.log('----- success')
}
}
}
plugin.openCard(params);// 接口参数说明如下
},
plugin.openCard(params) 接口说明
参数 | 类型 | 是否必填 | 描述 |
---|---|---|---|
cardParams | String | 是 | 开卡入参。 |
L cardParams.templateId | String | 是 | 开卡的卡模板 ID。 |
L cardParams.templateAppId | String | 是 | 卡模板 ID 所关联的 APPID。 |
L cardParams.outString | String | 否 | 商家自定义透传信息。注意:禁止将该字段作为开卡流程的必要字段,否则会导致会员推广场景下的入会失败。 |
L cardParams.pageType | String | 否 | 开卡组件样式。默认 half (半屏开卡)。 |
L cardParams.joinBenefitType | String | 否 | 扩展功能 入会有礼 专用。为入会有礼对应的权益类型,固定传入:VOUCHER_MRCH。 |
L cardParams.joinBenefitId | String | 否 | 扩展功能 入会有礼 专用。为入会有礼对应的活动 id(商家平台配置所得)。 |
callback | Any | 是 | 开卡完成回调 function。 |
参数 | 类型 | 描述 |
---|---|---|
success | Boolean | 开卡结果。 |
resultCode | String | 结果码。10000:用户领卡成功。10001:用户主动退出。10002:网络链接错误。 |
resultMsg | String | 结果信息描述。 |
extInfo | Object | 扩展信息。 |
服务端集成开卡接口

实现获取会员卡 SPI 接口
支付宝请求业务字段
参数 | 类型 | 是否必填 | 最大长度 | 示例值 | 描述 |
---|---|---|---|---|---|
user_id | String | 否 | 16 | 2088902351536970 | 蚂蚁统一会员 ID。 |
template_id | String | 是 | 32 | 20200312000000000414103000300846 | 会员卡模板 id,即 alipay.marketing.card.template.create(会员卡模板创建)返回的 template_id。 |
out_serial_no | String | 是 | 32 | 1621923366000 | out_serial_no:外部流水号,标识一次用户的开卡动作,用户每次打开开卡组件,都会生成一个全局唯一的 id。 |
biz_card_no | String | 是 | 32 | 000001 | 支付宝预先生成的 会员卡业务卡号,开卡结果需要回填。商家需要保存该业务卡号,后续可通过该卡号,更新、查询会员卡。 |
user_info | String | 是 | 10240 | [{"OPEN_FORM_FIELD_GENDER":"男"},{"OPEN_FORM_FIELD_MOBILE":"13888888888"},{"OPEN_FORM_FIELD_NAME":"李四"}] | 用户开卡时提交的表单信息,JSON 数组格式。 通用表单字段名称如下示例:OPEN_FORM_FIELD_MOBILE:手机号。OPEN_FORM_FIELD_GENDER:性别。OPEN_FORM_FIELD_NAME:姓名。OPEN_FORM_FIELD_BIRTHDAY:生日。OPEN_FORM_FIELD_IDCARD:身份证。OPEN_FORM_FIELD_EMAIL:邮箱。OPEN_FORM_FIELD_ADDRESS:地址。详细字段名称列表见会员卡开卡表单模板配置接口:alipay.marketing.card.formtemplate.set 注意:OPEN_FORM_FIELD_CERT_TYPE(证件类型字段)返回结果取值如下:0:身份证。1:护照。2:港澳居民通行证。3:台湾居民通行证。 |
out_string | String | 否 | 1024 | test | 该值为商家拉起开卡组件的传递的 out_string 值。通常可用于区分不同业务场景。注意:禁止将该字段作为开卡流程的必要字段,否则会导致会员推广场景下的入会失败。 |
约定返回业务字段
card_info 模型详解
参数 | 类型 | 是否必填 | 最大长度 | 示例值 | 描述 |
---|---|---|---|---|---|
biz_card_no | String | 是 | 32 | 000001 | 支付宝预先生成的 会员卡业务卡号,回填。 |
external_card_no | String | 是 | 64 | EXT0001 | 商户外部会员卡卡号,卡号需要满足以下要求:商家针对每一个 user_id,卡号需要保证唯一。支付宝幂等规则为:商家+external_card_no。 |
open_date | String | 是 | 32 | 2000-01-01 21:20:46 | 会员卡开卡时间,格式为 yyyy-MM-dd HH:mm:ss。 |
valid_date | String | 是 | 32 | 2100-02-20 21:20:46 | 会员卡有效期,格式为 yyyy-MM-dd HH:mm:ss。若期望会员卡长期有效,可适当把有效期设置长远一些 |
level | String | 否 | 64 | VIP1 | 会员卡等级。由商户自定义,并可以在卡模板创建时,定义等级信息。 |
point | String | 否 | 64 | 88 | 会员卡积分,小数点后最多两位。 |
balance | String | 否 | 64 | 124.89 | 余额,单位:元,小数点后最多两位。 |
template_id | String | 是 | 32 | 20170308000000000058101000300045 | 会员卡模板 id,即 alipay.marketing.card.template.create(会员卡模板创建接口)返回的 template_id。 |
open_card_ext_info 模型详解
参数 | 类型 | 是否必填 | 最大长度 | 示例值 | 描述 |
---|---|---|---|---|---|
is_new_member | Boolean | 否 | 10 | true | 是否新会员。商家可通过该字段,告诉支付宝是否是商家客户管理系统(CRM)中的新会员。 |
activity_id | String | 否 | 128 | 12345 | IoT 场景专用,普通场景无需关注。 |
实现示例
监听开卡结果消息
第一步:订阅消息
第二步:接收消息
监听消息示例代码
String appId = "your appid" ;
// 目标支付宝服务端地址,生产环境(线上环境)为 openchannel.alipay.com
String serverHost = "openchannel.alipay.com" ;
// 数据签名方式,请与应用设置的默认签名方式保持一致
String signType = "RSA2" ;
// 应用私钥
String appPrivateKey = "your app private key" ;
// 支付宝公钥
String alipayPublicKey = "alipay public key" ;
// 获取client对象,一个appId对应一个实例
final AlipayMsgClient alipayMsgClient = AlipayMsgClient.getInstance(appId);
alipayMsgClient.setConnector(serverHost);
alipayMsgClient.setSecurityConfig(signType, appPrivateKey, alipayPublicKey);
alipayMsgClient.setMessageHandler(new MsgHandler() {
/**
* 客户端接收到消息后回调此方法
* @param msgApi 接收到的消息的消息api名
* @param msgId 接收到的消息的消息id
* @param bizContent 接收到的消息的内容,json格式
*/
@Override
public void onMessage(String msgApi, String msgId, String bizContent) {
System.out.println( "receive message. msgApi:" + msgApi + " msgId:" + msgId + " bizContent:" + bizContent);
//商家处理收到开卡结果后置逻辑
}
});
alipayMsgClient.connect();
消息示例
ISV_GATEWAY_URL?charset=GBK&biz_content=
{
"user_id":"2088902351536970",
"template_id":"20200312000000000414103000300846",
"biz_card_no":"000001",
"external_card_no":"EXT0001",
"success":"true",
"error_code":"ILLEGAL_ARGUMENT",
"error_msg":"参数非法"
}
&msg_method=alipay.user.opencard.result.notify&utc_timestamp=1516797622752&version=1.1&sign_type=RSA2¬ify_id=d275fec564e62af6bedbcee73f3f05fi5x&app_id=2013121700999429&sign=I+Y/lvqYUEEc10EPdpntRhFIQ==
参数 | 类型 | 是否必填 | 最大长度 | 示例值 | 描述 |
---|---|---|---|---|---|
user_id | String | 必选 | 16 | 2088902351536970 | 支付宝用户号 userid。 |
template_id | String | 必选 | 32 | 20200312000000000414103000300846 | 会员卡模板 ID(卡模板创建接口返回的模板 ID) |
biz_card_no | String | 必选 | 32 | 000001 | 支付宝业务卡号。 |
external_card_no | String | 必选 | 64 | EXT0001 | 商家外部会员卡卡号。 |
success | String | 必选 | 10 | true | 开卡结果(true/false)。 |
error_code | String | 特殊可选 | 32 | ILLEGAL_ARGUMENT | 错误码,列表如下。 |
error_msg | String | 特殊可选 | 128 | 参数非法 | 错误描述。 |
error_code 类型 | 错误描述 |
---|---|
isv.invalid-arguments | 参数有误,需要结合 error_msg 定位具体原因。 |
isp.system-error | 系统繁忙。 |
isv.template-not-exist | 模板不存在。 |
isv.open-card-concurrently | 同一外部卡号并发开卡错误。 |
isv.card-has-opened | 开卡失败,用户已有此外部卡号的卡实例。 |
第二步:验签
第三步:反馈消息接收结果
success
表示消息获取成功,支付宝就会停止发送异步通知。如果返回 fail
或其它值,表示消息获取失败,支付宝会根据 投递重试策略 重新发送消息到应用网关地址。success
,验签失败返回 fail
,重新接收异步进行处理。响应值 | 描述 | 是否重试 |
---|---|---|
fail | 消息获取失败 | 重试 |
success | 消息获取成功 | 不重试 |