修改会员卡模板信息
更新时间:2025.08.01更新会员卡的信息,包括基本信息、储值信息、开卡信息等
接口限频:按品牌商户品牌 ID 维度 5 次/秒
接口说明
支持商户:【品牌商户】
请求方式:【PATCH】/brand/card-member/cards/{card_id}
请求域名:【主域名】https://api.mch.weixin.qq.com 使用该域名将访问就近的接入点
【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点 ,指引点击查看
请求参数
Header HTTP头参数
Authorization 必填 string
请参考签名认证生成认证信息
Accept 必填 string
请设置为application/json
Content-Type 必填 string
请设置为application/json
Wechatpay-Serial 必填 string
【微信支付公钥ID】 请传入brand_id对应的微信支付公钥ID,接口将会校验两者的关联关系,参考微信支付公钥产品简介及使用说明获取微信支付公钥ID和相关的介绍。以下两种场景将使用到微信支付公钥: 1、接收到接口的返回内容,需要使用微信支付公钥进行验签; 2、调用含有敏感信息参数(如姓名、身份证号码)的接口时,需要使用微信支付公钥加密敏感信息后再传输参数,加密指引请参考微信支付公钥加密敏感信息指引。
path 路径参数
card_id 必填 string(32)
【会员卡模板 ID】 商家创建会员卡模板成功后系统返回的会员卡模板ID
body 包体参数
card_title 选填 string(10)
【卡名称】 1.可用于展示在卡面的名称 2.支持最长10个中文字 3.支持中文字、英文字符、标点
card_color 选填 string(7)
【卡背景颜色】 用于卡片正面设计的RGB颜色编码,仅支持十六进制
card_picture_url 选填 string(256)
【卡图片】 商家自定义会员卡背景图。仅支持通过图片上传API接口获取的图片URL地址。支持JPG/JPEG/PNG格式,建议尺寸716px*320px,且图片小于1M。请查看以下链接后传入:图片要求示例,图片上传API指引
code_jump_information 选填 object
【会员码跳转信息】 会员码跳转的小程序信息,当会员码展示类型为跳转商家小程序时必填。
属性 | |
benefits 选填 string(32)
【会员权益】 会员权益是指平台、品牌或服务机构为付费会员(或等级会员)提供的专属优惠、服务或特权。
notify_url 选填 string(256)
【回调地址】 商家接收开卡成功回调通知的地址,需按照notify_url填写注意事项规范填写。
need_pinned 选填 boolean
【是否置顶】 置顶卡是界面中的一种特殊展示模块,通过人工设置,使其固定在内容列表的顶部位置,确保用户优先看到。默认为false。同一个品牌下允许存在多张置顶卡,按照更新时间倒序排序。
need_display_level 选填 boolean
【是否展示会员等级】 是否在会员卡面向用户展示等级信息,默认不展示(false)
service_phone 选填 string(32)
【服务电话】 展示在会员卡详情内,建议填写商家固定电话
valid_date_information 选填 object
【会员卡有效期】 会员卡有效期
属性 | |
member_information 选填 object
【会员中心信息】 用户点击会员卡卡面的跳转信息
属性 | |
points_information 选填 object
【积分信息】 若商家名片会员卡使用该功能,需传入跳转商家小程序的信息。否则不启动该功能。
属性 | |
balance_information 选填 object
【储值信息】 若商家名片会员卡使用该功能,需传入跳转商家小程序的信息。否则不启动该功能。
属性 | |
purchase_information 选填 object
【付费会员信息】 若商家名片会员卡使用该功能,需传入跳转商家小程序的信息及会员价格。否则不启动该功能。
属性 | |
user_information 选填 object
【用户开卡信息】 要求用户在开通会员卡时必须填写的信息。若用户不填写则不允许开通会员卡。
属性 | |
请求示例
PATCH
应答参数
200 OK
out_request_no 必填 string(128)
【商家请求单号】 商家创建会员卡模板凭据号。商家自定义,注意保持唯一性,仅供参考的格式:品牌ID+时间戳+流水号。字符仅允许包含英文半角的数字、字母、连接线-和下划线_。
card_id 必填 string(32)
【会员卡模板 ID】 商家创建会员卡模板成功后系统返回的会员卡模板ID
brand_id 必填 string(32)
【品牌ID】 商家进驻微信支付品牌商家后获得的品牌ID(灰度期间联系微信支付运营获取),用于标记该会员卡的归属方
appid 必填 string
【商家AppID】 商家的AppID,可以是服务号、订阅号、公众号、小程序的AppID。1、该AppID用于获取会员OpenID。2、该AppID需要与会员卡归属品牌有B-A关系。
card_type 必填 string
【会员卡类型】 支持付费、普通、储值 3 种类型。目前仅支持普通会员卡,填写付费和储值类型时会返回错误。
可选取值
PURCHASE
: 付费NORMAL
: 普通BALANCE
: 储值
card_title 必填 string(10)
【卡名称】 1.可用于展示在卡面的名称 2.支持最长10个中文字 3.支持中文字、英文字符、标点
card_color 必填 string(7)
【卡背景颜色】 用于卡片正面设计的RGB颜色编码,仅支持十六进制
card_picture_url 必填 string(256)
【卡图片】 商家自定义会员卡背景图。仅支持通过图片上传API接口获取的图片URL地址。支持JPG/JPEG/PNG格式,建议尺寸716px*320px,且图片小于1M。请查看以下链接后传入:图片要求示例,图片上传API指引
code_mode 必填 string
【会员卡code分配类型】 1、会员卡code是会员在一个会员卡模板下唯一身份标识,平台支持2种分配类型:(1)SYSTEM_ALLOCATE 微信支付系统分配,用户领取会员卡时从微信系统分配24位数字作为会员code;(2)MERCHANT_ALLOCATE 商家分配,商家同步会员开通结果时传入,用户开卡成功或失败都以商家传入的code作为会员卡code。 2、会员卡code分配模式若为“系统分配”,不支持修改为“商家分配”。
可选取值
SYSTEM_ALLOCATE
: 系统分配MERCHANT_ALLOCATE
: 商家分配
code_type 必填 string
【会员码展示类型】 会员码支持不展示码/二维码/条形码/二维码+条形码/跳转商家小程序5种设置。
可选取值
NONE_CODE
: 不显示任何码型BAR_CODE
: 条形码QR_CODE
: 二维码BAR_CODE_AND_QR_CODE
: 条形码和二维码JUMP_MINI_PROGRAM
: 跳转商家小程序
code_jump_information 选填 object
【会员码跳转信息】 会员码跳转的小程序信息,当会员码展示类型为跳转商家小程序时必填。
属性 | |
benefits 必填 string(32)
【会员权益】 会员权益是指平台、品牌或服务机构为付费会员(或等级会员)提供的专属优惠、服务或特权。
notify_url 必填 string(256)
【回调地址】 商家接收开卡成功回调通知的地址,需按照notify_url填写注意事项规范填写。
need_pinned 选填 boolean
【是否置顶】 置顶卡是界面中的一种特殊展示模块,通过人工设置,使其固定在内容列表的顶部位置,确保用户优先看到。默认为false。同一个品牌下允许存在多张置顶卡,按照更新时间倒序排序。
need_display_level 选填 boolean
【是否展示会员等级】 是否在会员卡面向用户展示等级信息,默认不展示(false)
init_level 选填 string(10)
【会员初始等级】 展示字段,商家可以自定义填写内容。如果选择了展示会员等级,必填init_level
,作为新用户开卡后的初始等级。如因商家业务规则需要变更某会员等级,可通过更新用户会员卡接口更新等级信息。
service_phone 选填 string(32)
【服务电话】 展示在会员卡详情内,建议填写商家固定电话
legal_agreement 必填 string(20480)
【商家法务协议】 商家法务协议是用户与商家之间签订的具有法律效力的合同文件,旨在明确双方在交易、服务提供、权利义务等方面的规则,以保障交易安全、规范商业行为,并在纠纷发生时提供法律依据。不支持换行和链接跳转,只支持纯文本展示。
valid_date_information 必填 object
【会员卡有效期】 会员卡有效期
属性 | |
member_information 必填 object
【会员中心信息】 用户点击会员卡卡面的跳转信息
属性 | |
points_information 选填 object
【积分信息】 若商家名片会员卡使用该功能,需传入跳转商家小程序的信息。否则不启动该功能。
属性 | |
balance_information 选填 object
【储值信息】 若商家名片会员卡使用该功能,需传入跳转商家小程序的信息。否则不启动该功能。
属性 | |
purchase_information 选填 object
【付费会员信息】 若商家名片会员卡使用该功能,需传入跳转商家小程序的信息及会员价格。否则不启动该功能。
属性 | |
user_information 选填 object
【用户开卡信息】 要求用户在开通会员卡时必须填写的信息。若用户不填写则不允许开通会员卡。
属性 | |
state 必填 string
【状态】 会员卡状态信息
可选取值
CARD_EFFECTIVE
: 生效中CARD_INVALID
: 已失效
create_time 必填 string(32)
【创建时间】 创建会员卡的时间,需遵循 RFC3339 标准格式:yyyy-MM-DDTHH:mm:ss+TIMEZONE。yyyy-MM-DD 表示年月日;T 字符用于分隔日期和时间部分;HH:mm:ss 表示具体的时分秒;TIMEZONE 表示时区(例如,+08:00 对应东八区时间,即北京时间)。示例:2015-05-20T13:29:35+08:00 表示北京时间2015年5月20日13点29分35秒。
modify_time 必填 string(32)
【更新时间】 更新会员卡的时间,需遵循 RFC3339 标准格式:yyyy-MM-DDTHH:mm:ss+TIMEZONE。yyyy-MM-DD 表示年月日;T 字符用于分隔日期和时间部分;HH:mm:ss 表示具体的时分秒;TIMEZONE 表示时区(例如,+08:00 对应东八区时间,即北京时间)。示例:2015-05-20T13:29:35+08:00 表示北京时间2015年5月20日13点29分35秒。
应答示例
200 OK
错误码
公共错误码
状态码 | 错误码 | 描述 | 解决方案 |
---|---|---|---|
400 | PARAM_ERROR | 参数错误 | 请根据错误提示正确传入参数 |
400 | INVALID_REQUEST | HTTP 请求不符合微信支付 APIv3 接口规则 | 请参阅 接口规则 |
401 | SIGN_ERROR | 验证不通过 | 请参阅 签名常见问题 |
500 | SYSTEM_ERROR | 系统异常,请稍后重试 | 请稍后重试 |
业务错误码
状态码 | 错误码 | 描述 | 解决方案 |
---|---|---|---|
400 | PARAM_ERROR | 会员中心跳转AppID 无效或与品牌 ID 没有绑定关系 | 请检查会员中心跳转的AppID是否有效,并确认其与品牌ID的绑定关系 |
400 | PARAM_ERROR | 会员码跳转AppID无效或与品牌 ID 没有绑定关系 | 请检查会员码跳转的AppID是否有效,并确认其与品牌ID的绑定关系 |
400 | PARAM_ERROR | 积分跳转AppID无效或与品牌 ID 没有绑定关系 | 请检查积分跳转的AppID是否有效,并确认其与品牌ID的绑定关系 |
400 | PARAM_ERROR | 储值跳转AppID无效或与品牌 ID 没有绑定关系 | 请检查储值跳转的AppID是否有效,并确认其与品牌ID的绑定关系 |
400 | PARAM_ERROR | 付费跳转AppID无效或与品牌 ID 没有绑定关系 | 请检查付费跳转的AppID是否有效,并确认其与品牌ID的绑定关系 |
400 | PARAM_ERROR | 请求内容或图片不符合法规,请重试 | 请检查提交的内容或图片是否合规,修改后重试 |
404 | NOT_FOUND | 会员卡模板不存在 | 请检查会员卡模板ID是否正确,或创建新的会员卡模板 |
400 | PARAM_ERROR | 会员码型不是跳转商家小程序,不支持修改跳转信息 | 请先将会员码型设置为跳转商家小程序后再修改跳转信息 |
400 | PARAM_ERROR | 非储值会员卡,不允许填写储值小程序信息 | 请移除储值小程序相关信息 |
400 | PARAM_ERROR | 非付费会员卡,不允许填写付费小程序信息 | 请移除付费小程序相关信息 |
400 | PARAM_ERROR | 付费会员价格必须大于 0 | 请设置一个大于0的会员价格 |
400 | PARAM_ERROR | 卡名称太长,支持最长10个中文字、英文字符、标点 | 请修改卡名称,确保长度不超过10个字符 |
400 | PARAM_ERROR | 卡名称仅支持中英文字符、数字和标点 | 请修改卡名称,移除不支持的特殊字符 |
400 | PARAM_ERROR | 卡模版有效期类型和请求的有效期类型不一致 | 请确保请求中的有效期类型与卡模板设置的有效期类型一致 |
400 | PARAM_ERROR | 绝对有效期卡模板必填有效期信息,不允许填写有效天数信息 | 请填写具体的有效期开始和结束时间,并移除有效天数信息 |
400 | PARAM_ERROR | 固定时间范围不允许填写领取后有效天数 | 当有效期类型为固定时间时,请移除领取后有效天数字段 |
400 | PARAM_ERROR | 固定时间范围的开始时间不能大于结束时间 | 请检查并修改固定时间范围,确保开始时间早于或等于结束时间 |
400 | PARAM_ERROR | 相对有效期卡模板必填有效天数信息,不允许填写有效期信息 | 请填写领取后有效天数,并移除具体的有效期开始和结束时间 |
400 | PARAM_ERROR | 领取后有效天数必须大于0 | 请设置一个大于0的有效天数 |
400 | PARAM_ERROR | 领取后有效天数不能大于30年(10958 天) | 请设置一个小于等于10958天的有效天数 |
400 | PARAM_ERROR | 永久有效不允许设置相对有效期 | 当有效期类型为永久时,请移除领取后有效天数字段 |
400 | PARAM_ERROR | 永久有效不允许设置固定时间有效的开始时间 | 当有效期类型为永久时,请移除开始时间字段 |
400 | PARAM_ERROR | 永久有效不允许设置固定时间有效的结束时间 | 当有效期类型为永久时,请移除结束时间字段 |
400 | PARAM_ERROR | 用户信息通用字段存在重复项 | 请检查用户信息通用字段,移除重复的字段定义 |
400 | PARAM_ERROR | 用户信息自定义字段存在重复项 | 请检查用户信息自定义字段,移除重复的字段定义 |
400 | PARAM_ERROR | 商户自定义信息最多一项,字段值列表最少1个,最多10个,单个列表限制8个字符 | 请检查商户自定义信息,确保其数量、列表长度和字符数符合限制 |
400 | PARAM_ERROR | 用户信息自定义字段中,用户选择的值的字符串非法 | 请检查用户提交的自定义字段值,确保编码和内容合法 |
400 | PARAM_ERROR | 会员中心跳转 AppID 或路径为空 | 请填写会员中心跳转所需的AppID和页面路径 |
400 | PARAM_ERROR | 会员码跳转 AppID 或路径为空 | 请填写会员码跳转所需的AppID和页面路径 |
400 | PARAM_ERROR | 积分跳转 AppID 或路径为空 | 请填写积分跳转所需的AppID和页面路径 |
400 | PARAM_ERROR | 储值跳转 AppID 或路径为空 | 请填写储值跳转所需的AppID和页面路径 |
400 | PARAM_ERROR | 付费跳转 AppID 或路径为空 | 请填写付费跳转所需的AppID和页面路径 |
400 | INVALID_REQUEST | 商家未开通商家名片会员功能 | 请联系运营为该商家开通商家名片会员功能 |