查询指定主体子商户列表

更新时间:2026.08.19
||

接口适用场景:收付通(平台)服务商可通过本接口,查询其名下指定主体的子商户列表。

1、通过organization_typecert_number定位主体。
2、仅返回属于指定主体、与当前服务商存在有效父子绑定关系且未注销的子商户。
3、支持limit/offset分页查询。

接口说明

支持商户:【平台商户】

请求方式:【GET】/v3/ecommerce/subject-sub-merchants

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

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

请求参数

Header  HTTP头参数

 Authorization  必填 string

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


 Accept  必填 string

请设置为application/json


 Wechatpay-Serial  必填 string

【微信支付公钥ID】或【微信支付平台证书序列号】  请求参数中的敏感字段,需要使用微信支付公钥加密(推荐),请参考获取微信支付公钥ID说明以及微信支付公钥加密敏感信息指引;也可以使用微信支付平台证书公钥加密,参考获取平台证书序列号平台证书加密敏感信息指引


query  查询参数

 organization_type  必填   string

【主体类型】 主体类型需与营业执照/登记证书上一致,可参考选择主体指引

可选取值

  • SUBJECT_TYPE_ENTERPRISE:  企业,营业执照上的主体类型一般为有限公司、有限责任公司

  • SUBJECT_TYPE_INSTITUTIONS_CLONED:  事业单位,包括国内各类事业单位,如:医疗、教育、学校等单位

  • SUBJECT_TYPE_INDIVIDUAL:  个体工商户,营业执照上的主体类型一般为个体户、个体工商户、个体经营

  • SUBJECT_TYPE_OTHERS:  社会组织,包括社会团体、民办非企业、基金会、基层群众性自治组织、农村集体经济组织等组织

  • SUBJECT_TYPE_GOVERNMENT:  政府机关,包括各级、各类政府机关,如机关党委、税务、民政、人社、工商、商务、市监等

  • SUBJECT_TYPE_MICRO:  小微商户或个人卖家,无营业执照、免办理工商注册登记的实体商户


 cert_number  必填   string(512)

【证件号码】 与主体类型对应的证件号码。
1、企业/个体工商户:营业执照上的注册号/统一社会信用代码。
2、小微/个人卖家:经营者身份证号码。
3、事业单位/政府机关/社会组织:登记证书上的编号。

该字段需要使用微信支付公钥加密(推荐),请参考获取微信支付公钥ID说明以及微信支付公钥加密敏感信息指引,也可以使用微信支付平台证书公钥加密,参考获取平台证书序列号平台证书加密敏感信息指引


 limit  选填   integer

【分页大小】 分页大小,最大不超过200。不传则默认值为20。该值需大于0。


 offset  选填   integer

【分页偏移】 该次请求的分页起始位置,从0开始计数。不传则默认值为0。

请求示例

curl
Java
Go

GET

1curl -X GET \
2  https://api.mch.weixin.qq.com/v3/ecommerce/subject-sub-merchants?organization_type=SUBJECT_TYPE_ENTERPRISE&cert_number=Iuas%2BxWj7ma0t%2Frcuy6eLqTBVkoxfc1vGVTjl4lqgPKinK24WHVnHao%2BJVp5xAJlvrkGPndf8LHOmroQ9qq44y2rUiPY7fEErV0zMh0vAKAG76M6yqcqQ9A1wOQ8l%2BIL7iQGAnd6SfqRMUsy8AU1nhzDwl7MUn2lBAPyFiR1LtJdc1ASagvSW3CP53iXyaVSkvVianWI6WUzb3xHv7HpEOSpaG3H9bhOjjdkbi8eaCudkbhXgF2f3QKfwO696j5DJTxN56r%2BomxtVfpgvi9B2fQOgDu7pZ%2FoqkkeTSyht%2BL8lL7T14%2FUj5T1m8fV9LOgjk2gGxziLjDgXCiX3jLXNw%3D%3D&limit=20&offset=0 \
3  -H "Authorization: WECHATPAY2-SHA256-RSA2048 mchid=\"1900000001\",..." \
4  -H "Accept: application/json" \
5  -H "Wechatpay-Serial: 5157F09EFDC096DE15EBE81A47057A7232F1B8E1"  
6

应答参数
折叠全部参数

200 OK

 data  必填   array[object]

【子商户列表】 子商户列表。若查询结果为空,则返回空数组。

属性

 sub_mchid  必填   string(32)

【子商户号】 属于指定主体、与当前服务商存在有效父子绑定关系且未注销的特约商户/二级商户号。


 merchant_shortname  必填   string(64)

【商户简称】 子商户简称。


 sign_time  必填   string(32)

【签约时间】 子商户签约完成时间,遵循rfc3339标准格式,如2018-06-08T10:34:56+08:00。若暂无签约时间则返回空字符串。


 offset  必填   integer

【分页偏移】 该次请求的分页起始位置,与请求参数一致。


 limit  必填   integer

【分页大小】 该次请求的分页大小,与请求参数一致(未传请求参数时为默认值)。


 total_count  必填   integer

【总条数】 符合条件的子商户总条数。

应答示例

200 OK

1{
2  "data" : [
3    {
4      "sub_mchid" : "1900000109",
5      "merchant_shortname" : "腾讯科技有限公司",
6      "sign_time" : "2018-06-08T10:34:56+08:00"
7    }
8  ],
9  "offset" : 0,
10  "limit" : 20,
11  "total_count" : 100
12}
13

 

错误码

以下是本接口返回的错误码列表。详细错误码规则,请参考微信支付接口规则-错误码和错误提示

状态码

错误码

描述

解决方案

400

PARAM_ERROR

参数错误

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

400

INVALID_REQUEST

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

请参阅 接口规则

401

SIGN_ERROR

验证不通过

请参阅 签名常见问题

500

SYSTEM_ERROR

系统异常,请稍后重试

请稍后重试

400

PARAM_ERROR

参数错误

请检查请求参数后重试

400

INVALID_REQUEST

仅支持平台收付通服务商调用

请使用已开通收付通能力的平台服务商商户号发起请求

404

NOT_FOUND

主体或商户不存在

请确认organization_type、cert_number与Authorization中的商户号是否正确

429

RATELIMIT_EXCEEDED

请求超过频率限制

请降低请求频率后重试

400

PARAM_ERROR

主体类型与入参不匹配

请确认organization_type与证件号对应主体类型一致

 

 

反馈
目录
置顶