通用场景
商户通过api接口，进行会员卡开卡。
公共请求参数
业务请求参数
out_serial_no｜外部商户流水号必选string[0,64]
【描述】外部商户流水号。由商户自定义，需保证商户系统中唯一。
【示例值】2016062700001
card_template_id｜会员卡模板id必选string[0,32]
【描述】支付宝分配的卡模板id（卡模板创建接口返回的模板id）
【示例值】201606270000001
card_user_info｜用户信息必选carduserinfo
【描述】发卡用户信息
user_uni_id_type｜用户唯一标识类型必选string[1,32]
【描述】用户唯一标识类型
【枚举值】
支付宝用户id: uid
【示例值】uid
以下参数 二选一 传入必选
user_uni_id｜用户唯一标识string[0,32]
【描述】用户唯一标识, 根据user_uni_id_type类型来定 （目前暂支持支付宝userid）
支付宝userid说明：支付宝用户号是以2088开头的16位纯数字组成
新商户建议使用open_id替代该字段。对于新商户，user_uni_id字段未来计划逐步回收，存量商户可继续使用。如使用open_id，请确认 应用-开发配置-openid配置管理 已启用。无该配置项，可查看openid配置申请。
【示例值】2088302463082075
open_id｜用户open_idstring[0,128]
【描述】用户open_id 详情可查看 openid简介
【示例值】074a1cctg1lelxke4xqc0zgndid0nxi95b5lsnpazwyoco5
card_ext_info｜外部卡信息必选merchantcard
【描述】外部卡信息(biz_card_no无需填写)
external_card_no｜商户外部会员卡卡号可选string[1,64]
【描述】用户在商户crm系统中的会员卡卡号，该参数必填。
【示例值】ext0001
open_date｜开卡时间可选date
【描述】会员卡开卡时间，格式为yyyy-mm-dd hh:mm:ss。会员卡更新时，该时间不支持修改。
匹配格式yyyy-mm-dd hh:mm:ss的date类型
【示例值】2014-02-20 21:20:46
valid_date｜有效期可选string[1,32]
【描述】会员卡有效期结束时间，格式为yyyy-mm-dd hh:mm:ss。会员卡更新时，该时间不支持修改。
【示例值】2020-02-20 21:20:46
level｜会员卡等级可选string[0,64]
【描述】会员卡等级（由商户自定义，并可以在卡模板创建时，定义等级信息）
【示例值】vip1
point｜会员卡积分可选string[0,64]
【描述】会员卡积分，积分必须为数字型（可为浮点型，带2位小数点）
【示例值】88
balance｜资金卡余额可选string[0,64]
【描述】资金卡余额，单位：元，精确到小数点后两位。
【示例值】124.89
mdcode_info｜商户动态码回传信息可选mdcodeinfodto
【描述】商户动态码回传信息：
只用于当write_off_type核销类型为mdbarcode或mdqrcode时，商户调用卡更新接口回传动态码。如需使用商户动态码，请联系支付宝凯发app官方网站的技术支持获取相关文档。
code_status｜动态码状态必选string[0,14]
【描述】本次回传动态码的状态：
success: 本次发码成功
fail_retry: 本次发码失败，且需要支付宝重试（重新通知商户发码）
fail_not_retry: 本次发码失败，且无需支付宝重试（无需重新通知商户发码）
【示例值】success
time_stamp｜时间戳必选number[1,9999999999]
【描述】商户回传动态码的时间戳 (单位秒)。
即商户调接口回传动态码时刻对应的long类型时间戳，用于区分不同的发码请求。
【示例值】1496996459
code_value｜动态码状态可选string[0,128]
【描述】动态码的码值：
code_status为success时必填；
基于此码值生成条形码或二维码用于扫码核销。
【示例值】1kfcdy0002
expire_time｜过期时间可选date
【描述】当前动态码的过期（失效）时间：
code_status为success时必填。
匹配格式yyyy-mm-dd hh:mm:ss的date类型
【示例值】2017-06-09 16:25:53
front_text_list｜卡面文案信息模型可选array
【描述】卡面文案列表，1项对应1行文案，最多只能传入4行文案；
单行文案展现分为左右两部分，左边对应label字段，右边对应value；
形如： 学院 新闻学院
label｜标签可选string[0,4]
【描述】文案标签
【示例值】专业
value｜展示文案可选string[0,32]
【描述】展示文案
【示例值】金融贸易
front_image_id｜卡面图片id可选string[0,1024]
【描述】卡面展示图片的图片id，通过接口（alipay.offline.material.image.upload）上传图片
这里预期展示的是个人照片；
图片说明：1m以内，格式bmp、png、jpeg、jpg、gif；
图片尺寸为230*295px，可等比放大；
【示例值】9fxnkgt0qfmqkal5v2bqxqaaacmaaqed
member_ext_info｜商户会员信息可选merchantmenber
【描述】商户会员信息
name｜姓名可选string[0,64]
【描述】姓名
【示例值】李洋
gende｜性别可选string[0,32]
【描述】性别
【枚举值】
男: male
女: female
【示例值】male
birth｜生日可选string[undefined,undefined]
【描述】生日 yyyy-mm-dd
【示例值】2016-06-27
cell｜手机号可选string[0,32]
【描述】手机号
【示例值】13000000000
open_card_channel｜领卡渠道可选string[0,32]
【描述】领卡渠道，用于记录外部商户端领卡来源的渠道信息，渠道值可自行定义（仅限数字、字母、下划线）
可直接标识领卡渠道，也可配合open_card_channel_id标识领卡渠道类型：
例如：
线下门店领取:20161534000000000008863（直接标识领卡渠道，门店shopid）
线下扫二维码领取:qr（标识领卡类型）;
凯发app官方网站的线下活动领取:20170522000000000003609（直接标识领卡渠道，商户活动id）
【示例值】20161534000000000008863
open_card_channel_id｜领卡来源的渠道id可选string[0,32]
【描述】领卡来源的渠道id，注意区别于open_card_channel领卡渠道；
一般使用场景：
open_card_channel用于区分渠道类型，例如取值为"shop"（门店），"activity"（活动）；
则open_card_channel_id可用于区分同渠道的不同实体，对应取各门店id或各活动的标识id等；
【示例值】123123123123
paid_outer_card_info｜付费外卡信息可选paidoutercardextrainfodto
【描述】付费外卡信息，只供特定业务使用，通常接入无需关注
action｜用户操作类型必选string[0,1024]
【描述】用户操作类型
【枚举值】
开通: open
升级: upgrade
降级: downgrade
【示例值】open
purchase_info｜外卡基本信息必选paidoutercardpurchaseinfodto
【描述】用户购买付费外卡基本信息
source｜用户操作来源必选string[0,20]
【描述】用户操作来源
【枚举值】
支付宝小程序: alipay_tiny_app
商家app: self_app
其他: other
【示例值】alipay_tiny_app
action_date｜操作时间必选string[19,19]
【描述】用户购买、升级、降级、续费的操作时间。格式为：yyyy-mm-dd hh:mm:ss
【示例值】2021-08-12 12:12:12
price｜用户购买金额可选string[0,12]
【描述】用户购买金额。当购买/升级/续费场景必填，单位元，精确到小数点后2位
【示例值】88.88
out_trade_no｜商户订单号可选string[0,64]
【描述】商户订单号。与创建订单api：alipay.trade.create保持一致
【示例值】20150320010101001
alipay_trade_no｜支付宝交易号可选string[0,64]
【描述】支付宝交易号，由api: alipay.trade.create 返回
【示例值】2015042321001004720200028594
cycle_info｜用户连续购买付费卡信息必选paidoutercardcycleinfodto
【描述】用户连续购买付费卡信息
open_status｜开通连续购买状态必选string[1,10]
【描述】开通连续购买状态。
【枚举值】
开通: open
关闭: close
【示例值】open
close_reason｜关闭连续购买原因可选string[1,20]
【描述】关闭连续购买原因。
【枚举值】
手动关闭: manual_close
过期关闭: expire_close
关闭: close
【示例值】manual_close
cycle_type｜用户开通连续购买类型可选string[1,20]
【描述】用户开通连续购买类型。
【枚举值】
年: year
季度: quarter
月: month
【示例值】year
alipay_deduct_scene｜支付宝代扣场景码可选string[0,64]
【描述】支付宝代扣场景码
【示例值】paid_outer_card
alipay_deduct_product_code｜支付宝代扣产品码可选string[0,64]
【描述】支付宝代扣产品码
【示例值】paid_outer_card
alipay_deduct_agreement｜支付宝用户签约协议号可选string[0,64]
【描述】支付宝用户签约协议号
【示例值】20151127000928469118
常见请求示例
默认示例
curl 'https://openapi.alipay.com/gateway.do?charset=utf-8&method=alipay.marketing.card.open&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=rsa2×tamp=${now}' \
-f 'biz_content={
"card_ext_info":{
"open_date":"2014-02-20 21:20:46",
"front_text_list":[
{
"label":"专业",
"value":"金融贸易"
}
],
"external_card_no":"ext0001",
"valid_date":"2020-02-20 21:20:46",
"balance":"124.89",
"level":"vip1",
"mdcode_info":{
"time_stamp":1496996459,
"code_value":"1kfcdy0002",
"expire_time":"2017-06-09 16:25:53",
"code_status":"success"
},
"front_image_id":"9fxnkgt0qfmqkal5v2bqxqaaacmaaqed",
"point":"88"
},
"open_card_channel":"20161534000000000008863",
"card_template_id":"201606270000001",
"card_user_info":{
"user_uni_id":"2088302463082075",
"user_uni_id_type":"uid",
"open_id":"074a1cctg1lelxke4xqc0zgndid0nxi95b5lsnpazwyoco5"
},
"out_serial_no":"2016062700001",
"paid_outer_card_info":{
"action":"open",
"cycle_info":{
"alipay_deduct_product_code":"paid_outer_card",
"alipay_deduct_agreement":"20151127000928469118",
"close_reason":"manual_close",
"cycle_type":"year",
"open_status":"open",
"alipay_deduct_scene":"paid_outer_card"
},
"purchase_info":{
"alipay_trade_no":"2015042321001004720200028594",
"out_trade_no":"20150320010101001",
"price":"88.88",
"action_date":"2021-08-12 12:12:12",
"source":"alipay_tiny_app"
}
},
"open_card_channel_id":"123123123123",
"member_ext_info":{
"name":"李洋",
"birth":"2016-06-27",
"gende":"male",
"cell":"13000000000"
}
}' 说明：本示例仅供参考。
公共响应参数
业务响应参数
card_info｜商户卡信息必选merchantcard
【描述】商户卡信息（包括支付宝分配的业务卡号）
biz_card_no｜支付宝业务卡号可选string(32)
【描述】支付宝业务卡号
说明：
1、开卡成功后返回该参数，需要保存留用；
2、开卡/更新/删卡/查询卡接口请求中不需要传该参数；
【示例值】000001
external_card_no｜商户外部会员卡卡号可选string(64)
【描述】用户在商户crm系统中的会员卡卡号，该参数必填。
【示例值】ext0001
open_date｜开卡时间可选date(32)
【描述】会员卡开卡时间，格式为yyyy-mm-dd hh:mm:ss。会员卡更新时，该时间不支持修改。
【示例值】2014-02-20 21:20:46
valid_date｜有效期可选string(32)
【描述】会员卡有效期结束时间，格式为yyyy-mm-dd hh:mm:ss。会员卡更新时，该时间不支持修改。
【示例值】2020-02-20 21:20:46
level｜会员卡等级可选string(64)
【描述】会员卡等级（由商户自定义，并可以在卡模板创建时，定义等级信息）
【示例值】vip1
point｜会员卡积分可选string(64)
【描述】会员卡积分，积分必须为数字型（可为浮点型，带2位小数点）
【示例值】88
balance｜资金卡余额可选string(64)
【描述】资金卡余额，单位：元，精确到小数点后两位。
【示例值】124.89
template_id｜会员卡模板id可选string(32)
【描述】会员卡更换不同的卡模板（该参数仅用在会员卡更新接口中）
【示例值】20170308000000000058101000300045
custom_assets｜资产可选string(64)
【描述】会员卡自定义资产值，只供特定业务使用，通常接入无需关注
【示例值】100元
mdcode_info｜商户动态码回传信息可选mdcodeinfodto(1024)
【描述】商户动态码回传信息：
只用于当write_off_type核销类型为mdbarcode或mdqrcode时，商户调用卡更新接口回传动态码。如需使用商户动态码，请联系支付宝凯发app官方网站的技术支持获取相关文档。
code_status｜动态码状态必选string(14)
【描述】本次回传动态码的状态：
success: 本次发码成功
fail_retry: 本次发码失败，且需要支付宝重试（重新通知商户发码）
fail_not_retry: 本次发码失败，且无需支付宝重试（无需重新通知商户发码）
【示例值】success
time_stamp｜时间戳必选number(20)
【描述】商户回传动态码的时间戳 (单位秒)。
即商户调接口回传动态码时刻对应的long类型时间戳，用于区分不同的发码请求。
【示例值】1496996459
code_value｜动态码状态可选string(128)
【描述】动态码的码值：
code_status为success时必填；
基于此码值生成条形码或二维码用于扫码核销。
【示例值】1kfcdy0002
expire_time｜过期时间可选date(19)
【描述】当前动态码的过期（失效）时间：
code_status为success时必填。
【示例值】2017-06-09 16:25:53
front_text_list｜卡面文案信息模型可选cardfronttextdto[](1024)
【描述】卡面文案列表，1项对应1行文案，最多只能传入4行文案；
单行文案展现分为左右两部分，左边对应label字段，右边对应value；
形如： 学院 新闻学院
label｜标签可选string(4)
【描述】文案标签
【示例值】专业
value｜展示文案可选string(32)
【描述】展示文案
【示例值】金融贸易
front_image_id｜卡面图片id可选string(1024)
【描述】卡面展示图片的图片id，通过接口（alipay.offline.material.image.upload）上传图片
这里预期展示的是个人照片；
图片说明：1m以内，格式bmp、png、jpeg、jpg、gif；
图片尺寸为230*295px，可等比放大；
【示例值】9fxnkgt0qfmqkal5v2bqxqaaacmaaqed
open_card_channel｜实际记录的领卡渠道特殊可选string(32)
【描述】实际记录的领卡渠道（可能跟商户传入值不同）；
可直接标识领卡渠道，也可配合open_card_channel_id标识领卡渠道类型：
例如：
线下门店领取:20161534000000000008863（直接标识领卡渠道，门店shopid）
线下扫二维码领取:qr（标识领卡类型）;
凯发app官方网站的线下活动领取:20170522000000000003609（直接标识领卡渠道，商户活动id）
【示例值】20161534000000000008863
open_card_channel_id｜实际记录的领卡来源渠道id特殊可选string(32)
【描述】实际记录的领卡来源渠道id（可能跟商户传入值不同）；
区别于open_card_channel领卡渠道；
一般使用场景：
open_card_channel用于区分渠道类型，例如取值为"shop"（门店），"activity"（活动）；
则open_card_channel_id可用于区分同渠道的不同实体，对应取各门店id或各活动的标识id等；
【示例值】123123123123
响应示例
正常示例
异常示例
{
"alipay_marketing_card_open_response": {
"code": "10000",
"msg": "success",
"card_info": {
"biz_card_no": "000001",
"external_card_no": "ext0001",
"open_date": "2014-02-20 21:20:46",
"valid_date": "2020-02-20 21:20:46",
"level": "vip1",
"point": "88",
"balance": "124.89",
"template_id": "20170308000000000058101000300045",
"custom_assets": "100元",
"mdcode_info": {
"code_status": "success",
"code_value": "1kfcdy0002",
"expire_time": "2017-06-09 16:25:53",
"time_stamp": 1496996459
},
"front_text_list": [
{
"label": "专业",
"value": "金融贸易"
}
],
"front_image_id": "9fxnkgt0qfmqkal5v2bqxqaaacmaaqed"
},
"open_card_channel": "20161534000000000008863",
"open_card_channel_id": "123123123123"
},
"sign": "eritjkeijkjhkkkkkkkhjereeeeeeeeeee"
}说明：本示例仅供参考。
公共错误码
业务错误码
| 错误码 | 错误描述 | 凯发app官方网站的解决方案 |
|---|---|---|
| system_error | 系统繁忙 | 服务器异常 可能发生了网络或者系统异常，导致服务调用失败，商户可以用同样的请求发起重试 |
| invalid_parameter | 参数有误 | 请根据接口返回的参数非法的具体错误信息，修改参数后进行重试 |
| card_has_opened | 开卡失败，用户已有此外部卡号的卡实例 | 用户已有此外部卡号的卡实例，可尝试alipay.marketing.card.update接口更新 |
| no_card_type | 没有卡类型 | 卡类型判断 |
| open_card_concurrently | 同一外部卡号并发开卡错误 | 控制并发 |
| open_card_need_openform | 开卡必须经过开卡组件 | 接入标准的开卡组件
https://opensupport.alipay.com/support/helpcenter/156/201602620379?ant_source=zsearch |
| paid_outer_card_lack_template_config | 付费外卡缺少卡模版配置 | 请补全卡模板配置。 |
| template_not_exit | 模板不存在 | 查看模板 |
| user_auth_fail | 用户授权失败 | 用户授权信息为空 |