创建品牌门店
更新时间:2025.08.04填入品牌门店资料,并创建门店。
接口说明
支持商户:【普通服务商】
请求方式:【POST】/v3/brand/partner/store/brandstores
请求域名:【主域名】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
body 包体参数
brand_id 必填 string
【品牌ID】 商家进驻微信支付品牌商家后获得的品牌ID。
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"的格式进行填写,时间段不能重复,最多支持两个时间段,两个时间段间用英文分号“|”区隔 |
请求示例
需配合微信支付工具库 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 CreateBrandStore { 26 private static String HOST = "https://api.mch.weixin.qq.com"; 27 private static String METHOD = "POST"; 28 private static String PATH = "/v3/brand/partner/store/brandstores"; 29 30 public static void main(String[] args) { 31 // TODO: 请准备商户开发必要参数,参考:https://pay.weixin.qq.com/doc/v3/partner/4013080340 32 CreateBrandStore client = new CreateBrandStore( 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 BrandStoresCreateRequest request = new BrandStoresCreateRequest(); 41 request.brandId = "123456789"; 42 request.storeBasics = new StoreBase(); 43 request.storeBasics.storeReferenceId = "MDL001"; 44 request.storeBasics.branchName = "海岸城店"; 45 request.storeAddress = new StoreLocation(); 46 request.storeAddress.addressCode = "440305"; 47 request.storeAddress.addressDetail = "深南大道10000号腾讯大厦1楼"; 48 request.storeAddress.addressComplements = "地铁A口右侧100米"; 49 request.storeAddress.longitude = "112.63484"; 50 request.storeAddress.latitude = "37.75464"; 51 request.storeBusiness = new StoreBusiness(); 52 request.storeBusiness.servicePhone = "0755-86013388"; 53 request.storeBusiness.businessHours = "周一至周五 09:00-20:00"; 54 try { 55 BrandStoresEntity response = client.run(request); 56 57 // TODO: 请求成功,继续业务逻辑 58 System.out.println(response); 59 } catch (WXPayUtility.ApiException e) { 60 // TODO: 请求失败,根据状态码执行不同的逻辑 61 e.printStackTrace(); 62 } 63 } 64 65 public BrandStoresEntity run(BrandStoresCreateRequest request) { 66 String uri = PATH; 67 String reqBody = WXPayUtility.toJson(request); 68 69 Request.Builder reqBuilder = new Request.Builder().url(HOST + uri); 70 reqBuilder.addHeader("Accept", "application/json"); 71 reqBuilder.addHeader("Wechatpay-Serial", wechatPayPublicKeyId); 72 reqBuilder.addHeader("Authorization", WXPayUtility.buildAuthorization(mchid, certificateSerialNo,privateKey, METHOD, uri, reqBody)); 73 reqBuilder.addHeader("Content-Type", "application/json"); 74 RequestBody requestBody = RequestBody.create(MediaType.parse("application/json; charset=utf-8"), reqBody); 75 reqBuilder.method(METHOD, requestBody); 76 Request httpRequest = reqBuilder.build(); 77 78 // 发送HTTP请求 79 OkHttpClient client = new OkHttpClient.Builder().build(); 80 try (Response httpResponse = client.newCall(httpRequest).execute()) { 81 String respBody = WXPayUtility.extractBody(httpResponse); 82 if (httpResponse.code() >= 200 && httpResponse.code() < 300) { 83 // 2XX 成功,验证应答签名 84 WXPayUtility.validateResponse(this.wechatPayPublicKeyId, this.wechatPayPublicKey, 85 httpResponse.headers(), respBody); 86 87 // 从HTTP应答报文构建返回数据 88 return WXPayUtility.fromJson(respBody, BrandStoresEntity.class); 89 } else { 90 throw new WXPayUtility.ApiException(httpResponse.code(), respBody, httpResponse.headers()); 91 } 92 } catch (IOException e) { 93 throw new UncheckedIOException("Sending request to " + uri + " failed.", e); 94 } 95 } 96 97 private final String mchid; 98 private final String certificateSerialNo; 99 private final PrivateKey privateKey; 100 private final String wechatPayPublicKeyId; 101 private final PublicKey wechatPayPublicKey; 102 103 public CreateBrandStore(String mchid, String certificateSerialNo, String privateKeyFilePath, String wechatPayPublicKeyId, String wechatPayPublicKeyFilePath) { 104 this.mchid = mchid; 105 this.certificateSerialNo = certificateSerialNo; 106 this.privateKey = WXPayUtility.loadPrivateKeyFromPath(privateKeyFilePath); 107 this.wechatPayPublicKeyId = wechatPayPublicKeyId; 108 this.wechatPayPublicKey = WXPayUtility.loadPublicKeyFromPath(wechatPayPublicKeyFilePath); 109 } 110 111 public static class BrandStoresCreateRequest { 112 @SerializedName("brand_id") 113 public String brandId; 114 115 @SerializedName("store_basics") 116 public StoreBase storeBasics; 117 118 @SerializedName("store_address") 119 public StoreLocation storeAddress; 120 121 @SerializedName("store_business") 122 public StoreBusiness storeBusiness; 123 } 124 125 public static class BrandStoresEntity { 126 @SerializedName("brand_id") 127 public String brandId; 128 129 @SerializedName("store_id") 130 public String storeId; 131 132 @SerializedName("store_state") 133 public StoreState storeState; 134 135 @SerializedName("audit_state") 136 public AuditState auditState; 137 138 @SerializedName("review_reject_reason") 139 public String reviewRejectReason; 140 141 @SerializedName("store_basics") 142 public StoreBase storeBasics; 143 144 @SerializedName("store_address") 145 public StoreLocation storeAddress; 146 147 @SerializedName("store_business") 148 public StoreBusiness storeBusiness; 149 150 @SerializedName("store_recipient") 151 public List<StoreRecipient> storeRecipient; 152 } 153 154 public static class StoreBase { 155 @SerializedName("store_reference_id") 156 public String storeReferenceId; 157 158 @SerializedName("branch_name") 159 public String branchName; 160 } 161 162 public static class StoreLocation { 163 @SerializedName("address_code") 164 public String addressCode; 165 166 @SerializedName("address_detail") 167 public String addressDetail; 168 169 @SerializedName("address_complements") 170 public String addressComplements; 171 172 @SerializedName("longitude") 173 public String longitude; 174 175 @SerializedName("latitude") 176 public String latitude; 177 } 178 179 public static class StoreBusiness { 180 @SerializedName("service_phone") 181 public String servicePhone; 182 183 @SerializedName("business_hours") 184 public String businessHours; 185 } 186 187 public enum StoreState { 188 @SerializedName("OPEN") 189 OPEN, 190 @SerializedName("CREATING") 191 CREATING, 192 @SerializedName("CLOSED") 193 CLOSED 194 } 195 196 public enum AuditState { 197 @SerializedName("SUCCESS") 198 SUCCESS, 199 @SerializedName("PROCESSING") 200 PROCESSING, 201 @SerializedName("REJECTED") 202 REJECTED 203 } 204 205 public static class StoreRecipient { 206 @SerializedName("mchid") 207 public String mchid; 208 209 @SerializedName("company_name") 210 public String companyName; 211 212 @SerializedName("recipient_state") 213 public RecipientState recipientState; 214 } 215 216 public enum RecipientState { 217 @SerializedName("CONFIRMED") 218 CONFIRMED, 219 @SerializedName("ADMIN_REJECTED") 220 ADMIN_REJECTED, 221 @SerializedName("CONFIRMING") 222 CONFIRMING, 223 @SerializedName("TIMEOUT_REJECTED") 224 TIMEOUT_REJECTED 225 } 226 227} 228
需配合微信支付工具库 wxpay_utility 使用,请参考 Go
1package main 2 3import ( 4 "bytes" 5 "demo/wxpay_utility" // 引用微信支付工具库,参考 https://pay.weixin.qq.com/doc/v3/partner/4015119446 6 "encoding/json" 7 "fmt" 8 "net/http" 9 "net/url" 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 := &BrandStoresCreateRequest{ 27 BrandId: wxpay_utility.String("123456789"), 28 StoreBasics: &StoreBase{ 29 StoreReferenceId: wxpay_utility.String("MDL001"), 30 BranchName: wxpay_utility.String("海岸城店"), 31 }, 32 StoreAddress: &StoreLocation{ 33 AddressCode: wxpay_utility.String("440305"), 34 AddressDetail: wxpay_utility.String("深南大道10000号腾讯大厦1楼"), 35 AddressComplements: wxpay_utility.String("地铁A口右侧100米"), 36 Longitude: wxpay_utility.String("112.63484"), 37 Latitude: wxpay_utility.String("37.75464"), 38 }, 39 StoreBusiness: &StoreBusiness{ 40 ServicePhone: wxpay_utility.String("0755-86013388"), 41 BusinessHours: wxpay_utility.String("周一至周五 09:00-20:00"), 42 }, 43 } 44 45 response, err := CreateBrandStore(config, request) 46 if err != nil { 47 fmt.Printf("请求失败: %+v\n", err) 48 // TODO: 请求失败,根据状态码执行不同的处理 49 return 50 } 51 52 // TODO: 请求成功,继续业务逻辑 53 fmt.Printf("请求成功: %+v\n", response) 54} 55 56func CreateBrandStore(config *wxpay_utility.MchConfig, request *BrandStoresCreateRequest) (response *BrandStoresEntity, err error) { 57 const ( 58 host = "https://api.mch.weixin.qq.com" 59 method = "POST" 60 path = "/v3/brand/partner/store/brandstores" 61 ) 62 63 reqUrl, err := url.Parse(fmt.Sprintf("%s%s", host, path)) 64 if err != nil { 65 return nil, err 66 } 67 reqBody, err := json.Marshal(request) 68 if err != nil { 69 return nil, err 70 } 71 httpRequest, err := http.NewRequest(method, reqUrl.String(), bytes.NewReader(reqBody)) 72 if err != nil { 73 return nil, err 74 } 75 httpRequest.Header.Set("Accept", "application/json") 76 httpRequest.Header.Set("Wechatpay-Serial", config.WechatPayPublicKeyId()) 77 httpRequest.Header.Set("Content-Type", "application/json") 78 authorization, err := wxpay_utility.BuildAuthorization(config.MchId(), config.CertificateSerialNo(), config.PrivateKey(), method, reqUrl.RequestURI(), reqBody) 79 if err != nil { 80 return nil, err 81 } 82 httpRequest.Header.Set("Authorization", authorization) 83 84 client := &http.Client{} 85 httpResponse, err := client.Do(httpRequest) 86 if err != nil { 87 return nil, err 88 } 89 90 respBody, err := wxpay_utility.ExtractResponseBody(httpResponse) 91 if err != nil { 92 return nil, err 93 } 94 95 if httpResponse.StatusCode >= 200 && httpResponse.StatusCode < 300 { 96 // 2XX 成功,验证应答签名 97 err = wxpay_utility.ValidateResponse( 98 config.WechatPayPublicKeyId(), 99 config.WechatPayPublicKey(), 100 &httpResponse.Header, 101 respBody, 102 ) 103 if err != nil { 104 return nil, err 105 } 106 107 response := &BrandStoresEntity{} 108 if err := json.Unmarshal(respBody, response); err != nil { 109 return nil, err 110 } 111 112 return response, nil 113 } else { 114 return nil, wxpay_utility.NewApiException( 115 httpResponse.StatusCode, 116 httpResponse.Header, 117 respBody, 118 ) 119 } 120} 121 122type BrandStoresCreateRequest struct { 123 BrandId *string `json:"brand_id,omitempty"` 124 StoreBasics *StoreBase `json:"store_basics,omitempty"` 125 StoreAddress *StoreLocation `json:"store_address,omitempty"` 126 StoreBusiness *StoreBusiness `json:"store_business,omitempty"` 127} 128 129type BrandStoresEntity struct { 130 BrandId *string `json:"brand_id,omitempty"` 131 StoreId *string `json:"store_id,omitempty"` 132 StoreState *StoreState `json:"store_state,omitempty"` 133 AuditState *AuditState `json:"audit_state,omitempty"` 134 ReviewRejectReason *string `json:"review_reject_reason,omitempty"` 135 StoreBasics *StoreBase `json:"store_basics,omitempty"` 136 StoreAddress *StoreLocation `json:"store_address,omitempty"` 137 StoreBusiness *StoreBusiness `json:"store_business,omitempty"` 138 StoreRecipient []StoreRecipient `json:"store_recipient,omitempty"` 139} 140 141type StoreBase struct { 142 StoreReferenceId *string `json:"store_reference_id,omitempty"` 143 BranchName *string `json:"branch_name,omitempty"` 144} 145 146type StoreLocation struct { 147 AddressCode *string `json:"address_code,omitempty"` 148 AddressDetail *string `json:"address_detail,omitempty"` 149 AddressComplements *string `json:"address_complements,omitempty"` 150 Longitude *string `json:"longitude,omitempty"` 151 Latitude *string `json:"latitude,omitempty"` 152} 153 154type StoreBusiness struct { 155 ServicePhone *string `json:"service_phone,omitempty"` 156 BusinessHours *string `json:"business_hours,omitempty"` 157} 158 159type StoreState string 160 161func (e StoreState) Ptr() *StoreState { 162 return &e 163} 164 165const ( 166 STORESTATE_OPEN StoreState = "OPEN" 167 STORESTATE_CREATING StoreState = "CREATING" 168 STORESTATE_CLOSED StoreState = "CLOSED" 169) 170 171type AuditState string 172 173func (e AuditState) Ptr() *AuditState { 174 return &e 175} 176 177const ( 178 AUDITSTATE_SUCCESS AuditState = "SUCCESS" 179 AUDITSTATE_PROCESSING AuditState = "PROCESSING" 180 AUDITSTATE_REJECTED AuditState = "REJECTED" 181) 182 183type StoreRecipient struct { 184 Mchid *string `json:"mchid,omitempty"` 185 CompanyName *string `json:"company_name,omitempty"` 186 RecipientState *RecipientState `json:"recipient_state,omitempty"` 187} 188 189type RecipientState string 190 191func (e RecipientState) Ptr() *RecipientState { 192 return &e 193} 194 195const ( 196 RECIPIENTSTATE_CONFIRMED RecipientState = "CONFIRMED" 197 RECIPIENTSTATE_ADMIN_REJECTED RecipientState = "ADMIN_REJECTED" 198 RECIPIENTSTATE_CONFIRMING RecipientState = "CONFIRMING" 199 RECIPIENTSTATE_TIMEOUT_REJECTED RecipientState = "TIMEOUT_REJECTED" 200) 201
POST
1curl -X POST \ 2 https://api.mch.weixin.qq.com/v3/brand/partner/store/brandstores \ 3 -H "Authorization: WECHATPAY2-SHA256-RSA2048 mchid=\"1900000001\",..." \ 4 -H "Accept: application/json" \ 5 -H "Content-Type: application/json" \ 6 -d '{ 7 "brand_id" : "123456789", 8 "store_basics" : { 9 "store_reference_id" : "MDL001", 10 "branch_name" : "海岸城店" 11 }, 12 "store_address" : { 13 "address_code" : "440305", 14 "address_detail" : "深南大道10000号腾讯大厦1楼", 15 "address_complements" : "地铁A口右侧100米", 16 "longitude" : "112.63484", 17 "latitude" : "37.75464" 18 }, 19 "store_business" : { 20 "service_phone" : "0755-86013388", 21 "business_hours" : "周一至周五 09:00-20:00" 22 } 23 }' 24
应答参数
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
错误码
公共错误码