淘宝开放平台

登录
文档中心 > API类目 > 营销API

营销API

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 是 256 商户请求参数的签名串，详见签名 详见示例
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的位数		 10
write_off_type String 必须 32 卡包详情页面中展现出的卡码（可用于扫码核销）

(1) 静态码
qrcode: 二维码，扫码得商户开卡传入的external_card_no
barcode: 条形码，扫码得商户开卡传入的external_card_no
text: 当前不再推荐使用，text的展示效果目前等价于barcode+qrcode，同时出现条形码和二维码

(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
  • 设置是否在卡面展示文案信息，默认不展示；
    文案信息分行展示，最多展示3行文案，每行文案分为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
  • 品牌商名称
  • 可乐
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
  • 二级页面标题
  • 会员专享权益
  • └ url
  • String
  • 可选
  • 256
  • 超链接(选择openweb的时候必须填写url参数内容)
  • http://www.baidu.com
  • └ params
  • String
  • 可选
  • 1024
  • 扩展参数，需要URL地址回带的值，JSON格式(openweb时填)
  • {}
  • └ descs
  • String []
  • 可选
  • 1000
  • 选择opennative的时候必须填写descs的内容
  • 会员生日7折
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
  • String
  • 必填
  • 1024
  • 行动点跳转链接
  • https://merchant.ali.com/ee/clock_in.do
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
  • 配置，预留字段，暂时不用
  • ""
service_label_list String [] 可选 1024 服务Code
HUABEI_FUWU：花呗服务（只有需要花呗服务时，才需要加入该标识）		 HUABEI_FUWU
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

公共响应参数

参数 类型 是否必填 最大长度 描述 示例值
code String 是 - 网关返回码,详见文档 40004
msg String 是 - 网关返回码描述,详见文档 Business Failed
sub_code String 否 - 业务返回码,详见文档 ACQ.TRADE_HAS_SUCCESS
sub_msg String 否 - 业务返回码描述,详见文档 交易已被支付
sign String 是 - 签名,详见文档 DZXh8eeTuAHoYE3w1J+POiPhfDxOYBfUNn1lkeT/V7P4zJdyojWEa6IZs6Hz0yDW5Cp/viufUb5I0/V5WENS3OYR8zRedqo6D+fUTdLHdc+EFyCkiQhBxIzgngPdPdfp1PIS7BdhhzrsZHbRqb7o4k3Dxc+AAnFauu4V6Zdwczo=

响应参数

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

请求示例

  • JAVA
  • .NET
  • PHP
  • HTTP请求源码
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\":\"可乐\"" +
"}," +
"\"template_benefit_info\":[{" +
"\"title\":\"消费即折扣\"," +
"\"benefit_desc\":[" +
"\"消费即折扣\"" +
"]," +
"\"start_date\":\"2016-07-1815:17:23\"," +
"\"end_date\":\"2016-07-3412: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折\"" +
"]" +
"}" +
"}]," +
"\"field_rule_list\":[{" +
"\"field_name\":\"Balance\"," +
"\"rule_name\":\"ASSIGN_FROM_REQUEST\"," +
"\"rule_value\":\"Balance\"" +
"}]," +
"\"card_action_list\":[{" +
"\"code\":\"TO_CLOCK_IN\"," +
"\"text\":\"打卡\"," +
"\"url\":\"https://merchant.ali.com/ee/clock_in.do\"" +
"}]," +
"\"open_card_conf\":{" +
"\"open_card_source_type\":\"ISV\"," +
"\"source_app_id\":\"201609191111111\"," +
"\"open_card_url\":\"https://www.alipay.com\"," +
"\"conf\":\"\\\"\\\"\"" +
"}," +
"\"service_label_list\":[" +
"\"HUABEI_FUWU\"" +
"]," +
"\"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("调用失败");
}

响应示例

  • JSON示例
{
	"sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE",
	"alipay_marketing_card_template_create_response":{
		"msg":"Success",
		"code":"10000",
		"template_id":"201607180000001"
	}
}

异常示例

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

业务错误码

错误码 错误描述 解决方案
INVALID_PARAMETER 参数有误。 查看message定位问题
SYSTEM_ERROR 系统繁忙 系统错误，查看message获取实际错误原因
TEMPLATE_NOT_EXIT 模板不存在 查看模板
NO_CARD_TYPE 没有卡类型 卡类型判断

公共错误码

公共错误码

触发通知类型

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

触发通知字段

参数 类型 是否必填 最大长度 描述 示例值
card_type String 选填 - 卡类型 OUT_MEMBER_CARD：外部卡
external_card_no String 选填 - 外部卡号
user_id String 选填 - 用户id
card_status String 选填 - 卡状态 NORMAL:正常 UNBUND:解绑 DISCARD:销卡
template_id String 选填 - 模板id
request_id String 选填 - 请求流水
process_time String 选填 - 请求处理时间 yyyy-MM-dd HH:mm:ss
event_code String 必填 32 TREATE_PAY：付款
CARD_STATUS_CHANGE：卡变更
RETURN_CARD删卡 		TREATE_PAY
biz_card_no String [] 选填 32 业务卡号 1000000089
trade_no String 选填 32 支付宝交易号 20170425000000000001
out_trade_no String 选填 32 外部交易号 201704250000000000001
total_amount String 选填 32 交易总金额，以元为单位 23.20
buyer_pay_amount String 选填 32 用户付款金额，以元为单位 23.23
gmt_payment String 选填 32 付款时间，格式yyyy-MM-dd HH:mm:ss 2017-04-25 14:51:22
merchant_uid String [] 必填 32 商户收款账户 2088202855218634

触发通知示例

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

异步通知验签方式

异步通知验签方式
有用(3)
我要提问
返回
顶部