修改会员卡模板信息

更新时间：2024.11.18

更新会员卡的信息，包括基本信息、储值信息、开卡信息、补充说明

接口说明

支持商户：【普通服务商】

请求方式：【PATCH】/v3/marketing/membercard-open/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

path 路径参数

card_id 　必填 string(32)

【会员卡模板ID】商户创建微信会员卡模板成功后系统返回的会员卡模板ID

body 包体参数

appid 　选填 string(32)

【商户AppID】商户的公众号AppID。

1、只能为服务号AppID，不支持APP、小程序、订阅号的AppID。

2、该AppID用于获取会员OpenID及UnionID。

3、会员相关（会员状态、权益、服务）消息将通过该服务号触达用户

4、该AppID需要与会员卡归属品牌有B-A关系

logo_url 　选填 string(128)

【会员卡logo】会员卡logo的URL地址。仅支持通过《图片上传API》接口获取的图片URL地址。

1、商户logo大小需为120像素*120像素。

2、支持JPG/JPEG/PNG格式，且图片小于1M。

title 　选填 string(10)

【卡名称】 1.展示在卡面上

2.支持最长10个中文字

3.支持中文字、英文字符、标点

background_picture_url 　选填 string(128)

【会员卡背景图】商家自定义会员卡背景图。仅支持通过图片上传API接口获取的图片URL地址。支持JPG/JPEG/PNG格式，且图片小于1M。

description 　选填 string(500)

【使用须知】展示在会员卡详情内，最长500个中文字符，建议填写会员权益及服务相关描述。

service_phone 　选填 string(32)

【服务电话】展示在会员卡详情内，建议填写商家固定电话。

total_quantity 　选填 integer

【会员卡总库存】可投放的最大会员卡数量。仅在会员卡code分配类型为系统自动分配（SYSTEM_ALLOCATE）时需要填写，其他分配类型不需要填写库存。系统分配code类型下，若未填写总库存，则微信支付系统会默认将总库存设置为5000000 （默认值）。

date_information 　选填 object

【有效期】有效期

属性

type 　必填 string(16)

【有效期类型】 1.该有效期为会员卡激活后的有效期

2.支持绝对有效期&相对有效期设置

3.绝对有效期：固定过期时间，格式为yyyy-mm-dd hh-mm-ss

4.相对有效期：用户激活后x天后有效，x为天数。最多支持10,957天（30年）

5.永久有效

6.过期后卡状态变为“已过期”，出现在卡包历史卡券。

7.过期后不再出现服务项，且会员服务触达无法再次下发

可选取值

FIX_TIME_RANGE: 必填available_begin_time和available_end_time，会员卡在此时间[available_begin_time, available_end_time)范围内有效
FIX_TERM: 必填available_day_after_receive和wait_days_after_receive
PERMANENT: 会员卡激活后永久有效

available_begin_time 　选填 string(32)

【有效期开始时间】 type为FIX_TIME_RANGE时专用，表示有效期开始时间，遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss.sss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss.sss表示时分秒毫秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2020-05-20T13:29:35.120+08:00表示北京时间2020年05月20日13点29分35秒。

available_end_time 　选填 string(32)

【有效期结束时间】 type为FIX_TERM_RANGE时专用，表示有效期结束时间，遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss.sss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss.sss表示时分秒毫秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2020-05-20T13:29:35.120+08:00表示北京时间2020年05月20日13点29分35秒。

available_day_after_receive 　选填 integer

【生效后N天内有效】 type为FIX_TERM时专用，表示生效后N天内有效，领取后当天有效填写0（单位为天）。最长不超过30年

wait_days_after_receive 　选填 integer

【领取后N天开始生效】 type为FIX_TERM时专用，表示自领取后N天开始生效。（单位为天）

init_level 　选填 string(5)

【会员初始等级】如果展示会员等级，必填init_level，作为新用户开卡后的初始等级。如因商家业务规则需要变更某会员等级，可通过更新用户会员卡接口更新等级信息

balance_information 　选填 object

【储值信息】

属性

user_information_form 　选填 object

【开卡信息】用户在开通会员卡时需要填写的信息

属性

can_modify_after_activate 　选填 boolean

【是否允许修改】是否允许用户在激活成功后修改信息

common_field_list 　选填 array[string]

【平台提供的通用开卡信息字段】平台提供了一些通用的开卡字段供开发者选用

可选取值

USER_FORM_FLAG_MOBILE: 用户开卡时填写手机号
USER_FORM_FLAG_SEX: 用户开卡时填写性别
USER_FORM_FLAG_NAME: 用户开卡时填写姓名
USER_FORM_FLAG_BIRTHDAY: 用户开卡时填写生日
USER_FORM_FLAG_ADDRESS: 用户开卡时填写地址
USER_FORM_FLAG_EMAIL: 用户开卡时填写邮箱
USER_FORM_FLAG_CITY: 用户开卡时填写城市

custom_field_list 　选填 array[object]

【商户自定义的开卡信息字段】商户自定义的开卡信息字段

属性

type 　选填 string

【字段类型】选择所需的字段类型

可选取值

TEXT: 用户可自由输入文本
SELECT: 用户可从商户提供的选项中进行选择
RADIO: 用户可从商户提供的选项中选择一项
CHECK_BOX: 用户可从商户提供的选项中选择一到多项

name 　选填 string(5)

【字段名称】信息项的名称

values 　选填 array[string(8)]

【字段值】信息项的值列表

特殊规则：列表最多支持10个，单个列表限制8个字符

additional_statement 　选填 object

【商户补充声明】

属性

code_mode 　选填 string

【会员卡code分配类型】仅支持MERCHANT_DEPOSIT和REAL_TIME之间互转，SYSTEM_ALLOCATE模式不支持修改

可选取值

SYSTEM_ALLOCATE: 由微信支付系统自动分配
MERCHANT_DEPOSIT: 商户预先存入自定义code，用户开卡时系统随机选取存入的code
REAL_TIME: 商户在用户开卡时实时传入自定义code

need_dynamic_code 　选填 boolean

【是否启用动态码】是否启用动态码功能。若启用，用户会员卡的身份识别码会被系统生成的18位数字取替，动态改变，可有效保障用户的储值资产安全，降低用户因被截图带来的储值盗用风险。默认为false

code_type 　选填 string

【会员码型】会员码支持二维码／条形码／二维码＋条形码/不展示码4种设置。码根据membership_number字段生成，用户领卡后membership_number默认为code值，支持商户通过更新用户会员卡接口更新，用于适配商家会员码规范

可选取值

BAR_CODE: 条形码
QRCODE: 二维码
BAR_CODE_AND_QRCODE: 条形码和二维码
NONE_CODE: 不显示任何码型

请求示例

PATCH

1curl -X PATCH \
2  https://api.mch.weixin.qq.com/v3/marketing/membercard-open/cards/pbLatjvWOibDc5-TBnbUk1pD12o0 \
3  -H "Authorization: WECHATPAY2-SHA256-RSA2048 mchid=\"1900000001\",..." \
4  -H "Accept: application/json" \
5  -H "Content-Type: application/json" \
6  -d '{
7    "appid" : "wxea9c30890f48d5ae",
8    "logo_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/0",
9    "title" : "微信支付测试卡",
10    "background_picture_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/xxxxx/0",
11    "description" : "使用本会员卡表示你同意xxx公司的协议，最终解释权归xxx公司所有",
12    "service_phone" : "010-8877xxxx",
13    "total_quantity" : 5000000,
14    "date_information" : {
15      "type" : "FIX_TIME_RANGE",
16      "available_begin_time" : "2020-05-20T13:29:35.120+08:00",
17      "available_end_time" : "2030-05-20T13:29:35.120+08:00",
18      "available_day_after_receive" : 1,
19      "wait_days_after_receive" : 1
20    },
21    "init_level" : "白银会员",
22    "balance_information" : {
23      "need_balance" : false,
24      "balance_appid" : "wxea9c30890f48d5ae",
25      "balance_path" : "pages/balance/balance",
26      "balance_url" : "https://xxx.com"
27    },
28    "user_information_form" : {
29      "can_modify_after_activate" : false,
30      "common_field_list" : [
31        "USER_FORM_FLAG_MOBILE"
32      ],
33      "custom_field_list" : [
34        {
35          "type" : "TEXT",
36          "name" : "喜欢的运动",
37          "values" : [
38            "篮球"
39          ]
40        }
41      ]
42    },
43    "additional_statement" : {
44      "title" : "xxx会员卡使用须知",
45      "url" : "https://xxx.111.com",
46      "appid" : "wxea9c30890f48d5ae",
47      "path" : "pages/statement/statement"
48    },
49    "code_mode" : "SYSTEM_ALLOCATE",
50    "need_dynamic_code" : false,
51    "code_type" : "BAR_CODE"
52  }'
53

应答参数

无应答包体

应答示例

204 No Content

1'无应答包体'
2

错误码

公共错误码

状态码	错误码	描述	解决方案
400	PARAM_ERROR	参数错误	请根据错误提示正确传入参数
400	INVALID_REQUEST	HTTP 请求不符合微信支付 APIv3 接口规则	请参阅接口规则
401	SIGN_ERROR	验证不通过	请参阅签名常见问题
500	SYSTEM_ERROR	系统异常，请稍后重试	请稍后重试

业务错误码

状态码	错误码	描述	解决方案
403	NO_AUTH	商户暂无权限使用此功能	请开通商户号权限。请联系产品或商务申请
500	SYSTEM_ERROR	生成二维码链接失败，请重试	系统异常，请使用相同参数稍后重新调用
400	INVALID_REQUEST	扫码投放场景不支持实时code模式	请更换非实时code模式的会员卡再重试
400	INVALID_REQUEST	会员卡的创建商户号不等于调用方商户号	请使用会员卡的创建商户号进行操作
400	INVALID_REQUEST	请先升级会员卡才能使用此功能	请先调用《升级会员卡API》升级会员卡
400	INVALID_REQUEST	AppID非服务号	请使用正确的服务号的AppID重新调用，不支持App、小程序、订阅号。
400	INVALID_REQUEST	会员卡code分配类型不支持修改	会员卡code分配类型为“系统分配”，不支持修改
400	INVALID_REQUEST	会员卡code分配类型不支持修改为“系统分配”	会员卡code分配类型无法修改为“系统分配”。
400	INVALID_REQUEST	储值小程序path为空	请填写储值小程序path
400	INVALID_REQUEST	会员卡ID无效	请检查会员卡ID是否正确填写
400	INVALID_REQUEST	该会员1年内未在本商家有微信支付交易，无法导入	请更换手机号重试
400	INVALID_REQUEST	会员已经领取过该卡	请使用其他会员卡
400	INVALID_REQUEST	会员卡code为实时模式，需要传入卡code	请填入卡code
400	INVALID_REQUEST	积分跳转path为空	请填写积分跳转path
400	INVALID_REQUEST	自助积分跳转path为空	请填写自助积分跳转path
400	INVALID_REQUEST	会员专享价跳转path为空	请填写会员专享价跳转path
400	INVALID_REQUEST	该手机号和会员卡已被导入过	请更换手机号或会员卡ID重试
400	INVALID_REQUEST	该商户号不是会员卡的创建商户号	请使用会员卡的创建商户号进行操作
400	INVALID_REQUEST	手机号未绑定微信号，无法导入	请更换手机号重试
400	INVALID_REQUEST	商户无授权，请重试	请开通商户号权限。请联系产品或商务申请
400	INVALID_REQUEST	该手机号会员卡记录不存在	请更换手机号或会员卡ID重试
400	INVALID_REQUEST	没有符合条件的数据	请使用正确的参数重新调用
400	INVALID_REQUEST	商户号不属于该卡的创建方	请使用会员卡创建方的商户号重新调用
400	INVALID_REQUEST	会员卡已经迁移	会员卡已经迁移，无需重复操作
400	INVALID_REQUEST	会员权益一旦展示无法关闭	会员权益一旦展示无法关闭
400	INVALID_REQUEST	会员储值一旦展示无法关闭	会员储值一旦展示无法关闭
400	INVALID_REQUEST	需要上架至少一个积分权益、优惠权益、服务才可以投放	请先给会员卡上架至少一个积分权益、优惠权益、服务
400	PARAM ERROR	AppID有误	请使用正确的AppID重新调用
400	PARAM ERROR	OpenID有误	请使用正确的OpenID重新调用
400	PARAM ERROR	商户和品牌关系校验失败	请先将商户号绑定到品牌
400	PARAM ERROR	品牌、AppID关系校验失败	请先将AppID绑定到品牌

文档是否有帮助

更多支持

开发文档(商户)开发文档(V2版)开发者社区微信开放平台微信公众平台腾讯客服