修改会员卡模板信息
更新时间:2025.08.01更新会员卡的信息,包括基本信息、储值信息、开卡信息等
接口说明
支持商户:【品牌商户】
请求方式:【PATCH】/brand/card-member/cards/{card_id}
请求域名:【主域名】https://api.mch.weixin.qq.com 使用该域名将访问就近的接入点
【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点 ,指引点击查看
接口限频:10/秒(品牌ID维度)
请求参数
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
【会员码跳转信息】 会员码跳转的小程序信息,当会员码展示类型为跳转商家小程序时必填。
| 属性 | |
jump_appid 选填 string(32) 【会员码跳转AppID】 会员码跳转的小程序AppID jump_path 选填 string(128) 【会员码跳转路径】 会员码跳转的小程序路径 |
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
【会员卡有效期】 会员卡有效期
| 属性 | |
type 选填 string 【有效期类型】 1.该有效期为会员卡激活后的有效期 2.支持绝对有效期&相对有效期设置 3.绝对有效期:固定过期时间,需遵循 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秒。 4.相对有效期:用户激活后x天后有效,x为天数。最多支持10,957天(30年) 5.永久有效 6.过期后卡状态变为“已过期” 7.过期后不再出现服务项,且无法给用户发送会员服务消息通知 可选取值
available_begin_time 选填 string 【有效期开始时间】 type为FIX_TIME_RANGE时专用, 表示有效期开始时间。需需遵循 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秒。 available_end_time 选填 string 【有效期结束时间】 type为FIX_TIME_RANGE时专用,表示有效期结束时间。需需遵循 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秒。 available_day_after_receive 选填 integer 【领取后N天内有效】 type为FIX_TERM时专用,表示领取后N个自然天内有效。最长不超过30年(10958 天) |
member_information 选填 object
【会员中心信息】 用户点击会员卡卡面的跳转信息
| 属性 | |
jump_appid 必填 string(32) 【会员中心跳转AppID】 用户点击会员卡卡面后跳转的小程序AppID jump_path 必填 string(128) 【会员中心跳转路径】 用户点击会员卡卡面后跳转的小程序路径 |
points_information 选填 object
【积分信息】 若商家名片会员卡使用该功能,需传入跳转商家小程序的信息。否则不启动该功能。
| 属性 | |
jump_appid 选填 string(32) 【积分跳转AppID】 会员积分跳转的小程序AppID jump_path 选填 string(128) 【积分跳转路径】 会员积分跳转的小程序路径 |
balance_information 选填 object
【储值信息】 若商家名片会员卡使用该功能,需传入跳转商家小程序的信息。否则不启动该功能。
| 属性 | |
jump_appid 选填 string(32) 【储值小程序AppID】 点击储值额跳转的小程序AppID jump_path 选填 string(128) 【储值小程序路径】 点击储值额跳转的小程序页面路径,建议为储值充值页面 |
purchase_information 选填 object
【付费会员信息】 若商家名片会员卡使用该功能,需传入跳转商家小程序的信息及会员价格。否则不启动该功能。
| 属性 | |
price 选填 integer 【付费会员价格】 指用户为获取特定商家提供的会员权益而需支付的费用金额。(单位:分) jump_appid 选填 string(32) 【付费会员跳转AppID】 用户购买付费会员时跳转的付费会员的AppID jump_path 选填 string(128) 【付费会员跳转路径】 用户购买付费会员时购买跳转的路径 |
user_information 选填 object
【用户开卡信息】 要求用户在开通会员卡时必须填写的信息。若用户不填写则不允许开通会员卡。
| 属性 | |||||
common_field_list 选填 array[string] 【平台提供的通用开卡信息字段】 平台提供的通用开卡信息字段。若商户在会员卡模板中设置该值,则查询结果中会返回给商户。 可选取值
custom_field_list 选填 array[object] 【商家自定义的开卡信息字段】 商家自定义的开卡信息字段。若商户在会员卡模板中设置该值,则查询结果中会返回给商户。当前最多只允许传入1项。
|
请求示例
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
【会员码跳转信息】 会员码跳转的小程序信息,当会员码展示类型为跳转商家小程序时必填。
| 属性 | |
jump_appid 选填 string(32) 【会员码跳转AppID】 会员码跳转的小程序AppID jump_path 选填 string(128) 【会员码跳转路径】 会员码跳转的小程序路径 |
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)
【商家法务协议】 指用户与商家之间签订的具有法律效力的合同文件,旨在明确双方在交易、服务提供、权利义务等方面的规则,以保障交易安全、规范商业行为,并在纠纷发生时提供法律依据。不支持链接跳转,支持使用\n代表换行,只支持纯文本展示。
valid_date_information 必填 object
【会员卡有效期】 会员卡有效期
| 属性 | |
type 选填 string 【有效期类型】 1.该有效期为会员卡激活后的有效期 2.支持绝对有效期&相对有效期设置 3.绝对有效期:固定过期时间,需遵循 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秒。 4.相对有效期:用户激活后x天后有效,x为天数。最多支持10,957天(30年) 5.永久有效 6.过期后卡状态变为“已过期” 7.过期后不再出现服务项,且无法给用户发送会员服务消息通知 可选取值
available_begin_time 选填 string 【有效期开始时间】 type为FIX_TIME_RANGE时专用, 表示有效期开始时间。需需遵循 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秒。 available_end_time 选填 string 【有效期结束时间】 type为FIX_TIME_RANGE时专用,表示有效期结束时间。需需遵循 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秒。 available_day_after_receive 选填 integer 【领取后N天内有效】 type为FIX_TERM时专用,表示领取后N个自然天内有效。最长不超过30年(10958 天) |
member_information 必填 object
【会员中心信息】 用户点击会员卡卡面的跳转信息
| 属性 | |
jump_appid 必填 string(32) 【会员中心跳转AppID】 用户点击会员卡卡面后跳转的小程序AppID jump_path 必填 string(128) 【会员中心跳转路径】 用户点击会员卡卡面后跳转的小程序路径 |
points_information 选填 object
【积分信息】 若商家名片会员卡使用该功能,需传入跳转商家小程序的信息。否则不启动该功能。
| 属性 | |
jump_appid 选填 string(32) 【积分跳转AppID】 会员积分跳转的小程序AppID jump_path 选填 string(128) 【积分跳转路径】 会员积分跳转的小程序路径 |
balance_information 选填 object
【储值信息】 若商家名片会员卡使用该功能,需传入跳转商家小程序的信息。否则不启动该功能。
| 属性 | |
jump_appid 选填 string(32) 【储值小程序AppID】 点击储值额跳转的小程序AppID jump_path 选填 string(128) 【储值小程序路径】 点击储值额跳转的小程序页面路径,建议为储值充值页面 |
purchase_information 选填 object
【付费会员信息】 若商家名片会员卡使用该功能,需传入跳转商家小程序的信息及会员价格。否则不启动该功能。
| 属性 | |
price 选填 integer 【付费会员价格】 指用户为获取特定商家提供的会员权益而需支付的费用金额。(单位:分) jump_appid 选填 string(32) 【付费会员跳转AppID】 用户购买付费会员时跳转的付费会员的AppID jump_path 选填 string(128) 【付费会员跳转路径】 用户购买付费会员时购买跳转的路径 |
user_information 选填 object
【用户开卡信息】 要求用户在开通会员卡时必须填写的信息。若用户不填写则不允许开通会员卡。
| 属性 | |||||
common_field_list 选填 array[string] 【平台提供的通用开卡信息字段】 平台提供的通用开卡信息字段。若商户在会员卡模板中设置该值,则查询结果中会返回给商户。 可选取值
custom_field_list 选填 array[object] 【商家自定义的开卡信息字段】 商家自定义的开卡信息字段。若商户在会员卡模板中设置该值,则查询结果中会返回给商户。当前最多只允许传入1项。
|
state 必填 string
【状态】 会员卡状态信息
可选取值
CARD_EFFECTIVE: 生效中CARD_INVALID: 已失效
create_time 必填 string
【创建时间】 创建会员卡的时间,需遵循 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
【更新时间】 更新会员卡的时间,需遵循 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
错误码
以下是本接口返回的错误码列表。详细错误码规则,请参考微信支付接口规则-错误码和错误提示

