通用场景
会员卡更新
公共请求参数
业务请求参数
target_card_no｜支付宝业务卡号必选string[1,32]
【描述】支付宝业务卡号：1、3.0（历史版本）版本来源于alipay.marketing.card.open(会员卡开卡)接口开卡后获取的 card_info.biz_card_no 值；2、极速版来源于spi.alipay.user.opencard.get(会员卡开通，获取会员卡信息)请求参数中的biz_card_no值。
【示例值】000001
target_card_no_type｜卡号id类型必选string[0,32]
【描述】卡号id类型
【枚举值】
支付宝业务卡号: biz_card
【示例值】biz_card
occur_time｜业务发生时间必选date
【描述】业务发生时间，时间格式为"yyyy-mm-dd hh:mm:ss"。
匹配格式yyyy-mm-dd hh:mm:ss的date类型
【示例值】2020-12-27 12:12:12
card_info｜商户卡信息必选merchantcard
【描述】需要修改的最新卡信息
biz_card_no｜支付宝业务卡号可选string[1,32]
【描述】支付宝业务卡号
说明：
1、开卡成功后返回该参数，需要保存留用；
2、开卡/更新/删卡/查询卡接口请求中不需要传该参数；
【示例值】000001
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
template_id｜会员卡模板id可选string[1,32]
【描述】会员卡更换不同的卡模板（该参数仅用在会员卡更新接口中）
【示例值】20170308000000000058101000300045
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
ext_info｜扩展信息可选string[0,1024]
【描述】扩展信息(暂时无用)
【示例值】{"key":"value"}
merchant_card_msg_info｜商家会员卡消息信息可选merchantcardmsginfo
【描述】商家会员卡消息信息
changed_point｜本次消息通知的变动积分可选string[0,64]
【描述】本次消息通知的变动积分，积分必须为数字型（可为浮点型，带2位小数点），格式非法则不发送消息。例如：
100，则代表增加100积分。
-100，则代表减少100积分。
【示例值】100.00
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.update&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=rsa2×tamp=${now}' \
-f 'biz_content={
"target_card_no_type":"biz_card",
"occur_time":"2020-12-27 12:12:12",
"target_card_no":"000001",
"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"
}
},
"ext_info":"{\"key\":\"value\"}",
"card_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",
"biz_card_no":"000001",
"template_id":"20170308000000000058101000300045",
"point":"88"
},
"merchant_card_msg_info":{
"changed_point":"100.00"
}
}' 说明：本示例仅供参考。
公共响应参数
业务响应参数
result_code｜处理结果码可选string(64)
【描述】二级错误处理结果（如果公用返回结果为false，则可以看这个接口判断明细原因）
如果公用返回为true，则该字段为空
【示例值】isv.update-usercard-fail
响应示例
正常示例
异常示例
{
"alipay_marketing_card_update_response": {
"code": "10000",
"msg": "success",
"result_code": "isv.update-usercard-fail"
},
"sign": "eritjkeijkjhkkkkkkkhjereeeeeeeeeee"
}说明：本示例仅供参考。
公共错误码
业务错误码
| 错误码 | 错误描述 | 凯发app官方网站的解决方案 |
|---|---|---|
| system_error | 系统繁忙 | 服务器异常 可能发生了网络或者系统异常，导致服务调用失败，商户可以用同样的请求发起重试 |
| invalid_parameter | 参数有误 | 请根据接口返回的参数非法的具体错误信息，修改参数后进行重试 |
| card_not_exit | 会员卡不存在 | 核对所有描述卡号的字段，和开卡时的是否一致（包括支付宝业务卡号、商户外部卡号） |
| no_card_type | 没有卡类型 | 卡类型判断 |
| paidoutercard_lack_template_config | 付费外卡缺少模版配置 | 核对付费外卡模板号是否正确 |