进件子商户

更新时间：2025.01.07

机构提交子商户资料，微信支付系统会为每个子商户创建子商户号。

注意：

本接口请求的header需包含Idempotency-Key参数，它是一个由商户侧生成的唯一key，微信服务器使用该值来识别多次重试是否为同一请求，该字段长度64位，可包含字母和数字。

1. 接口说明

适用对象: 机构模式

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

请求方式: POST

Path 指该参数为路径参数

Query 指该参数为URL参数

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

2. 请求参数

参数名

变量

类型[长度限制]

必填

描述

机构appid

sp_appid

string[1,32]

是

Body 机构在微信公众平台申请服务号对应的APPID
注意：仅适用于机构模式
示例值：wx8888888888888888

机构商户号

sp_mchid

string[1,32]

是

Body 微信支付分配的机构商户号
注意：仅适用于机构模式
示例值：3200000001

商户名称

name

string[1,128]

是

Body 完整的商家实体名称必须与公司的官方注册文件（例如营业执照、公司注册证书、工商注册证等）中的注册名称完全相同。
示例值：Merchant name

子商户简称

shortname

string[1,64]

是

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

公司电话

office_phone

string[1,32]

是

Body 请指定客户服务电话号码。请使用电话号码前缀。前缀列表请参见附录。
示例值：+86075586010000

联系人信息

contact

object

是

Body 联系人信息，详细说明见

联系人信息

行业类目

business_category

int

是

Body 根据您的营业执照规定业务类别，请参考微信支付的商业类目列表
示例值：644

渠道号

channel_id

string[1,20]

否

Body 机构在微信商户管理后台创建的渠道号，如有渠道号请填写
示例值：3200000001

注册国家或区域

merchant_country_code

string[1,3]

是

Body 子商户公司注册的国家或区域，详见国家/地区代码
示例值：344

商户类型

merchant_type

string[1,10]

是

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

公司注册文件编号

registration_certificate_number

string[1,50]

是

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

公司注册文件过期时间

registration_certificate_date

string[1,10]

是

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

公司注册文件照片

registration_certificate_copy

string[1,128]

否

Body 请提供公司注册文件的复印件。如果商家是自然人（个人），请提供董事或负责人的身份证复印件。如果商家是独资经营者（个体户），请提供营业执照的复印件。取值为《上传图片API》返回的media ID。
示例值：w7yQFawBtja5uEdm_aoXokv2SDoEmHIPs

子商户银行结算账户信息

settlement_bank_number

string[1,128]

否

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

业务信息

business

object

是

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

业务信息

董事信息

director

object

是/否

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

董事信息

负责人信息

principal

object

是/否

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

负责人信息

是否申请H5支付权限

apply_h5_payment

boolean

否

是否为子商户申请H5支付权限。
需要申请H5支付权限时此字段为true。
示例值：true

H5支付申请资料资料

h5_payment_apply_info

object

是/否

Body H5申请资料，需要申请H5支付权限时填写。

H5支付申请资料资料

敏感字段加密说明：对于包含了敏感信息的参数，如联系方式等，我们增加了“字段加密”的安全机制，保护敏感信息只能被数据的接收方看到。

加密步骤：

1、获取微信支付平台证书和对应的平台证书序列号，获取微信支付平台证书。本接口请求http头的“Wechatpay-Serial”需要传平台证书序列号。

2、使用微信支付平台证书的公钥，对于需要加密的参数值进行RSA加密。Java语言的加密方法的填充方案使用 RSA/ECB/PKCS1Padding ;PHP填充方式为OPENSSL_PKCS1_PADDING。

3、加密后的密文，使用base64编码后，作为请求中相应参数的值。

请求示例

只进件子商户

1{
2		"sp_appid": "wx82ec4jy334ner1",
3		"sp_mchid": "2422128905",
4		"name": "Merchant name",
5		"shortname": "shortname",
6		"office_phone": "+86075586010000",
7		"contact": {
8			"email": "gP32/1QSaIpKlaFbWgP3hr8W3+YTtiavMRbOJJ6dATymJzxx/b4YPOTKdeRApW6Nt2ZZB9reZ1x45XhIEF/Ztb6mqfFVb6LxpJlHgDL/zpUG51551XQ3Ww+/kVCJcokiIiT1bSwEcCe6tPL2cmdsOEjlTikyrasLc1bG8vaG/i361r0vX9w56O2Mgv3OnJ4fr4xnmxNcVrJnk1f/gBSIiCUWA0163f3LM4KifQelEuz/WtroeKAzRDiI0/pOvXfwrYDK==",
9			"name": "Vxjsrod2RT2aGxeI5i+Z2C4arXYGXZuwE8IrRf6uYu6S5dy4Igw7kjvYWYCNfsgcdXyfjdA4KVntbgSa3zic+ERsOd5u+SNKkaFSH3SwYtpcCyaUMvICTw/6AOY/qy+He9la/gxObgi4zkxvLJmZTJVualTVJWWCIvcuDArW8Kfqp8rBl+IxDEgCojoEmqE7ymVReslGBXWiaPS1UsZx1QJyez3/ijzBa4AKch3XuPx6d3qvM+J8iMx/b94LAfpTihU/j==",
10			"phone": "l8JH2dAGLNJ8P5DENoMV0eW4JgIquV2ZO4conHnZp48g/eVpgvIfMj4Ge6LRVENW4eZksErJnYCQB+EOFEGR0lMhA1LexPLu0en08iM2ghkftYWAsOD4JPkvvc36SAfWal29eoZh4maO6kOGW7G4uBua6JoMsEjR6uuw5Gw5DC2eikcdkDBGk9vHSP/oxRs3Qu8a83GikhLgdpAPitXbZX/TEPG5SUg8Fx4BCMCKOfxy8uakq2/EeCtyBMjaiheUePoA=="
11		},
12		"business_category": 644,
13		"merchant_country_code": "344",
14		"merchant_type": "ENTERPRISE",
15		"registration_certificate_number": "519723407213085723",
16		"registration_certificate_date": "2022-06-03",
17		"settlement_bank_number": "559304578245298347923856",
18		"business": {
19			"business_type": "ONLINE",
20			"mcc": "5344",
21			"mini_program": "wx8888888888888888"
22		},
23		"director": {
24			"name": "Tom",
25			"number": "1234567890"
26	}
27}

进件子商户并申请H5支付权限

1{
2	  "sp_appid": "wx82ec4jy334ner1",
3	  "sp_mchid": "2422128905",
4	  "name": "Merchant name",
5	  "shortname": "Merchant shortname",
6	  "office_phone": "+86075586010000",
7	  "contact": {
8		"name": "yuhZiIh1C8x2UQ9FZY9ojV65HmpttQUSeOi3MdWy52ZoQUSpBUb52dJ+puGkzeGzjuXxJHbD0EGMDOfikdsAr7sqXhqfJexJKN7TSrwewbJqOEJ7fFjB3fqGVu6b/gfq6HduulBgaAlwZ5RcxpEVrAVM54mY3Z9HiX21fcqs65bti/QjEVCg0e1LlypKR3eqdW/XZi3q0gQ3hI0J9crA9OekIGc3M6OZ34aue5VdOd0PTCT99rIcI6N1VuapH2a7hY3fpgGAGxnYgNhUGsTgNoKso0pVCLEl0OlwvYCqmht3foyXtU/4WwwkpK8oFW1yQP3X7D1jXInEakWDFRAcUw==",
9		"phone": "XuafjSrgtiqsSzq4QdPEfrfspphyNnVSp9EKg9gM2/szy6ai+q5geSVE5VRRoQlVfiPYK/cFyTk009Cb8GDQilhL0X0HoxcBpcuRIaaW1+LOfMz0POAonG22yER/0486MhQrfNGaCb8QBTfeiIjZT2RPIpvTNyz6cESDV+Y1cD2JKOfK73MU3XKmgQz4mulb9sKdbNtGJV4wc03cR0Md/lnz9QnW5RulHu3bEwVRwtTSGJuMoZntkYhkn4KMRh/z93ri7wKd+DkIfIDMDTzvA2MUn4LW/PJtiKaNP5sOdpmpsw63kOsx5J32mTU7+0qz654MGayTFMW+fSgHBBNYVw==",
10		"email": "m+6RSfdEWSAZfrSfrP+FAPzh+jrFPQDPVCaslWwN3EdmsTliLvrUdcYnYuiILHpkZv1E6NNo592KOeznsDrKKWio00qfrurMhTAlneucHfU64yTvIsA6YqeBf8Uqfdad2BG0mYqbIn7AunnE2xqCoqS4W/lJPPROP7VU2/rFzkJx0KMInCo9FErktmN9nNQfhK5dpVis+YNv5SBQ7xSaVAUkTio4xNap1CWpVUIn8CjMgaSa7XJAOwNrNE6+ohU3pA/wlPALNIzYnNu/tktVYnuCm7yA+6wmCrzlWoIC68EgrzzaHZ6Yu59kvibfsMWerSkXRuYT9QNHN8Oe9MdcAQ=="
11	  },
12	  "business_category": 644,
13	  "merchant_country_code": "344",
14	  "merchant_type": "INDIVIDUAL",
15	  "registration_certificate_number": "5555-8888",
16	  "registration_certificate_date": "2025-08-27",
17	  "registration_certificate_copy": "w7yQFawBtja5uEdm_aoXokv2SDoEmHIPs",
18	  "business": {
19		"business_type": "BOTH",
20		"website": "http://www.qq.com",
21		"store_address": "shenzhen nanshan tencent",
22		"mcc": "5045"
23	  },
24	  "apply_h5_payment": true,
25	  "h5_payment_apply_info": {
26		"website_url": "http://www.qq.com",
27		"domains": ["www.qq.com", "www.wechat.com"]
28  }
29}

3. 返回参数

正常返回

参数名	变量	类型[长度限制]	必填	描述
子商户号	sub_mchid	string[1,32]	是	微信支付分配的子商户号注意：仅适用于机构模式示例值：1900000109
审核状态	verification_status	string[1,32]	是	描述子商户的审核状态： Under Review：微信支付审核中，子商户暂无交易权限，无法发起交易（需至微信支付商户平台查询子商户审核状态，审核通过后才可交易） Approved：微信支付审核通过，子商户可发起正常交易示例值：Under Review
验证状态描述	description	string[1,128]	否	审核状态描述。示例值：该子商户需要通过审核才可生效。请登录商户平台检查审核状态。
H5支付权限状态	h5_authorization_state	string[1, 32]	是	apply_h5_payment为YES时返回，描述子商户的H5支付权限状态： APPROVED：已有H5权限 UNAUTHORIZED：未获得H5权限，也未申请过H5权限 UNDER_REVIEW：H5权限申请当前在审核中 REJECTED：H5权限申请被驳回 UNDER_PUNISHMENT：曾经申请并获得H5权限，但当前权限被处罚，请联系BD处理； APPLICATION_FAILED：H5权限申请单创建失败示例值：APPROVED

异常返回

参数名

变量

类型[长度限制]

必填

描述

返回状态码

code

string[1, 32]

是

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

返回信息

message

string[1, 256]

是

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

详细的错误描述

detail

object

否

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

详细的错误描述

返回示例

SUCCESS（Approved）

1{
2	"sub_mchid": "20000100",
3	"verification_status": "Approved"
4}

SUCCESS（Under review）

1{
2	"sub_mchid": "20000100",
3	"verification_status": "Under Review",
4	"description": "This merchant takes effect only after being approved. Please check the verification status on WeChat Pay Merchant Platform."
5}

ERROR

1{
2	"code": "INVALID_REQUEST",
3	"message": "Parameter format verification error",
4	"detail": {
5		"field": "#/properties/payer",
6		"value": "1346177081915535577",
7		"issue": "与ALLOF schema不符",
8		"location": "body"
9	}
10}

进件子商户并申请H5支付权限

1{
2  "h5_authorization_state": "APPROVED",
3  "sub_mchid": "20000100",
4  "verification_status": "Approved"
5}

4. 错误码

错误码	描述	解决方案
PARAM_ERROR	请求参数未按指引进行填写	具体参数格式可以查看文档
SYSTEM_ERROR	后台系统返回错误	系统异常，请使用原参数重新发起
INVALID_REQUEST	商户系统异常导致，商户权限异常、重复请求支付、证书错误、频率限制、商户号不存在、appid和mchid不存在绑定关系、渠道号不对等	请根据接口返回的详细错误描述信息检查您的程序，具体可以查询detail 字段返回的详细信息
INVALID_REQUEST	没有api创建子商户的权限	请登录商户管理后台人工录入子商户信息
INVALID_REQUEST	商户唯一标识已经存在，请更换	针对不同的子商户，请定义唯一的标识
INVALID_REQUEST	商户被处罚，不允许申请开通H5支付权限。	商户支付权限被处罚，请先联系运营人员解除
INVALID_REQUEST	提交的H5经营网址或支付域名存在风险，请联系对接BD处理。	经营网址或者H5支付域名命中黑名单，请联系运营人员申请豁免