发起门店主体匹配

更新时间:2025.05.09

发起门店主体匹配。该接口允许服务商批量查询门店主体是否已在微信支付开通相关支付产品,匹配结果可用于后续企业支付业务的开展。企业可通过此接口确认合作门店的支付能力,提前了解是否可以使用企业支付功能进行消费。

接口说明

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

请求方式:【POST】/v3/webizpay/stores/entity-matches

请求域名:【主域名】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  包体参数

 sp_mchid  必填   string(32)

【服务商商户号】 是由微信支付系统生成并分配给每个服务商的唯一标识符,具体请参考服务商模式开发必要参数说明


 out_batch_id  必填   string(32)

【商户主体匹配批次单号】 商户主体匹配批次单号,要求6-32个字符内,只能是数字、大小写字母_-|* 且在同一个商户号下唯一。


 match_details  选填   array[object]

【主体匹配明细列表】 主体匹配明细列表

属性

请求示例

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 InitiateEntityMatch {
26  private static String HOST = "https://api.mch.weixin.qq.com";
27  private static String METHOD = "POST";
28  private static String PATH = "/v3/webizpay/stores/entity-matches";
29
30  public static void main(String[] args) {
31    // TODO: 请准备商户开发必要参数,参考:https://pay.weixin.qq.com/doc/v3/partner/4013080340
32    InitiateEntityMatch client = new InitiateEntityMatch(
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    StoreInitiateEntityMatchRequest request = new StoreInitiateEntityMatchRequest();
41    request.spMchid = "12341234";
42    request.outBatchId = "batch12345678";
43    request.matchDetails = new ArrayList<>();
44    {
45      EntityMatchDetail matchDetailsItem = new EntityMatchDetail();
46      matchDetailsItem.organizationCode = "91110000710926094P";
47      matchDetailsItem.storeName = "微信小店";
48      matchDetailsItem.productType = ProductType.CODE_PAY;
49      request.matchDetails.add(matchDetailsItem);
50    };
51    try {
52      StoreInitiateEntityMatchResponse response = client.run(request);
53
54      // TODO: 请求成功,继续业务逻辑
55      System.out.println(response);
56    } catch (WXPayUtility.ApiException e) {
57      // TODO: 请求失败,根据状态码执行不同的逻辑
58      e.printStackTrace();
59    }
60  }
61
62  public StoreInitiateEntityMatchResponse run(StoreInitiateEntityMatchRequest request) {
63    String uri = PATH;
64    String reqBody = WXPayUtility.toJson(request);
65
66    Request.Builder reqBuilder = new Request.Builder().url(HOST + uri);
67    reqBuilder.addHeader("Accept", "application/json");
68    reqBuilder.addHeader("Wechatpay-Serial", wechatPayPublicKeyId);
69    reqBuilder.addHeader("Authorization", WXPayUtility.buildAuthorization(mchid, certificateSerialNo,privateKey, METHOD, uri, reqBody));
70    reqBuilder.addHeader("Content-Type", "application/json");
71    RequestBody requestBody = RequestBody.create(MediaType.parse("application/json; charset=utf-8"), reqBody);
72    reqBuilder.method(METHOD, requestBody);
73    Request httpRequest = reqBuilder.build();
74
75    // 发送HTTP请求
76    OkHttpClient client = new OkHttpClient.Builder().build();
77    try (Response httpResponse = client.newCall(httpRequest).execute()) {
78      String respBody = WXPayUtility.extractBody(httpResponse);
79      if (httpResponse.code() >= 200 && httpResponse.code() < 300) {
80        // 2XX 成功,验证应答签名
81        WXPayUtility.validateResponse(this.wechatPayPublicKeyId, this.wechatPayPublicKey,
82            httpResponse.headers(), respBody);
83
84        // 从HTTP应答报文构建返回数据
85        return WXPayUtility.fromJson(respBody, StoreInitiateEntityMatchResponse.class);
86      } else {
87        throw new WXPayUtility.ApiException(httpResponse.code(), respBody, httpResponse.headers());
88      }
89    } catch (IOException e) {
90      throw new UncheckedIOException("Sending request to " + uri + " failed.", e);
91    }
92  }
93
94  private final String mchid;
95  private final String certificateSerialNo;
96  private final PrivateKey privateKey;
97  private final String wechatPayPublicKeyId;
98  private final PublicKey wechatPayPublicKey;
99
100  public InitiateEntityMatch(String mchid, String certificateSerialNo, String privateKeyFilePath, String wechatPayPublicKeyId, String wechatPayPublicKeyFilePath) {
101    this.mchid = mchid;
102    this.certificateSerialNo = certificateSerialNo;
103    this.privateKey = WXPayUtility.loadPrivateKeyFromPath(privateKeyFilePath);
104    this.wechatPayPublicKeyId = wechatPayPublicKeyId;
105    this.wechatPayPublicKey = WXPayUtility.loadPublicKeyFromPath(wechatPayPublicKeyFilePath);
106  }
107
108  public static class StoreInitiateEntityMatchRequest {
109    @SerializedName("sp_mchid")
110    public String spMchid;
111  
112    @SerializedName("out_batch_id")
113    public String outBatchId;
114  
115    @SerializedName("match_details")
116    public List<EntityMatchDetail> matchDetails;
117  }
118  
119  public static class StoreInitiateEntityMatchResponse {
120    @SerializedName("sp_mchid")
121    public String spMchid;
122  
123    @SerializedName("out_batch_id")
124    public String outBatchId;
125  
126    @SerializedName("batch_id")
127    public String batchId;
128  
129    @SerializedName("time")
130    public String time;
131  
132    @SerializedName("state")
133    public BatchState state;
134  }
135  
136  public static class EntityMatchDetail {
137    @SerializedName("organization_code")
138    public String organizationCode;
139  
140    @SerializedName("store_name")
141    public String storeName;
142  
143    @SerializedName("product_type")
144    public ProductType productType;
145  }
146  
147  public enum BatchState {
148    @SerializedName("ACCEPTED")
149    ACCEPTED,
150    @SerializedName("IN_PROGRESS")
151    IN_PROGRESS,
152    @SerializedName("COMPLETED")
153    COMPLETED,
154    @SerializedName("CLOSED")
155    CLOSED
156  }
157  
158  public enum ProductType {
159    @SerializedName("CODE_PAY")
160    CODE_PAY,
161    @SerializedName("NONE")
162    NONE
163  }
164  
165}
166

应答参数

200 OK

 sp_mchid  必填   string(32)

【服务商商户号】 服务商商户号,商户请求时传入


 out_batch_id  必填   string(32)

【商户主体匹配批次单号】 商户主体匹配批次单号,由商户发起门店信息匹配时传入


 batch_id  必填   string(32)

【微信支付主体匹配批次单号】 微信支付主体匹配批次单号,标记某一次响应商户主体匹配信息对应的处理单号,在微信支付体系下唯一。


 time  必填   string

【批次创建时间】 批次创建时间,微信支付处理完成此批次的时间。
遵循rfc3339标准格式:yyyy-MM-DDTHH:mm:ss+TIMEZONEyyyy-MM-DD 表示年月日;T 字符用于分隔日期和时间部分;HH:mm:ss 表示具体的时分秒;TIMEZONE 表示时区(例如,+08:00 对应东八区时间,即北京时间)。

示例:2015-05-20T13:29:35+08:00 表示北京时间2015年5月20日13点29分35秒。


 state  必填   string

【批次状态】 批次状态:已受理ACCEPTED、处理中IN_PROGRESS、已完成COMPLETED、已关闭CLOSED

可选取值

  • ACCEPTED:  已受理

  • IN_PROGRESS:  处理中

  • COMPLETED:  已完成

  • CLOSED:  已关闭

应答示例

200 OK

1{
2  "sp_mchid" : "12341234",
3  "out_batch_id" : "batch12345678",
4  "batch_id" : "1030000071201xxxxx",
5  "time" : "2023-06-08T10:34:56+08:00",
6  "state" : "ACCEPTED"
7}
8

 

错误码

公共错误码

状态码

错误码

描述

解决方案

400

PARAM_ERROR

参数错误

请根据错误提示正确传入参数

400

INVALID_REQUEST

HTTP 请求不符合微信支付 APIv3 接口规则

请参阅 接口规则

401

SIGN_ERROR

验证不通过

请参阅 签名常见问题

500

SYSTEM_ERROR

系统异常,请稍后重试

请稍后重试

 

 

更多技术问题
技术咨询
反馈
咨询
目录
置顶