同步会员开通结果

更新时间: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:  开卡失败

请求示例

curl
Java
Go

POST

1curl -X POST \
2  https://api.mch.weixin.qq.com/v3/brand/partner/card-member/user-cards/478515832665/confirm?card_id=pbLatjvWOibDc5-TBnbUk1pD12o0 \
3  -H "Authorization: WECHATPAY2-SHA256-RSA2048 mchid=\"1900000001\",..." \
4  -H "Accept: application/json" \
5  -H "Wechatpay-Serial: 5157F09EFDC096DE15EBE81A47057A7232F1B8E1"  \
6  -H "Content-Type: application/json" \
7  -d '{
8    "brand_id" : "1004",
9    "openid" : "obLatjnx9gnqzS4myYGmLZ7LgLBA",
10    "card_color" : "#FFFF00",
11    "card_picture_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/PiajxSqBRaEIPAeia7Imvtsn7sYGNcEj33YzVvJF88ECQ19LXId8ZL2Q/0",
12    "phone_number" : "vvysDQeEaH3I+wRh14St0abIkvQyFgh/fbWYSs2bLtG9tj+bdJn4WSCPzLhShNHgujZzseiL6sYmT7E65mv/eFeTa7yslYfrX0hrhHazSM/+tfvN/C3OZwiBbcrF9LTIIdBVhGOqhCx0gK5YAVZc8dbW/yJqC5i79PDfVYJtpQe3A4v/GiDa2Q+Mv03taxgnEkzqlSPjkXiCYBj9UaFJ4bqCTXiO2Kt6TpczvAaZW+9/blxiJwqEFXe78LbrIQvkDUmVdZbqBdPQ+QGQgc/2Ea4IbP/EEt1qSyXnFbzaaKSE2j4mAFON3kzNexb/SYkHZNJAuCittaW4wpGj7U+h9A==",
13    "level" : "钻石会员",
14    "valid_date_information" : {
15      "type" : "PERMANENT",
16      "available_begin_time" : "2020-05-20T13:29:35.120+08:00",
17      "available_end_time" : "2020-05-20T13:29:35.120+08:00",
18      "available_day_after_receive" : 30
19    },
20    "user_information" : {
21      "common_field_list" : [
22        {
23          "name" : "USER_FORM_FLAG_BIRTHDAY",
24          "value" : "vvysDQeEaH3I+wRh14St0abIkvQyFgh/fbWYSs2bLtG9tj+bdJn4WSCPzLhShNHgujZzseiL6sYmT7E65mv/eFeTa7yslYfrX0hrhHazSM/+tfvN/C3OZwiBbcrF9LTIIdBVhGOqhCx0gK5YAVZc8dbW/yJqC5i79PDfVYJtpQe3A4v/GiDa2Q+Mv03taxgnEkzqlSPjkXiCYBj9UaFJ4bqCTXiO2Kt6TpczvAaZW+9/blxiJwqEFXe78LbrIQvkDUmVdZbqBdPQ+QGQgc/2Ea4IbP/EEt1qSyXnFbzaaKSE2j4mAFON3kzNexb/SYkHZNJAuCittaW4wpGj7U+h9A=="
25        }
26      ],
27      "custom_field_list" : [
28        {
29          "name" : "喜欢的运动",
30          "user_chosen_values" : [
31            "vvysDQeEaH3I+wRh14St0abIkvQyFgh/fbWYSs2bLtG9tj+bdJn4WSCPzLhShNHgujZzseiL6sYmT7E65mv/eFeTa7yslYfrX0hrhHazSM/+tfvN/C3OZwiBbcrF9LTIIdBVhGOqhCx0gK5YAVZc8dbW/yJqC5i79PDfVYJtpQe3A4v/GiDa2Q+Mv03taxgnEkzqlSPjkXiCYBj9UaFJ4bqCTXiO2Kt6TpczvAaZW+9/blxiJwqEFXe78LbrIQvkDUmVdZbqBdPQ+QGQgc/2Ea4IbP/EEt1qSyXnFbzaaKSE2j4mAFON3kzNexb/SYkHZNJAuCittaW4wpGj7U+h9A=="
32          ]
33        }
34      ]
35    },
36    "attach" : "自定义数据说明",
37    "user_card_confirm_state" : "CREATE_CARD_SUCCESS"
38  }'
39

应答参数

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

1{
2  "user_card_code" : "478515832665",
3  "card_id" : "pbLatjvWOibDc5-TBnbUk1pD12o0",
4  "openid" : "obLatjnx9gnqzS4myYGmLZ7LgLBA",
5  "card_color" : "#FFFF00",
6  "card_picture_url" : "https://wxpaylogo.qpic.cn/wxpaylogo/PiajxSqBRaEIPAeia7Imvtsn7sYGNcEj33YzVvJF88ECQ19LXId8ZL2Q/0",
7  "brand_id" : "1001622624",
8  "card_type" : "NORMAL",
9  "phone_number" : "vvysDQeEaH3I+wRh14St0abIkvQyFgh/fbWYSs2bLtG9tj+bdJn4WSCPzLhShNHgujZzseiL6sYmT7E65mv/eFeTa7yslYfrX0hrhHazSM/+tfvN/C3OZwiBbcrF9LTIIdBVhGOqhCx0gK5YAVZc8dbW/yJqC5i79PDfVYJtpQe3A4v/GiDa2Q+Mv03taxgnEkzqlSPjkXiCYBj9UaFJ4bqCTXiO2Kt6TpczvAaZW+9/blxiJwqEFXe78LbrIQvkDUmVdZbqBdPQ+QGQgc/2Ea4IbP/EEt1qSyXnFbzaaKSE2j4mAFON3kzNexb/SYkHZNJAuCittaW4wpGj7U+h9A==",
10  "level" : "钻石会员",
11  "valid_date_information" : {
12    "type" : "PERMANENT",
13    "available_begin_time" : "2020-05-20T13:29:35.120+08:00",
14    "available_end_time" : "2020-05-20T13:29:35.120+08:00",
15    "available_day_after_receive" : 30
16  },
17  "pickup_time" : "2020-05-20T13:29:35.120+08:00",
18  "user_information" : {
19    "common_field_list" : [
20      {
21        "name" : "USER_FORM_FLAG_BIRTHDAY",
22        "value" : "vvysDQeEaH3I+wRh14St0abIkvQyFgh/fbWYSs2bLtG9tj+bdJn4WSCPzLhShNHgujZzseiL6sYmT7E65mv/eFeTa7yslYfrX0hrhHazSM/+tfvN/C3OZwiBbcrF9LTIIdBVhGOqhCx0gK5YAVZc8dbW/yJqC5i79PDfVYJtpQe3A4v/GiDa2Q+Mv03taxgnEkzqlSPjkXiCYBj9UaFJ4bqCTXiO2Kt6TpczvAaZW+9/blxiJwqEFXe78LbrIQvkDUmVdZbqBdPQ+QGQgc/2Ea4IbP/EEt1qSyXnFbzaaKSE2j4mAFON3kzNexb/SYkHZNJAuCittaW4wpGj7U+h9A=="
23      }
24    ],
25    "custom_field_list" : [
26      {
27        "name" : "喜欢的运动",
28        "user_chosen_values" : [
29          "vvysDQeEaH3I+wRh14St0abIkvQyFgh/fbWYSs2bLtG9tj+bdJn4WSCPzLhShNHgujZzseiL6sYmT7E65mv/eFeTa7yslYfrX0hrhHazSM/+tfvN/C3OZwiBbcrF9LTIIdBVhGOqhCx0gK5YAVZc8dbW/yJqC5i79PDfVYJtpQe3A4v/GiDa2Q+Mv03taxgnEkzqlSPjkXiCYBj9UaFJ4bqCTXiO2Kt6TpczvAaZW+9/blxiJwqEFXe78LbrIQvkDUmVdZbqBdPQ+QGQgc/2Ea4IbP/EEt1qSyXnFbzaaKSE2j4mAFON3kzNexb/SYkHZNJAuCittaW4wpGj7U+h9A=="
30        ]
31      }
32    ]
33  },
34  "attach" : "自定义数据说明",
35  "user_card_state" : "EFFECTIVE",
36  "invalid_reason" : "传入的自定义作废原因",
37  "invalid_time" : "2020-05-20T13:29:35.120+08:00",
38  "create_time" : "2020-05-20T13:29:35.120+08:00",
39  "modify_time" : "2020-05-20T13:29:35.120+08:00"
40}
41

 

错误码

公共错误码

状态码

错误码

描述

解决方案

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

请求的用户信息自定义字段未定义在卡模版中

请先在卡模板中定义需要获取的用户信息自定义字段

 

反馈
咨询
目录
置顶