查询子商户

更新时间：2025.01.07

用于机构查询子商户创建是否成功，接口只提供单个子商户信息查询。

1. 接口说明

适用对象:机构模式

请求URL: https://apihk.mch.weixin.qq.com/v3/global/merchants/{sub_mchid}

请求方式: GET

Path 指该参数为路径参数

Query 指该参数为URL参数

Body 指该参数需在请求JSON传参

2. 请求参数

参数名	变量	类型[长度限制]	必填	描述
机构appid	sp_appid	string[1,32]	是	Query 机构在微信公众平台申请服务号对应的APPID 注意：仅适用于机构模式示例值：wx8888888888888888
机构商户号	sp_mchid	string[1,32]	是	Query 微信支付分配的机构商户号注意：仅适用于机构模式示例值：3200000001
子商户号	sub_mchid	string[1,32]	是	Path 子商户号示例值：20000100

请求示例

JSON

1https://apihk.mch.weixin.qq.com/v3/global/merchants/{20000100}?sp_appid=wx8888888888888888&sp_mchid=1900000100

3. 返回参数

正常返回

参数名

变量

类型[长度限制]

必填

描述

子商户号

sub_mchid

string(32)

是

微信支付分配的子商户号
示例值：20000100

子商户全称

name

string(128)

是

子商户公司注册的名称
示例值：Merchant name

子商户简称

shortname

string(64)

是

子商户简称，用于微信订单详情和支付成功页展示
示例值：Merchant shortname

公司联系方式

office_phone

string(32)

是

商户联系方式，用户支付完成后展示给用户的商家联系方式
示例值：075586010000

注册国家或区域

merchant_country_code

string(3)

是

子商户公司注册的国家或区域
示例值：344

类目

business_category

int

是

参考附录，详见商业类目列表
示例值：101

联系人信息

contact

object

是

联系人信息，详细说明见

联系人信息

商户类型

merchant_type

string[1,10]

是

取值ENTERPRISE或INDIVIDUAL
若商户为自然人或独资经营者，请选择INDIVIDUAL。
示例值：ENTERPRISE

公司注册文件编号

registration_certificate_number

string[1,50]

是

公司注册文件编号。
若商户为自然人，请提供董事或负责人的ID号。
若商户为独资经营者，请提供独资经营的业务资质证书编号。
示例值：5555-8888

公司注册文件过期时间

registration_certificate_date

string[1,10]

是

公司注册文件过期时间。
取值为过期的日期或取值为“PERMANENT”，“N/A”, 若取值为日期，格式为YYYY-MM-DD，比如2020-10-16。
若商户为自然人，请提供董事或负责人的ID号过期日期。
若商户为独资经营者，请提供独资经营的业务资质证书编号过期日期。
示例值：2020-10-16

子商户银行结算账户信息

settlement_bank_number

string[1,128]

否

子商户的结算银行账户信息
示例值：555588889999

业务信息

business

object

是

业务信息，具体请参考business对象列表

业务信息

董事信息

director

object

是/否

董事信息，当商户类型为ENTERPRISE必传，具体请参考director对象列表

董事信息

负责人信息

principal

object

是/否

负责人信息，当商户类型为INDIVIDUAL必传，具体请参考principal对象列表

负责人信息

H5支付权限详情

h5_payment

object

否

Body H5支付权限详情

H5支付权限详情

子商户状态信息

sub_merchant_state

object

否

Body 子商户状态信息

子商户状态信息

异常返回

参数名

变量

类型[长度限制]

必填

描述

返回状态码

code

string[1, 32]

是

错误码，枚举值见错误码列表
示例值：INVALID_REQUEST

返回信息

message

string[1, 256]

是

返回信息，如非空，为错误原因
示例值：参数格式校验错误

详细的错误描述

detail

object

否

当code为PARAM_ERROR时返回，详细说明见下

详细的错误描述

返回示例

子商户状态为OPERATING

1{
2  "sub_mchid": "20000100",
3  "name": "test mcherchan_name",
4  "shortname": "mcherchan_name",
5  "office_phone": "075586010000",
6  "merchant_introduction": "hotel and restaurant",
7  "business_category": 644,
8  "contact": {
9    "name": "Bob Zhang",
10    "phone": "+8613633334444"
11  },
12  "principal": {
13    "principal_name": "Bob",
14    "principal_id_number": "5555-8888"
15  },
16  "h5_payment": {
17    "h5_authorization_state": "APPROVED"
18  },
19  "sub_merchant_state": {
20      "sub_merchant_status": "OPERATING"
21  }
22}

子商户状态为INCOMPLETE_APPLICATION

1{
2  "sub_mchid": "20000100",
3  "name": "test mcherchan_name",
4  "shortname": "mcherchan_name",
5  "office_phone": "075586010000",
6  "merchant_introduction": "hotel and restaurant",
7  "business_category": 644,
8  "contact": {
9    "name": "Bob Zhang",
10    "phone": "+8613633334444"
11  },
12  "principal": {
13    "principal_name": "Bob",
14    "principal_id_number": "5555-8888"
15  },
16  "h5_payment": {
17    "h5_authorization_state": "UNDER_REVIEW"
18  },
19  "sub_merchant_state": {
20    "application_reject_detail": [
21      { "field": "name", "reason": "Merchant name is invalid." }
22    ],
23    "application_status": "REJECTED",
24    "sub_merchant_status": "INCOMPLETE_APPLICATION"
25  }
26}

4. 错误码

错误码	描述	解决方案
PARAM_ERROR	请求参数未按指引进行填写	具体参数格式可以查看文档
INVALID_REQUEST	商户系统异常导致，商户权限异常、重复请求支付、证书错误、频率限制、商户号不存在、appid和mchid不存在绑定关系、渠道号不对等	请根据接口返回的详细错误描述信息检查您的程序
SYSTEM_ERROR	后台系统返回错误	系统异常，请使用原参数重新发起