查询用户会员卡信息

更新时间:2025.06.22

通过此接口可查询指定用户会员卡的信息,如会员积分、储值余额、开卡信息等

接口说明

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

请求方式:【GET】/v3/brand/partner/card-member/user-cards/{user_card_code}

请求域名:【主域名】https://api.mch.weixin.qq.com 使用该域名将访问就近的接入点

     【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点 ,指引点击查看

请求参数

Header  HTTP头参数

 Authorization  必填 string

请参考签名认证生成认证信息


 Accept  必填 string

请设置为application/json


path  路径参数

 user_card_code  必填   string(32)

【会员卡code】 会员在一个会员卡模版下的唯一标识,用户领取会员卡后获得的code。只能填写数字/英文/半角标点。


query  查询参数

 brand_id  必填   string(32)

【品牌ID】 商家进驻微信支付品牌商家后获得的品牌ID(灰度期间联系微信支付运营获取),用于标记该会员卡的归属方


 card_id  必填   string(32)

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


 openid  必填   string(128)

【用户标识】 用户在品牌商家会员卡模板AppID下的唯一标识

请求示例

Java
Go
curl

需配合微信支付工具库 WXPayUtility 使用,请参考 Java 

1package com.java.demo;
2
3import com.java.utils.WXPayUtility; // 引用微信支付工具库,参考:https://pay.weixin.qq.com/doc/v3/partner/4014985777
4
5import com.google.gson.annotations.SerializedName;
6import com.google.gson.annotations.Expose;
7import okhttp3.MediaType;
8import okhttp3.OkHttpClient;
9import okhttp3.Request;
10import okhttp3.RequestBody;
11import okhttp3.Response;
12
13import java.io.IOException;
14import java.io.UncheckedIOException;
15import java.security.PrivateKey;
16import java.security.PublicKey;
17import java.util.ArrayList;
18import java.util.HashMap;
19import java.util.List;
20import java.util.Map;
21
22/**
23 * 查询用户会员卡信息
24 */
25public class GetUserCard {
26  private static String HOST = "https://api.mch.weixin.qq.com";
27  private static String METHOD = "GET";
28  private static String PATH = "/v3/brand/partner/card-member/user-cards/{user_card_code}";
29
30  public static void main(String[] args) {
31    // TODO: 请准备商户开发必要参数,参考:https://pay.weixin.qq.com/doc/v3/partner/4013080340
32    GetUserCard client = new GetUserCard(
33      "19xxxxxxxx",                    // 商户号,是由微信支付系统生成并分配给每个商户的唯一标识符,商户号获取方式参考 https://pay.weixin.qq.com/doc/v3/partner/4013080340
34      "1DDE55AD98Exxxxxxxxxx",         // 商户API证书序列号,如何获取请参考 https://pay.weixin.qq.com/doc/v3/partner/4013058924
35      "/path/to/apiclient_key.pem",    // 商户API证书私钥文件路径,本地文件路径
36      "PUB_KEY_ID_xxxxxxxxxxxxx",      // 微信支付公钥ID,如何获取请参考 https://pay.weixin.qq.com/doc/v3/partner/4013038589
37      "/path/to/wxp_pub.pem"           // 微信支付公钥文件路径,本地文件路径
38    );
39
40    GetUserCardRequest request = new GetUserCardRequest();
41    request.userCardCode = "478515832665";
42    request.brandId = "1004";
43    request.cardId = "pbLatjvWOibDc5-TBnbUk1pD12o0";
44    request.openid = "obLatjnx9gnqzS4myYGmLZ7LgLBA";
45    try {
46      UserCard response = client.run(request);
47
48      // TODO: 请求成功,继续业务逻辑
49      System.out.println(response);
50    } catch (WXPayUtility.ApiException e) {
51      // TODO: 请求失败,根据状态码执行不同的逻辑
52      e.printStackTrace();
53    }
54  }
55
56  public UserCard run(GetUserCardRequest request) {
57    String uri = PATH;
58    uri = uri.replace("{user_card_code}", WXPayUtility.urlEncode(request.userCardCode));
59    Map<String, Object> args = new HashMap<>();
60    args.put("brand_id", request.brandId);
61    args.put("card_id", request.cardId);
62    args.put("openid", request.openid);
63    uri = uri + "?" + WXPayUtility.urlEncode(args);
64
65    Request.Builder reqBuilder = new Request.Builder().url(HOST + uri);
66    reqBuilder.addHeader("Accept", "application/json");
67    reqBuilder.addHeader("Wechatpay-Serial", wechatPayPublicKeyId);
68    reqBuilder.addHeader("Authorization", WXPayUtility.buildAuthorization(mchid, certificateSerialNo, privateKey, METHOD, uri, null));
69    reqBuilder.method(METHOD, null);
70    Request httpRequest = reqBuilder.build();
71
72    // 发送HTTP请求
73    OkHttpClient client = new OkHttpClient.Builder().build();
74    try (Response httpResponse = client.newCall(httpRequest).execute()) {
75      String respBody = WXPayUtility.extractBody(httpResponse);
76      if (httpResponse.code() >= 200 && httpResponse.code() < 300) {
77        // 2XX 成功,验证应答签名
78        WXPayUtility.validateResponse(this.wechatPayPublicKeyId, this.wechatPayPublicKey,
79            httpResponse.headers(), respBody);
80
81        // 从HTTP应答报文构建返回数据
82        return WXPayUtility.fromJson(respBody, UserCard.class);
83      } else {
84        throw new WXPayUtility.ApiException(httpResponse.code(), respBody, httpResponse.headers());
85      }
86    } catch (IOException e) {
87      throw new UncheckedIOException("Sending request to " + uri + " failed.", e);
88    }
89  }
90
91  private final String mchid;
92  private final String certificateSerialNo;
93  private final PrivateKey privateKey;
94  private final String wechatPayPublicKeyId;
95  private final PublicKey wechatPayPublicKey;
96
97  public GetUserCard(String mchid, String certificateSerialNo, String privateKeyFilePath, String wechatPayPublicKeyId, String wechatPayPublicKeyFilePath) {
98    this.mchid = mchid;
99    this.certificateSerialNo = certificateSerialNo;
100    this.privateKey = WXPayUtility.loadPrivateKeyFromPath(privateKeyFilePath);
101    this.wechatPayPublicKeyId = wechatPayPublicKeyId;
102    this.wechatPayPublicKey = WXPayUtility.loadPublicKeyFromPath(wechatPayPublicKeyFilePath);
103  }
104
105  public static class GetUserCardRequest {
106    @SerializedName("brand_id")
107    @Expose(serialize = false)
108    public String brandId;
109  
110    @SerializedName("card_id")
111    @Expose(serialize = false)
112    public String cardId;
113  
114    @SerializedName("user_card_code")
115    @Expose(serialize = false)
116    public String userCardCode;
117  
118    @SerializedName("openid")
119    @Expose(serialize = false)
120    public String openid;
121  }
122  
123  public static class UserCard {
124    @SerializedName("user_card_code")
125    public String userCardCode;
126  
127    @SerializedName("card_id")
128    public String cardId;
129  
130    @SerializedName("openid")
131    public String openid;
132  
133    @SerializedName("card_color")
134    public String cardColor;
135  
136    @SerializedName("card_picture_url")
137    public String cardPictureUrl;
138  
139    @SerializedName("brand_id")
140    public String brandId;
141  
142    @SerializedName("card_type")
143    public CardType cardType;
144  
145    @SerializedName("phone_number")
146    public String phoneNumber;
147  
148    @SerializedName("level")
149    public String level;
150  
151    @SerializedName("valid_date_information")
152    public DateInfo validDateInformation;
153  
154    @SerializedName("pickup_time")
155    public String pickupTime;
156  
157    @SerializedName("user_information")
158    public UserInfo userInformation;
159  
160    @SerializedName("attach")
161    public String attach;
162  
163    @SerializedName("user_card_state")
164    public UserCardState userCardState;
165  
166    @SerializedName("invalid_reason")
167    public String invalidReason;
168  
169    @SerializedName("invalid_time")
170    public String invalidTime;
171  
172    @SerializedName("create_time")
173    public String createTime;
174  
175    @SerializedName("modify_time")
176    public String modifyTime;
177  }
178  
179  public enum CardType {
180    @SerializedName("PURCHASE")
181    PURCHASE,
182    @SerializedName("NORMAL")
183    NORMAL,
184    @SerializedName("BALANCE")
185    BALANCE
186  }
187  
188  public static class DateInfo {
189    @SerializedName("type")
190    public DateType type;
191  
192    @SerializedName("available_begin_time")
193    public String availableBeginTime;
194  
195    @SerializedName("available_end_time")
196    public String availableEndTime;
197  
198    @SerializedName("available_day_after_receive")
199    public Long availableDayAfterReceive;
200  }
201  
202  public static class UserInfo {
203    @SerializedName("common_field_list")
204    public List<UserInfoCommonField> commonFieldList;
205  
206    @SerializedName("custom_field_list")
207    public List<UserInfoCustomField> customFieldList;
208  }
209  
210  public enum UserCardState {
211    @SerializedName("UNACTIVATED")
212    UNACTIVATED,
213    @SerializedName("EFFECTIVE")
214    EFFECTIVE,
215    @SerializedName("EXPIRED")
216    EXPIRED,
217    @SerializedName("INVALID")
218    INVALID
219  }
220  
221  public enum DateType {
222    @SerializedName("FIX_TIME_RANGE")
223    FIX_TIME_RANGE,
224    @SerializedName("FIX_TERM")
225    FIX_TERM,
226    @SerializedName("PERMANENT")
227    PERMANENT
228  }
229  
230  public static class UserInfoCommonField {
231    @SerializedName("name")
232    public CommonFieldFlag name;
233  
234    @SerializedName("value")
235    public String value;
236  }
237  
238  public static class UserInfoCustomField {
239    @SerializedName("name")
240    public String name;
241  
242    @SerializedName("user_chosen_values")
243    public List<String> userChosenValues;
244  }
245  
246  public enum CommonFieldFlag {
247    @SerializedName("USER_FORM_FLAG_SEX")
248    USER_FORM_FLAG_SEX,
249    @SerializedName("USER_FORM_FLAG_NAME")
250    USER_FORM_FLAG_NAME,
251    @SerializedName("USER_FORM_FLAG_BIRTHDAY")
252    USER_FORM_FLAG_BIRTHDAY,
253    @SerializedName("USER_FORM_FLAG_ADDRESS")
254    USER_FORM_FLAG_ADDRESS,
255    @SerializedName("USER_FORM_FLAG_EMAIL")
256    USER_FORM_FLAG_EMAIL,
257    @SerializedName("USER_FORM_FLAG_CITY")
258    USER_FORM_FLAG_CITY
259  }
260  
261}
262

应答参数

200 OK

 user_card_code  必填   string(32)

【会员卡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

INVALID_REQUEST

会员卡模版ID不属于该品牌

请确认品牌ID和会员卡模版ID是否正确

404

NOT_FOUND

用户会员卡信息不存在

请确认品牌ID、会员卡模版ID、会员卡code是否正确

 

反馈
咨询
目录
置顶