alipay.marketing.card.template.create(会员卡模板创建) 在线调试(沙箱环境)

会员卡模板创建

公共参数

请求地址

环境HTTPS请求地址
正式环境 https://openapi.alipay.com/gateway.do

公共请求参数

参数 类型 是否必填最大长度描述示例值
app_id String 32 支付宝分配给开发者的应用ID 2014072300007148
method String 128 接口名称 alipay.marketing.card.template.create
format String 40 仅支持JSON JSON
charset String 10 请求使用的编码格式,如utf-8,gbk,gb2312等 utf-8
sign_type String 10 商户生成签名字符串所使用的签名算法类型,目前支持RSA2和RSA,推荐使用RSA2 RSA2
sign String 344 商户请求参数的签名串,详见签名 详见示例
timestamp String 19 发送请求的时间,格式"yyyy-MM-dd HH:mm:ss" 2014-07-24 03:07:50
version String 3 调用的接口版本,固定为:1.0 1.0
notify_url String 256 支付宝服务器主动通知商户服务器里指定的页面http/https路径。 http://api.test.alipay.net/atinterface/receive_notify.htm
app_auth_token String 40 详见应用授权概述
biz_content String 请求参数的集合,最大长度不限,除公共参数外所有请求参数都必须放在这个参数中传递,具体参照各产品快速接入文档

请求参数

参数 类型 是否必填 最大长度 描述 示例值
request_id String 必选 32 请求ID,由开发者生成并保证唯一性 2016072600000000000000001
card_type String 必选 32 卡类型为固定枚举类型,可选类型如下:
OUT_MEMBER_CARD:外部权益卡
OUT_MEMBER_CARD
biz_no_prefix String 可选 10 业务卡号前缀,由商户指定
支付宝业务卡号生成规则:biz_no_prefix(商户指定)卡号前缀 + biz_no_suffix(实时生成)卡号后缀
prex
biz_no_suffix_len String 必选 2 业务卡号后缀的长度,取值范围为[8,32]
支付宝业务卡号生成规则:biz_no_prefix(商户指定)卡号前缀 + biz_no_suffix(实时生成)卡号后缀
由于业务卡号最长不超过32位,所以biz_no_suffix_len <= 32 - biz_no_prefix的位数。注:biz_no_suffix_len一旦指定,在模板修改时不支持修改。
10
write_off_type String 必选 32 卡包详情页面中展现出的卡码(可用于扫码核销)

(1) 静态码
qrcode: 二维码,扫码得商户开卡传入的external_card_no
barcode: 条形码,扫码得商户开卡传入的external_card_no

(2) 动态码-支付宝生成码值(动态码会在2分钟左右后过期)
dqrcode: 动态二维码,扫码得到的码值可配合会员卡查询接口使用
dbarcode: 动态条形码,扫码得到的码值可配合会员卡查询接口使用

(3) 动态码-商家自主生成码值(码值、时效性都由商户控制)
mdqrcode: 商户动态二维码,扫码得商户自主传入的码值
mdbarcode: 商户动态条码,扫码得商户自主传入的码值
如需使用商户动态码,请联系支付宝技术支持获取相关文档。
qrcode
template_style_info TemplateStyleInfoDTO 必选 模板样式信息
card_show_name String 必填 10 钱包端显示名称(字符串长度) 花呗联名卡
logo_id String 必填 1000 logo的图片ID,通过接口(alipay.offline.material.image.upload)上传图片

图片说明:1M以内,格式bmp、png、jpeg、jpg、gif;
尺寸不小于500*500px的正方形;
请优先使用商家LOGO;
1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC
color String 可选 64 注意:此字段已废弃。
卡片颜色
rgb(55,112,179)
background_id String 必填 1000 背景图片Id,通过接口(alipay.offline.material.image.upload)上传图片

图片说明:2M以内,格式:bmp、png、jpeg、jpg、gif;
尺寸不小于1020*643px;
图片不得有圆角,不得拉伸变形
1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC
bg_color String 必填 32 字体颜色(非背景色),只影响卡详情中部信息区域字体颜色 rgb(55,112,179)
front_text_list_enable Boolean 可选 5 设置是否在卡面展示文案信息,默认不展示;
文案信息分行展示,最多展示4行文案,每行文案分为label和value两部分;
文案实际内容随创建卡/更新卡时传入;
详见会员卡产品说明文档。
false
front_image_enable Boolean 可选 5 设置是否在卡面展示(个人头像)图片信息,默认不展示;
当前仅用于身份验证信息类型的个人头像图片;
图片id随创建卡/更新卡时传入;
详见会员卡产品文档。
false
feature_descriptions String[] 可选 4000 特色信息,用于领卡预览 使用花呗卡可享受免费分期
slogan String 可选 100 标语 会员权益享不停
slogan_img_id String 可选 100 标语图片, 通过接口(alipay.offline.material.image.upload)上传图片 1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC
brand_name String 可选 100 品牌商名称 可乐
banner_img_id String 可选 1000 banner图片地址。 通过接口(alipay.offline.material.image.upload)上传图片。 1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC
banner_url String 可选 256 banner跳转地址。 http://www.baidu.com
column_info_layout String 可选 10 栏位信息布局。目前只支持list(列表)或grid(宫格)形式。如果为空则默认为list。 list
template_benefit_info TemplateBenefitInfoDTO[] 可选 权益信息,
1、在卡包的卡详情页面会自动添加“会员权益”栏位,展现此字段配置的会员卡权益信息,
2、如果添加门店渠道,则可在门店页展现会员卡的权益
title String 必填 16 权益描述 消费即折扣
benefit_desc String[] 必填 1000 权益描述信息 消费即折扣
start_date Date 必填 64 开始时间 2016-07-18 15:17:23
end_date Date 必填 64 权益结束时间 2016-07-34 12:12:12
column_info_list TemplateColumnInfoDTO[] 必选 栏位信息
code String 必填 32 标准栏位:行为由支付宝统一定,同时已经分配标准Code
BALANCE:会员卡余额
POINT:积分
LEVEL:等级
TELEPHONE:联系方式
自定义栏位:行为由商户定义,自定义Code码(只要无重复)
BENEFIT_INFO
operate_type String 可选 32 1、openNative:打开二级页面,展现 more中descs
2、openWeb:打开URL
3、staticinfo:静态信息
注意:
不填则默认staticinfo;
标准code尽量使用staticinfo,例如TELEPHONE商家电话栏位就只支持staticinfo;
openWeb
title String 必填 16 栏目的标题 会员专享
value String 可选 16 卡包详情页面,卡栏位右边展现的值

TELEPHONE栏位的商家联系电话号码由此value字段传入
80
more_info MoreInfoDTO 可选 2048 扩展信息
title String 必填 16 二级页面标题,只有当operate_type为openNative时有效。 会员专享权益
url String 可选 256 超链接(选择openweb的时候必须填写url参数内容) http://www.baidu.com
params String 可选 1024 扩展参数,需要URL地址回带的值,JSON格式(openweb时填) {}
descs String[] 可选 1000 选择opennative的时候必须填写descs的内容 会员生日7折
icon_id String 可选 1000 若template_style_info.column_info_layout
的值为grid,此项为宫格项的展示icon。通过接口(alipay.offline.material.image.upload)上传图片。
1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC
tag String 可选 3 若template_style_info.column_info_layout
的值为grid,此项为宫格项标签。可空。
热门
group_title String 可选 6 若template_style_info.column_info_layout
的值为grid,此项为宫格项所属分组标题。可空。如果需要展示该项,还需支付宝内部进行特殊配置。
校园助手
field_rule_list TemplateFieldRuleDTO[] 必选 字段规则列表,会员卡开卡过程中,会员卡信息的生成规则,
例如:卡有效期为开卡后两年内有效,则设置为:DATE_IN_FUTURE
field_name String 必填 64 字段名称,现在支持如下几个Key(暂不支持自定义)
Balance:金额
Point:整数
Level:任意字符串
OpenDate:开卡日期
ValidDate:过期日期
Balance
rule_name String 必填 64 规则名
1、ASSIGN_FROM_REQUEST: 以rule_value为key值,表示该栏位的值从会员卡开卡接口中获取,会员卡开卡接口的card_info中获取对应参数值
2、DATE_IN_FUTURE: 生成一个未来的日期(格式YYYY-MM-DD),当选择DATE_IN_FUTURE的时候,field_name 必须是OpenDate或ValidDate, 值为(10m或10d 分别表示10个月或10天)
3、CONST: 常量,会员卡开卡接口进行开卡的时候使用模板创建时候设置的值,即取rule_value的值
ASSIGN_FROM_REQUEST
rule_value String 必填 512 根据rule_name,采取相应取值策略
CONST:直接取rule_value作为卡属性值
DATE_IN_FUTURE:10m或10d 分别表示10个月或10天
ASSIGN_FROM_REQUEST:在开卡Reuqest请求中按rule_value取值,现在和field_name对应的为(OpenDate、ValidDate、Level、Point、Balance)
Balance
card_action_list TemplateActionInfoDTO[] 可选 卡行动点配置;
行动点,即用户可点击跳转的区块,类似按钮控件的交互;
单张卡最多定制4个行动点。如果各项的配置内容完全一样,展示时会进行去重。
code String 必填 32 行动点业务CODE,商户自定义 TO_CLOCK_IN
text String 必填 6 行动点展示文案 打卡
url_type String 可选 20 跳转链接类型,当前支持url和miniAppUrl,不填则默认为url类型:
url:对应填写url参数,支持http(s)和支付宝schema地址等;
miniAppUrl: 对应填写mini_app_url参数,跳转至指定的支付宝小程序页面
url
url String 可选 1024 行动点跳转链接,当url_type取"url"或不填时必填 https://merchant.ali.com/ee/clock_in.do
mini_app_url TemplateActionMiniAppUrlDTO 可选 999 小程序页面跳转链接,当url_type取"miniAppUrl"时必填
mini_app_id String 必填 20 小程序appId 2018xxxxxxx
mini_page_param String 可选 20 指定小程序页面,不填则默认跳转至对应小程序首页 xxxxxxxx
mini_query_param String 可选 50 query参数,商户自定义传参,填入值将以"query"为参数名提交至指定小程序页面 abcxxxxxx
display_on_list String 可选 5 行动点按钮是否在列表页展示,true 或 false,不填则默认false;
列表页可以配置展示最多2项小程序跳转行动点。
false
open_card_conf TemplateOpenCardConfDTO 可选 会员卡用户领卡配置,在门店等渠道露出领卡入口时,需要部署的商户领卡H5页面地址
open_card_source_type String 必填 20 ISV:外部系统
MER:直连商户
ISV
source_app_id String 必填 32 渠道APPID,提供领卡页面的服务提供方 201609191111111
open_card_url String 必填 256 开卡连接,必须http、https开头 https://www.alipay.com
conf String 可选 4000 配置,预留字段,暂时不用 ""
card_rights TemplateRightsContentDTO[] 可选 3 领卡权益信息
title String 必填 10 权益内容标题 积分兑换好礼
detail String 可选 20 权益内容详情 积分随时查,积分换好礼
shop_ids String[] 可选 1024 会员卡上架门店id(支付宝门店id),既发放会员卡的商家门店id 2015122900077000000002409504
pub_channels PubChannelDTO[] 可选 卡模板投放渠道
pub_channel String 必填 32 1、SHOP_DETAIL:店铺详情页
2、PAYMENT_RESULT: 支付成功页(支付成功页暂不支持)
SHOP_DETAIL
ext_info String 可选 1024 扩展信息,无需配置 "key":"value"
card_level_conf TemplateCardLevelConfDTO[] 可选 卡级别配置
level String 必填 64 会员级别 该级别和开卡接口中的level要一致 VIP1
level_show_name String 必填 64 会员级别显示名称 黄金会员
level_icon String 必填 64 会员级别对应icon, 通过接口(alipay.offline.material.image.upload)上传图片 1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC
level_desc String 必填 4000 会员级别描述 黄金会员享受免费停车
mdcode_notify_conf TemplateMdcodeNotifyConfDTO 可选 商户动态码通知参数配置:
当write_off_type指定为商户动态码mdbarcode或mdqrcode时必填;
在此字段配置用户打开会员卡时支付宝通知商户生成动态码(发码)的通知参数,如接收通知地址等。
url String 必填 1024 商户接收发码通知的地址链接;
只支持https地址;
用户打开会员卡时,支付宝提交POST请求此url地址,通知商户发码。
https://www.ali123.com/ant/mdcode
ext_params String 可选 1024 扩展参数信息;
格式为key-value键值对;
支付宝POST请求指定url时,除BizCardNo等固定参数外,将带上ext_params中配置的所有key-value参数。
{"param1":"value1","param2":"value2"}
card_spec_tag String 可选 20 卡特定标签,只供特定业务使用,通常接入无需关注 NONE

响应参数

参数 类型 是否必填 最大长度 描述 示例值
template_id String 必填 32 支付宝卡模板ID 201607180000001

请求示例

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
AlipayMarketingCardTemplateCreateRequest request = new AlipayMarketingCardTemplateCreateRequest();
request.setBizContent("{" +
"\"request_id\":\"2016072600000000000000001\"," +
"\"card_type\":\"OUT_MEMBER_CARD\"," +
"\"biz_no_prefix\":\"prex\"," +
"\"biz_no_suffix_len\":\"10\"," +
"\"write_off_type\":\"qrcode\"," +
"\"template_style_info\":{" +
"\"card_show_name\":\"花呗联名卡\"," +
"\"logo_id\":\"1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC\"," +
"\"color\":\"rgb(55,112,179)\"," +
"\"background_id\":\"1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC\"," +
"\"bg_color\":\"rgb(55,112,179)\"," +
"\"front_text_list_enable\":false," +
"\"front_image_enable\":false," +
"        \"feature_descriptions\":[" +
"          \"使用花呗卡可享受免费分期\"" +
"        ]," +
"\"slogan\":\"会员权益享不停\"," +
"\"slogan_img_id\":\"1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC\"," +
"\"brand_name\":\"可乐\"," +
"\"banner_img_id\":\"1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC\"," +
"\"banner_url\":\"http://www.baidu.com\"," +
"\"column_info_layout\":\"list\"" +
"    }," +
"      \"template_benefit_info\":[{" +
"        \"title\":\"消费即折扣\"," +
"          \"benefit_desc\":[" +
"            \"消费即折扣\"" +
"          ]," +
"\"start_date\":\"2016-07-18 15:17:23\"," +
"\"end_date\":\"2016-07-34 12:12:12\"" +
"        }]," +
"      \"column_info_list\":[{" +
"        \"code\":\"BENEFIT_INFO\"," +
"\"operate_type\":\"openWeb\"," +
"\"title\":\"会员专享\"," +
"\"value\":\"80\"," +
"\"more_info\":{" +
"\"title\":\"会员专享权益\"," +
"\"url\":\"http://www.baidu.com\"," +
"\"params\":\"{}\"," +
"            \"descs\":[" +
"              \"会员生日7折\"" +
"            ]" +
"        }," +
"\"icon_id\":\"1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC\"," +
"\"tag\":\"热门\"," +
"\"group_title\":\"校园助手\"" +
"        }]," +
"      \"field_rule_list\":[{" +
"        \"field_name\":\"Balance\"," +
"\"rule_name\":\"ASSIGN_FROM_REQUEST\"," +
"\"rule_value\":\"Balance\"" +
"        }]," +
"      \"card_action_list\":[{" +
"        \"code\":\"TO_CLOCK_IN\"," +
"\"text\":\"打卡\"," +
"\"url_type\":\"url\"," +
"\"url\":\"https://merchant.ali.com/ee/clock_in.do\"," +
"\"mini_app_url\":{" +
"\"mini_app_id\":\"2018xxxxxxx\"," +
"\"mini_page_param\":\"xxxxxxxx\"," +
"\"mini_query_param\":\"abcxxxxxx\"," +
"\"display_on_list\":\"false\"" +
"        }" +
"        }]," +
"\"open_card_conf\":{" +
"\"open_card_source_type\":\"ISV\"," +
"\"source_app_id\":\"201609191111111\"," +
"\"open_card_url\":\"https://www.alipay.com\"," +
"\"conf\":\"\\\"\\\"\"," +
"        \"card_rights\":[{" +
"          \"title\":\"积分兑换好礼\"," +
"\"detail\":\"积分随时查,积分换好礼\"" +
"          }]" +
"    }," +
"      \"shop_ids\":[" +
"        \"2015122900077000000002409504\"" +
"      ]," +
"      \"pub_channels\":[{" +
"        \"pub_channel\":\"SHOP_DETAIL\"," +
"\"ext_info\":\"\\\"key\\\":\\\"value\\\"\"" +
"        }]," +
"      \"card_level_conf\":[{" +
"        \"level\":\"VIP1\"," +
"\"level_show_name\":\"黄金会员\"," +
"\"level_icon\":\"1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC\"," +
"\"level_desc\":\"黄金会员享受免费停车\"" +
"        }]," +
"\"mdcode_notify_conf\":{" +
"\"url\":\"https://www.ali123.com/ant/mdcode\"," +
"\"ext_params\":\"{\\\"param1\\\":\\\"value1\\\",\\\"param2\\\":\\\"value2\\\"}\"" +
"    }," +
"\"card_spec_tag\":\"NONE\"" +
"  }");
AlipayMarketingCardTemplateCreateResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

响应示例

{
    "alipay_marketing_card_template_create_response": {
        "code": "10000",
        "msg": "Success",
        "template_id": "201607180000001"
    },
    "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}

异常示例

{
    "alipay_marketing_card_template_create_response": {
        "code": "20000",
        "msg": "Service Currently Unavailable",
        "sub_code": "isp.unknow-error",
        "sub_msg": "系统繁忙"
    },
    "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}

业务错误码

公共错误码

错误码错误描述解决方案
INVALID_PARAMETER 参数有误。 查看message定位问题
SYSTEM_ERROR 系统繁忙 系统错误,查看message获取实际错误原因
TEMPLATE_NOT_EXIT 模板不存在 查看模板
NO_CARD_TYPE 没有卡类型 卡类型判断
TEMPLATE_OVER_LIMIT 模板数量超限 每个商家可创建的会员卡模板数量有限,请尽量复用已有模板。若为合理诉求需要增加,突破默认限制,请联系商务申请扩大数量配额

触发通知类型

通知类型描述默认开启
tradeStatus.TRADE_SUCCESS 处理成功 1

触发通知示例

https://www.merchant.com/receive_notify.htm?notify_type=trade_status_sync&notify_id=91722adff935e8cfa58b3aabf4dead6ibe&notify_time=2017-02-16 21:46:15&sign_type=RSA2&sign=WcO+t3D8Kg71dTlKwN7r9PzUOXeaBJwp8/FOuSxcuSkXsoVYxBpsAidprySCjHCjmaglNcjoKJQLJ28/Asl93joTW39FX6i07lXhnbPknezAlwmvPdnQuI01HZsZF9V1i6ggZjBiAd5lG8bZtTxZOJ87ub2i9GuJ3Nr/NUc9VeY=&card_type=null&external_card_no=null&user_id=null&card_status=null&template_id=null&request_id=null&process_time=null&event_code=TREATE_PAY&biz_card_no=1000000089&trade_no=20170425000000000001&out_trade_no=201704250000000000001&total_amount=23.20&buyer_pay_amount=23.23&gmt_payment=2017-04-25 14:51:22&merchant_uid=2088202855218634
onlineServer