查询品牌门店
更新时间:2025.08.04根据品牌门店ID,查询品牌门店。
接口说明
支持商户:【普通服务商】
请求方式:【GET】/v3/brand/partner/store/brandstores/{store_id}
请求域名:【主域名】https://api.mch.weixin.qq.com 使用该域名将访问就近的接入点
【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点 ,指引点击查看
请求参数
Header HTTP头参数
Authorization 必填 string
请参考签名认证生成认证信息
Accept 必填 string
请设置为application/json
path 路径参数
store_id 必填 string
【品牌门店ID】 创建品牌门店后,系统为该门店分配的唯一ID。
query 查询参数
brand_id 必填 string
【品牌ID】 商家进驻微信支付品牌商家后获得的品牌ID。
请求示例
需配合微信支付工具库 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 GetBrandStore { 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/store/brandstores/{store_id}"; 29 30 public static void main(String[] args) { 31 // TODO: 请准备商户开发必要参数,参考:https://pay.weixin.qq.com/doc/v3/partner/4013080340 32 GetBrandStore client = new GetBrandStore( 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 GetBrandStoreRequest request = new GetBrandStoreRequest(); 41 request.storeId = "1234567890123456"; 42 request.brandId = "123456789"; 43 try { 44 BrandStoresEntity response = client.run(request); 45 46 // TODO: 请求成功,继续业务逻辑 47 System.out.println(response); 48 } catch (WXPayUtility.ApiException e) { 49 // TODO: 请求失败,根据状态码执行不同的逻辑 50 e.printStackTrace(); 51 } 52 } 53 54 public BrandStoresEntity run(GetBrandStoreRequest request) { 55 String uri = PATH; 56 uri = uri.replace("{store_id}", WXPayUtility.urlEncode(request.storeId)); 57 Map<String, Object> args = new HashMap<>(); 58 args.put("brand_id", request.brandId); 59 uri = uri + "?" + WXPayUtility.urlEncode(args); 60 61 Request.Builder reqBuilder = new Request.Builder().url(HOST + uri); 62 reqBuilder.addHeader("Accept", "application/json"); 63 reqBuilder.addHeader("Wechatpay-Serial", wechatPayPublicKeyId); 64 reqBuilder.addHeader("Authorization", WXPayUtility.buildAuthorization(mchid, certificateSerialNo, privateKey, METHOD, uri, null)); 65 reqBuilder.method(METHOD, null); 66 Request httpRequest = reqBuilder.build(); 67 68 // 发送HTTP请求 69 OkHttpClient client = new OkHttpClient.Builder().build(); 70 try (Response httpResponse = client.newCall(httpRequest).execute()) { 71 String respBody = WXPayUtility.extractBody(httpResponse); 72 if (httpResponse.code() >= 200 && httpResponse.code() < 300) { 73 // 2XX 成功,验证应答签名 74 WXPayUtility.validateResponse(this.wechatPayPublicKeyId, this.wechatPayPublicKey, 75 httpResponse.headers(), respBody); 76 77 // 从HTTP应答报文构建返回数据 78 return WXPayUtility.fromJson(respBody, BrandStoresEntity.class); 79 } else { 80 throw new WXPayUtility.ApiException(httpResponse.code(), respBody, httpResponse.headers()); 81 } 82 } catch (IOException e) { 83 throw new UncheckedIOException("Sending request to " + uri + " failed.", e); 84 } 85 } 86 87 private final String mchid; 88 private final String certificateSerialNo; 89 private final PrivateKey privateKey; 90 private final String wechatPayPublicKeyId; 91 private final PublicKey wechatPayPublicKey; 92 93 public GetBrandStore(String mchid, String certificateSerialNo, String privateKeyFilePath, String wechatPayPublicKeyId, String wechatPayPublicKeyFilePath) { 94 this.mchid = mchid; 95 this.certificateSerialNo = certificateSerialNo; 96 this.privateKey = WXPayUtility.loadPrivateKeyFromPath(privateKeyFilePath); 97 this.wechatPayPublicKeyId = wechatPayPublicKeyId; 98 this.wechatPayPublicKey = WXPayUtility.loadPublicKeyFromPath(wechatPayPublicKeyFilePath); 99 } 100 101 public static class GetBrandStoreRequest { 102 @SerializedName("brand_id") 103 @Expose(serialize = false) 104 public String brandId; 105 106 @SerializedName("store_id") 107 @Expose(serialize = false) 108 public String storeId; 109 } 110 111 public static class BrandStoresEntity { 112 @SerializedName("brand_id") 113 public String brandId; 114 115 @SerializedName("store_id") 116 public String storeId; 117 118 @SerializedName("store_state") 119 public StoreState storeState; 120 121 @SerializedName("audit_state") 122 public AuditState auditState; 123 124 @SerializedName("review_reject_reason") 125 public String reviewRejectReason; 126 127 @SerializedName("store_basics") 128 public StoreBase storeBasics; 129 130 @SerializedName("store_address") 131 public StoreLocation storeAddress; 132 133 @SerializedName("store_business") 134 public StoreBusiness storeBusiness; 135 136 @SerializedName("store_recipient") 137 public List<StoreRecipient> storeRecipient; 138 } 139 140 public enum StoreState { 141 @SerializedName("OPEN") 142 OPEN, 143 @SerializedName("CREATING") 144 CREATING, 145 @SerializedName("CLOSED") 146 CLOSED 147 } 148 149 public enum AuditState { 150 @SerializedName("SUCCESS") 151 SUCCESS, 152 @SerializedName("PROCESSING") 153 PROCESSING, 154 @SerializedName("REJECTED") 155 REJECTED 156 } 157 158 public static class StoreBase { 159 @SerializedName("store_reference_id") 160 public String storeReferenceId; 161 162 @SerializedName("branch_name") 163 public String branchName; 164 } 165 166 public static class StoreLocation { 167 @SerializedName("address_code") 168 public String addressCode; 169 170 @SerializedName("address_detail") 171 public String addressDetail; 172 173 @SerializedName("address_complements") 174 public String addressComplements; 175 176 @SerializedName("longitude") 177 public String longitude; 178 179 @SerializedName("latitude") 180 public String latitude; 181 } 182 183 public static class StoreBusiness { 184 @SerializedName("service_phone") 185 public String servicePhone; 186 187 @SerializedName("business_hours") 188 public String businessHours; 189 } 190 191 public static class StoreRecipient { 192 @SerializedName("mchid") 193 public String mchid; 194 195 @SerializedName("company_name") 196 public String companyName; 197 198 @SerializedName("recipient_state") 199 public RecipientState recipientState; 200 } 201 202 public enum RecipientState { 203 @SerializedName("CONFIRMED") 204 CONFIRMED, 205 @SerializedName("ADMIN_REJECTED") 206 ADMIN_REJECTED, 207 @SerializedName("CONFIRMING") 208 CONFIRMING, 209 @SerializedName("TIMEOUT_REJECTED") 210 TIMEOUT_REJECTED 211 } 212 213} 214
需配合微信支付工具库 wxpay_utility 使用,请参考 Go
1package main 2 3import ( 4 "demo/wxpay_utility" // 引用微信支付工具库,参考 https://pay.weixin.qq.com/doc/v3/partner/4015119446 5 "encoding/json" 6 "fmt" 7 "net/http" 8 "net/url" 9 "strings" 10) 11 12func main() { 13 // TODO: 请准备商户开发必要参数,参考:https://pay.weixin.qq.com/doc/v3/partner/4013080340 14 config, err := wxpay_utility.CreateMchConfig( 15 "19xxxxxxxx", // 商户号,是由微信支付系统生成并分配给每个商户的唯一标识符,商户号获取方式参考 https://pay.weixin.qq.com/doc/v3/partner/4013080340 16 "1DDE55AD98Exxxxxxxxxx", // 商户API证书序列号,如何获取请参考 https://pay.weixin.qq.com/doc/v3/partner/4013058924 17 "/path/to/apiclient_key.pem", // 商户API证书私钥文件路径,本地文件路径 18 "PUB_KEY_ID_xxxxxxxxxxxxx", // 微信支付公钥ID,如何获取请参考 https://pay.weixin.qq.com/doc/v3/partner/4013038589 19 "/path/to/wxp_pub.pem", // 微信支付公钥文件路径,本地文件路径 20 ) 21 if err != nil { 22 fmt.Println(err) 23 return 24 } 25 26 request := &GetBrandStoreRequest{ 27 BrandId: wxpay_utility.String("123456789"), 28 StoreId: wxpay_utility.String("1234567890123456"), 29 } 30 31 response, err := GetBrandStore(config, request) 32 if err != nil { 33 fmt.Printf("请求失败: %+v\n", err) 34 // TODO: 请求失败,根据状态码执行不同的处理 35 return 36 } 37 38 // TODO: 请求成功,继续业务逻辑 39 fmt.Printf("请求成功: %+v\n", response) 40} 41 42func GetBrandStore(config *wxpay_utility.MchConfig, request *GetBrandStoreRequest) (response *BrandStoresEntity, err error) { 43 const ( 44 host = "https://api.mch.weixin.qq.com" 45 method = "GET" 46 path = "/v3/brand/partner/store/brandstores/{store_id}" 47 ) 48 49 reqUrl, err := url.Parse(fmt.Sprintf("%s%s", host, path)) 50 if err != nil { 51 return nil, err 52 } 53 reqUrl.Path = strings.Replace(reqUrl.Path, "{store_id}", url.PathEscape(*request.StoreId), -1) 54 query := reqUrl.Query() 55 query.Add("brand_id", *request.BrandId) 56 reqUrl.RawQuery = query.Encode() 57 httpRequest, err := http.NewRequest(method, reqUrl.String(), nil) 58 if err != nil { 59 return nil, err 60 } 61 httpRequest.Header.Set("Accept", "application/json") 62 httpRequest.Header.Set("Wechatpay-Serial", config.WechatPayPublicKeyId()) 63 authorization, err := wxpay_utility.BuildAuthorization(config.MchId(), config.CertificateSerialNo(), config.PrivateKey(), method, reqUrl.RequestURI(), nil) 64 if err != nil { 65 return nil, err 66 } 67 httpRequest.Header.Set("Authorization", authorization) 68 69 client := &http.Client{} 70 httpResponse, err := client.Do(httpRequest) 71 if err != nil { 72 return nil, err 73 } 74 75 respBody, err := wxpay_utility.ExtractResponseBody(httpResponse) 76 if err != nil { 77 return nil, err 78 } 79 80 if httpResponse.StatusCode >= 200 && httpResponse.StatusCode < 300 { 81 // 2XX 成功,验证应答签名 82 err = wxpay_utility.ValidateResponse( 83 config.WechatPayPublicKeyId(), 84 config.WechatPayPublicKey(), 85 &httpResponse.Header, 86 respBody, 87 ) 88 if err != nil { 89 return nil, err 90 } 91 92 response := &BrandStoresEntity{} 93 if err := json.Unmarshal(respBody, response); err != nil { 94 return nil, err 95 } 96 97 return response, nil 98 } else { 99 return nil, wxpay_utility.NewApiException( 100 httpResponse.StatusCode, 101 httpResponse.Header, 102 respBody, 103 ) 104 } 105} 106 107type GetBrandStoreRequest struct { 108 BrandId *string `json:"brand_id,omitempty"` 109 StoreId *string `json:"store_id,omitempty"` 110} 111 112func (o *GetBrandStoreRequest) MarshalJSON() ([]byte, error) { 113 type Alias GetBrandStoreRequest 114 a := &struct { 115 BrandId *string `json:"brand_id,omitempty"` 116 StoreId *string `json:"store_id,omitempty"` 117 *Alias 118 }{ 119 // 序列化时移除非 Body 字段 120 BrandId: nil, 121 StoreId: nil, 122 Alias: (*Alias)(o), 123 } 124 return json.Marshal(a) 125} 126 127type BrandStoresEntity struct { 128 BrandId *string `json:"brand_id,omitempty"` 129 StoreId *string `json:"store_id,omitempty"` 130 StoreState *StoreState `json:"store_state,omitempty"` 131 AuditState *AuditState `json:"audit_state,omitempty"` 132 ReviewRejectReason *string `json:"review_reject_reason,omitempty"` 133 StoreBasics *StoreBase `json:"store_basics,omitempty"` 134 StoreAddress *StoreLocation `json:"store_address,omitempty"` 135 StoreBusiness *StoreBusiness `json:"store_business,omitempty"` 136 StoreRecipient []StoreRecipient `json:"store_recipient,omitempty"` 137} 138 139type StoreState string 140 141func (e StoreState) Ptr() *StoreState { 142 return &e 143} 144 145const ( 146 STORESTATE_OPEN StoreState = "OPEN" 147 STORESTATE_CREATING StoreState = "CREATING" 148 STORESTATE_CLOSED StoreState = "CLOSED" 149) 150 151type AuditState string 152 153func (e AuditState) Ptr() *AuditState { 154 return &e 155} 156 157const ( 158 AUDITSTATE_SUCCESS AuditState = "SUCCESS" 159 AUDITSTATE_PROCESSING AuditState = "PROCESSING" 160 AUDITSTATE_REJECTED AuditState = "REJECTED" 161) 162 163type StoreBase struct { 164 StoreReferenceId *string `json:"store_reference_id,omitempty"` 165 BranchName *string `json:"branch_name,omitempty"` 166} 167 168type StoreLocation struct { 169 AddressCode *string `json:"address_code,omitempty"` 170 AddressDetail *string `json:"address_detail,omitempty"` 171 AddressComplements *string `json:"address_complements,omitempty"` 172 Longitude *string `json:"longitude,omitempty"` 173 Latitude *string `json:"latitude,omitempty"` 174} 175 176type StoreBusiness struct { 177 ServicePhone *string `json:"service_phone,omitempty"` 178 BusinessHours *string `json:"business_hours,omitempty"` 179} 180 181type StoreRecipient struct { 182 Mchid *string `json:"mchid,omitempty"` 183 CompanyName *string `json:"company_name,omitempty"` 184 RecipientState *RecipientState `json:"recipient_state,omitempty"` 185} 186 187type RecipientState string 188 189func (e RecipientState) Ptr() *RecipientState { 190 return &e 191} 192 193const ( 194 RECIPIENTSTATE_CONFIRMED RecipientState = "CONFIRMED" 195 RECIPIENTSTATE_ADMIN_REJECTED RecipientState = "ADMIN_REJECTED" 196 RECIPIENTSTATE_CONFIRMING RecipientState = "CONFIRMING" 197 RECIPIENTSTATE_TIMEOUT_REJECTED RecipientState = "TIMEOUT_REJECTED" 198) 199
GET
1curl -X GET \ 2 https://api.mch.weixin.qq.com/v3/brand/partner/store/brandstores/1234567890123456?brand_id=123456789 \ 3 -H "Authorization: WECHATPAY2-SHA256-RSA2048 mchid=\"1900000001\",..." \ 4 -H "Accept: application/json" 5
应答参数
200 OK
brand_id 必填 string
【品牌ID】 商家进驻微信支付品牌商家后获得的品牌ID。
store_id 选填 string
【品牌门店ID】 创建品牌门店后,系统为该门店分配的唯一ID。
store_state 选填 string
【门店状态】 用于描述门店当前状态
可选取值
OPEN
: 门店营业中。CREATING
: 门店创建中。在创建门店后,门店资料正在审核。审核详情请查看审核状态。CLOSED
: 门店已停业。不可用于微信支付生态中的其他业务,可删除该门店,删除后将无法恢复,请谨慎操作。
audit_state 选填 string
【审核状态】 创建、修改门店时,通过此字段可得知当前审核状态
可选取值
SUCCESS
: 门店资料审核通过PROCESSING
: 门店资料审核中REJECTED
: 门店资料被驳回,请根据驳回原因进行修改。
review_reject_reason 选填 string
【审核失败原因】 门店资料审核失败的原因
store_basics 选填 object
【门店基础信息】 用于描述门店编码,名称等基本情况。
属性 | |
store_reference_id 选填 string(32) 【商家门店编号】 商家内部的门店编号,最长32位字符;商家自行保证该编码在商家内部的唯一性。不允许有符号表情。 branch_name 选填 string(20) 【门店名称】 只需填写纯粹的分店名称,例如:"南山店"、"朝阳门店"、"天河城店"
|
store_address 选填 object
【门店地址信息】 用于描述门店地址,经纬度等地理位置相关情况。
属性 | |
address_code 必填 string(20) 【门店省市编码】 门店所在省市区编码,只能由数字组成;详细参见微信支付提供的省市对照表。 address_detail 必填 string(100) 【门店地址】 门店地址为核心重要信息,请准确填写并精确到门牌号,该信息涉及到地址核实、营销活动等业务,说明:不要重复填写省市区信息。地址长度在4-100个字符。 address_complements 选填 string(50) 【门店地址辅助描述】 门店周围标志性建筑,用于辅助定位。 longitude 选填 string(32) 【门店经度】 经度,取值在[-180,180]之间的数字,经度长度不能超过32个字符,腾讯地图经纬度查询:https://lbs.qq.com/tool/getpoint/index.html latitude 选填 string(32) 【门店纬度】 纬度,取值在[-90,90]之间的数字,纬度长度不能超过32个字符,腾讯地图经纬度查询:https://lbs.qq.com/tool/getpoint/index.html |
store_business 选填 object
【门店经营信息】 用于描述门店联系电话,经营时间等经营状况。
属性 | |
service_phone 选填 string(32) 【门店服务电话】 支持座机和手机,只支持数字和“-”符号,最多支持两个电话,两个电话间用分号“|”区隔。 business_hours 选填 string(256) 【门店经营时间】 请严格按"周一至周五 09:00-20:00|周六至周日 10:00-22:00"的格式进行填写,时间段不能重复,最多支持两个时间段,两个时间段间用英文分号“|”区隔 |
store_recipient 选填 array[object]
【门店收款信息】 门店收款商户列表。
属性 | |
mchid 选填 string(16) 【门店收款商户号】 门店的收款商户号,仅支持绑定品牌已关联的商户号。 company_name 选填 string(256) 【门店收款主体】 门店收款的主体信息,支持企业,个体户,小微。 recipient_state 选填 string 【收款绑定状态】 门店收款商户号的绑定状态 可选取值
|
应答示例
200 OK
1{ 2 "brand_id" : "123456789", 3 "store_id" : "1234567890123456", 4 "store_state" : "OPEN", 5 "audit_state" : "SUCCESS", 6 "review_reject_reason" : "通过核实,您提交的电话错误,请核实手机号码或座机号码是否正确", 7 "store_basics" : { 8 "store_reference_id" : "MDL001", 9 "branch_name" : "海岸城店" 10 }, 11 "store_address" : { 12 "address_code" : "440305", 13 "address_detail" : "深南大道10000号腾讯大厦1楼", 14 "address_complements" : "地铁A口右侧100米", 15 "longitude" : "112.63484", 16 "latitude" : "37.75464" 17 }, 18 "store_business" : { 19 "service_phone" : "0755-86013388", 20 "business_hours" : "周一至周五 09:00-20:00" 21 }, 22 "store_recipient" : [ 23 { 24 "mchid" : "1230000109", 25 "company_name" : "腾讯科技(深圳)有限公司", 26 "recipient_state" : "CONFIRMED" 27 } 28 ] 29} 30
错误码
公共错误码