同步会员开通结果
更新时间:2025.06.22用户通过入会组件和商家名片开卡后,微信支付会回调通知给商家,且商家必须再把开卡结果同步给微信支付侧才算开卡成功(注意:通过API导入和下单同步等方式无需同步开卡结果)。在同步开卡结果时商家可修改部分会员卡信息
接口限频:按服务商商户号维度 5次/秒
接口说明
支持商户:【普通服务商】
请求方式:【POST】/v3/brand/partner/card-member/user-cards/{user_card_code}/confirm
请求域名:【主域名】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】或【微信支付平台证书序列号】 请求参数中的敏感字段,需要使用微信支付公钥加密(推荐),请参考获取微信支付公钥ID说明以及微信支付公钥加密敏感信息指引;也可以使用微信支付平台证书公钥加密,参考获取平台证书序列号、平台证书加密敏感信息指引
path 路径参数
user_card_code 必填 string(32)
【会员卡code】 会员在一个会员卡模板下的唯一标识,用户领取会员卡后获得的code。只能填写数字/英文/半角标点。平台支持2种会员卡code分配类型:(1)SYSTEM_ALLOCATE 微信支付系统分配,用户领取会员卡时从微信系统分配24位数字作为会员code;(2)MERCHANT_ALLOCATE 商家分配,商家同步会员开通结果时传入,用户开卡成功或失败都以商家传入的code作为会员卡code。
query 查询参数
card_id 必填 string(32)
【会员卡模板 ID】 商家创建会员卡模板成功后系统返回的会员卡模板ID
body 包体参数
brand_id 必填 string(32)
【品牌ID】 商家进驻微信支付品牌商家后获得的品牌ID(灰度期间联系微信支付运营获取),用于标记该会员卡的归属方
openid 必填 string(128)
【用户标识】 用户在品牌商家会员卡模板AppID下的唯一标识,获取方式详见参数说明。
card_color 选填 string(7)
【卡背景颜色】 用于卡片正面设计的RGB颜色编码,仅支持十六进制
card_picture_url 选填 string(256)
【卡图片】 商家自定义会员卡背景图。仅支持通过图片上传API接口获取的图片URL地址。支持JPG/JPEG/PNG格式,建议尺寸716px*320px,且图片小于1M。查看以下链接后传入:图片要求示例,图片上传API指引。
phone_number 选填 string(512)
【加密的手机号】 注册会员的手机号码。该字段需要使用微信支付公钥加密(推荐),请参考获取微信支付公钥ID说明以及微信支付公钥加密敏感信息指引,也可以使用微信支付平台证书公钥加密,参考获取平台证书序列号、平台证书加密敏感信息指引。
level 选填 string(10)
【等级】 用户会员等级,展示字段,商家可以自定义填写内容。
valid_date_information 选填 object
【会员卡有效期】 会员卡有效期
属性 | |
user_information 选填 object
【用户开卡时填写的个人信息】 用户开卡时填写的个人信息
属性 | |
attach 选填 string(256)
【商家数据包】 商家在创建用户会员卡时可传入自定义数据包,该数据对用户不可见,用于存储商家自定义信息,其总长度限制在256字符以内。查询用户会员卡详情时会将此字段返回给商家。
user_card_confirm_state 必填 string
【会员开卡状态】 商家需要同步会员开卡状态
可选取值
CREATE_CARD_SUCCESS
: 开卡成功CREATE_CARD_FAIL
: 开卡失败
请求示例
POST
应答参数
200 OK
user_card_code 必填 string(32)
【会员卡code】 会员在一个会员卡模板下的唯一标识,用户领取会员卡后获得的code。只能填写数字/英文/半角标点。平台支持2种会员卡code分配类型:(1)SYSTEM_ALLOCATE 微信支付系统分配,用户领取会员卡时从微信系统分配24位数字作为会员code;(2)MERCHANT_ALLOCATE 商家分配,商家同步会员开通结果时传入,用户开卡成功或失败都以商家传入的code作为会员卡code。
card_id 必填 string(32)
【会员卡模板 ID】 商家创建会员卡模板成功后系统返回的会员卡模板ID
openid 必填 string(128)
【用户标识】 用户在品牌商家会员卡模板AppID下的唯一标识,获取方式详见参数说明。
card_color 选填 string(7)
【卡背景颜色】 用于卡片正面设计的RGB颜色编码,仅支持十六进制
card_picture_url 选填 string(256)
【卡图片】 商家自定义会员卡背景图。仅支持通过图片上传API接口获取的图片URL地址。支持JPG/JPEG/PNG格式,建议尺寸716px*320px,且图片小于1M。查看以下链接后传入:图片要求示例,图片上传API指引。
brand_id 必填 string(32)
【品牌ID】 商家进驻微信支付品牌商家后获得的品牌ID(灰度期间联系微信支付运营获取),用于标记该会员卡的归属方
card_type 必填 string
【会员卡类型】 支持付费、普通、储值 3 种类型。目前仅支持普通会员卡,填写付费和储值类型时会返回错误。
可选取值
PURCHASE
: 付费NORMAL
: 普通BALANCE
: 储值
phone_number 选填 string(512)
【加密的手机号】 注册会员的手机号码,仅在用户授权手机号、商家通过 API 传入的情况下有值。解密请参考如何使用API证书解密敏感字段。
level 选填 string(10)
【等级】 用户会员等级,展示字段,商家可以自定义填写内容。
valid_date_information 必填 object
【会员卡有效期】 会员卡有效期
属性 | |
pickup_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秒。
user_information 选填 object
【用户开卡时填写的个人信息】 用户开卡时填写的个人信息
属性 | |
attach 选填 string(256)
【商家数据包】 商家在创建用户会员卡时可传入自定义数据包,该数据对用户不可见,用于存储商家自定义信息,其总长度限制在256字符以内。查询用户会员卡详情时会将此字段返回给商家。
user_card_state 必填 string
【用户会员卡状态】 用户当前的卡状态
可选取值
UNACTIVATED
: 用户已领卡,但还未激活EFFECTIVE
: 用户的会员卡可正常使用EXPIRED
: 用户的会员卡已过期INVALID
: 用户的会员卡已失效
invalid_reason 选填 string(32)
【作废原因】 会员卡作废时传入的原因
invalid_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秒。
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 | 用户卡code 无效,只能包含数字、英文、半角标点 | 请修改用户卡code,确保其只包含数字、英文和半角标点 |
400 | PARAM_ERROR | 请求内容或图片不符合法规,请重试 | 请检查提交的内容或图片是否合规,修改后重试 |
404 | NOT_FOUND | 用户不存在未激活的会员卡 | 请确认该用户是否存在待激活的会员卡 |
400 | INVALID_REQUEST | 该用户卡 code 已存在 | 请更换用户卡code后重试 |
400 | INVALID_REQUEST | 会员卡号分配方式为系统分配,不允许修改会员卡号 | 请移除请求中的用户卡code字段,由系统自动分配 |
400 | INVALID_REQUEST | 用户卡状态不正确,只能操作已激活的会员卡 | 请检查用户会员卡状态,确保操作的是已激活的卡片 |
400 | INVALID_REQUEST | OpenID 不属于品牌的 AppID | 请检查OpenID是否属于品牌的AppID |
400 | INVALID_REQUEST | OpenID 无效 | 请检查并填写正确的OpenID |
404 | NOT_FOUND | 会员卡模板不存在 | 请检查会员卡模板ID是否正确,或创建新的会员卡模板 |
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 | 请求的用户信息通用字段未定义在卡模版中 | 请先在卡模板中定义需要获取的用户信息通用字段 |
400 | PARAM_ERROR | 用户信息通用字段中,生日格式不正确 | 请检查并使用正确的生日格式 |
400 | PARAM_ERROR | 用户信息通用字段中,邮箱格式不正确 | 请检查并使用正确的邮箱格式 |
400 | PARAM_ERROR | 用户信息通用字段中,性别格式不正确 | 请检查并使用正确的性别格式 |
400 | PARAM_ERROR | 请求的用户信息自定义字段未定义在卡模版中 | 请先在卡模板中定义需要获取的用户信息自定义字段 |