适用对象:机构模式
请求URL: https://api.mch.weixin.qq.com/secapi/mch/addInstitutionsub
请求方式: POST
是否需要证书: 是
| 参数名 | 变量 | 类型 | 必填 | 描述 |
|---|---|---|---|---|
| 机构appid | app_id | string(32) | 是 | 机构在微信公众平台申请服务号对应的APPID 示例值：wx8888888888888888 |
| 机构商户号 | mch_id | string(32) | 是 | 微信支付分配的机构商户号 示例值：3200000001 |
| 签名 | sign | string(32) | 是 | 参数签名。详见签名方法 注意：默认加密方式为MD5，且仅支持MD5加密 详见签名方法示例值：C380BEC2BFD727A4B6845133519F3AD6 |
| 渠道编号 | channel_id | string(20) | 否 | 机构合作渠道的编号，通过商户平台创建 示例值：101 |
| 商户名称 | merchant_name | string(128) | 是 | 完整的商家实体名称必须与公司的官方注册文件（例如营业执照、公司注册证书、工商注册证等）中的注册名称完全相同。 示例值：Merchant name |
| 子商户简称 | merchant_shortname | string(64) | 是 | 子商户简称，用于微信订单详情和支付成功页展示 示例值：Merchant shortname |
| 子商户唯一标识 | merchant_remark | string(20) | 是 | 机构为商户备注的信息，可以是商户在机构系统的商户编号 示例值：ABC123456 |
| 注册国家或区域 | merchant_country_code | string(3) | 是 | 公司所注册的国家或区域，详见国家/地区代码 示例值：344 |
| 商户类型 | merchant_type | string(10) | 是 | 取值ENTERPRISE或INDIVIDUAL 若商户为自然人或独资经营者，请选择INDIVIDUAL。 示例值：ENTERPRISE |
| 行业类目 | business_category | string（3） | 是 | 根据您的营业执照规定业务类别，请参考微信支付的业务类目列表 示例值：644 |
| MCC码 | mcc | string(4) | 是 | Mcc码，请参考商户行业编码 示例值：4214 |
| 公司注册文件编号 | registration_certificate_number | string(50) | 是 | 公司注册文件编号。 若商户为自然人，请提供董事或负责人的ID号。 若商户为独资经营者，请提供独资经营的业务资质证书编号。 示例值：5555-8888 |
| 公司注册文件过期时间 | registration_certificate_date | string(10) | 是 | 公司注册文件过期时间。 取值为过期的日期或取值为“PERMANENT”，“N/A”, 若取值为日期，格式为YYYY-MM-DD，比如2020-10-16。 若商户为自然人，请提供董事或负责人的ID号过期日期。 若商户为独资经营者，请提供独资经营的业务资质证书编号过期日期。 示例值：2020-10-16 |
| 公司注册文件照片 | registration_certificate_copy | string(128) | 否 | 请提供公司注册文件的复印件。如果商家是自然人（个人），请提供董事或负责人的身份证复印件。如果商家是独资经营者（个体户），请提供营业执照的复印件。取值为《上传图片API》返回的media ID。 示例值：w7yQFawBtja5uEdm_aoXokv2SDoEmHIPs |
| 业务类型 | business_type | string(7) | 是 | 取值为三种业务类型：ONLINE, OFFLINE 或BOTH 示例值：BOTH |
| APP下载链接 | app_download | string(128) | 是/否 | 商户APP的下载地址，当业务类型取值为ONLINE或BOTH时，app_download, bus_website，office_account, mini_program四项中至少选择一项传入 示例值：https://download.qq.com |
| 业务网站 | business_website | string(128) | 是/否 | 当业务类型取值为ONLINE或BOTH时，app_download, bus_website，office_account, mini_program四项中至少选择一项传入 示例值：https://www.qq.com |
| 公众号 | office_account | string(128) | 是/否 | 当业务类型取值为ONLINE或BOTH时，app_download, bus_website，office_account, mini_program四项中至少选择一项传入 示例值：wx8888888888888888 |
| 小程序 | mini_program | string(128) | 是/否 | 当业务类型取值为ONLINE或BOTH时，app_download, bus_website，office_account, mini_program四项中至少选择一项传入 示例值：wx8888888888888888 |
| 门店地址 | store_address | string(128) | 是/否 | 商户门店地址，当业务类型取值为OFFLINE或BOTH时必传 示例值：广东省深圳市南山区科技中一道10000号 |
| 门店照片 | store_photos | string(1024) | 否 | 商户门店照片，当业务类型取值为OFFLINE或BOTH时建议填写（非必填）。至少上传三张门店照片，取值为上传图片API返回的media ID。多个图片，使用Json数组格式提交。 示例值： |
| 董事姓名 | director_name | string(128) | 否 | 董事姓名，当商户类型为ENTERPRISE时选择填入 示例值：Bob Zhang |
| 董事证件号码 | director_id_number | string(128) | 否 | 董事证件号码，当商户类型为ENTERPRISE时选择填入 示例值：5555—8888 |
| 负责人姓名 | principal_name | string(128) | 否 | 负责人姓名。当商户类型为INDIVIDUAL时选择填入 示例值：Bob Zhang |
| 负责人证件号 | principal_id_number | string(128) | 是/否 | 负责人证件号码。当商户类型为INDIVIDUAL时选择填入 示例值：5555—8888 |
| 客服电话 | office_phone | string(32) | 是 | 请指定客户服务电话号码。 请使用电话号码前缀。前缀列表请参见附录。 示例值：+86075586010000 |
| 联系人姓名 | contact_name | string(64) | 是 | 联系人姓名 示例值：李先生 |
| 联系人电话 | contact_phone | string(32) | 是 | 联系人电话 示例值：075586010000 |
| 联系人邮箱 | contact_email | string(256) | 是 | 联系人邮箱 示例值：test@test.com |
| 子商户结算银行账户 | settlement_bank_number | string(128) | 否 | 子商户的结算银行账户信息 示例值：555588889999 |
| 是否申请H5支付权限 | apply_h5_payment | string(4) | 否 | 是否申请H5支付权限，取值YES或NO。 示例值：YES |
| H5经营网址 | h5_website_url | string(128) | 是/否 | apply_h5_payment为YES时必填。包含该子商户的主营业务、销售商品/服务及价格、用户可在线下单购买的网址。 示例值：https://qq.com |
| H5支付域名 | h5_domains | string(512) | 是/否 | apply_h5_payment为YES时必填。拉起H5支付的域名，不超过5个；以json数组格式提交。 注意：提交的修改的域名列表会覆盖已有支付域名列表。 示例值：["www.qq.com","www.weixin.com"] |
<xml>
<mch_id>1230000109</mch_id>
<app_id><![CDATA[wx7bc98d929da735fe]]></app_id>
<merchant_name><![CDATA[Merchant name]]></merchant_name>
<merchant_shortname><![CDATA[ABC]]></merchant_shortname>
<office_phone><![CDATA[075586010000]]></office_phone>
<business_category><![CDATA[343]]></business_category>
<merchant_remark><![CDATA[202012041]]></merchant_remark>
<merchant_country_code><![CDATA[344]]></merchant_country_code>
<contact_name><![CDATA[bob]]></contact_name>
<contact_phone><![CDATA[+8618688886666]]></contact_phone>
<contact_email><![CDATA[test@tencent.com]]></contact_email>
<merchant_type><![CDATA[INDIVIDUAL]]></merchant_type>
<registration_certificate_number><![CDATA[5555-8888]]></registration_certificate_number>
<registration_certificate_date><![CDATA[2025-08-27]]></registration_certificate_date>
<registration_certificate_copy><![CDATA[w7yQFawBtja5uEdm_aoXokv2SDoEmHIPs]]></registration_certificate_copy>
<business_type><![CDATA[BOTH]]></business_type>
<business_website><![CDATA[http://www.qq.com]]></business_website>
<store_address><![CDATA[First Street]]></store_address>
<mcc><![CDATA[5045]]></mcc>
<settlement_bank_number><![CDATA[55558888]]></settlement_bank_number>
<sign><![CDATA[C47005DF5722D862EFF30E7B8964AE17]]></sign>
</xml>| 字段名 | 变量 | 类型 | 必填 | 描述 |
|---|---|---|---|---|
| 返回状态码 | return_code | string(16) | 是 | SUCCESS/FAIL 此字段是通信标识，非交易标识，交易是否成功需要查看result_code来判断 示例值：SUCCESS |
| 返回信息 | return_msg | string(128) | 否 | 返回信息，如非空，为错误原因 签名失败 参数格式校验错误 示例值：签名失败 |
当return_code为SUCCESS的时候，会包括以下字段：
| 参数名 | 变量 | 类型 | 必填 | 描述 |
|---|---|---|---|---|
| 业务返回码 | result_code | string(32) | 是 | 业务返回码，SUCCESS/FAIL 示例值：SUCCESS |
| 错误编码 | err_code | string(32) | 否 | 详细参见错误列表 示例值：参数格式校验错误 |
| 错误描述 | err_code_des | string(128) | 否 | 错误信息描述 示例值：系统错误 |
| 子商户号 | sub_mch_id | string(32) | 是 | 子商户号，微信支付为该商户创建的商户号 示例值：12345678 |
| 签名 | sign | string(32) | 是 | 参数签名,详见签名方法 示例值：C380BEC2BFD727A4B6845133519F3AD6 |
| 验证状态 | verification_status | string(32) | 是 | 描述子商户的审核状态： Under review： 微信支付审核中，子商户暂无交易权限，无法发起交易（需至微信支付商户平台查询子商户审核状态，审核通过后才可交易） Approved： 微信支付审核通过，子商户可发起正常交易 示例值：Under Review |
| 验证状态描述 | description | string(128) | 否 | 审核状态描述。 示例值：该子商户需要通过审核才可生效。请登录商户平台检查审核状态。 |
| H5支付权限状态 | h5_authorization_state | string(32) | 否 | apply_h5_payment为YES时返回，描述子商户的H5支付权限状态： APPROVED：已有H5权限 UNAUTHORIZED：未获得H5权限，也未申请过H5权限 UNDER_REVIEW：H5权限申请当前在审核中 REJECTED：H5权限申请被驳回 UNDER_PUNISHMENT：曾经申请并获得H5权限，但当前权限被处罚，请联系BD处理； APPLICATION_FAILED：H5权限申请单创建失败 示例值：APPROVED |
<xml>
<return_code><![CDATA[SUCCESS]]></return_code>
<return_msg><![CDATA[OK]]></return_msg>
<result_code><![CDATA[SUCCESS]]></result_code>
<sign><![CDATA[2FB58D2C8CF07E2097D628FA10F05287]]></sign>
<sub_mch_id><![CDATA[013467007045764]]></sub_mch_id>
<verification_status><![CDATA[Approved]]></verification_status>
</xml>| 错误编码 | 描述 | 原因 | 解决方案 |
|---|---|---|---|
| INVALID_REQUEST | 请求错误 | 请使用HTTP POST 方式，检查后重新尝试。 | 请开发人员请求数据 |
| INVALID_REQUEST | 请求异常 | XML格式异常，请检查格式，重新尝试 | |
| SIGNERROR | 签名错误 | 签名校验失败，请检查签名数据，重新尝试。 | |
| INVALID_REQUEST | 请求错误 | 请使用字符集UTF-8. | |
| PARAM_ERROR | 参数错误 | 参数错误，请检查重新尝试。 例如：参数超过限定长度。 |
请检查参数 |
| PARAM_ERROR | 参数错误 | 参数错误，请检查重新尝试。 例如：参数格式错误。 |
|
| INVALID_REQUEST | 请求错误 | 没有进件子商户的权限。 | 请检查权限 |
| INVALID_REQUEST | 请求错误 | 检索客户端证书序列号失败&\160； 来自客户端证书的可分辨名称（DN）字段失败&\160； 证书验证失败。 没有携带证书。请检查后重新尝试。 |
请检查证书 |
| INVALID_REQUEST | 请求错误 | 商户信息校验时发生系统错误。 输入字段包含不适当的术语。检查并再次输入。 输入字段包含不符合服务规则的不适当术语。检查并再次输入。 由于违规，权限被限制。有关详细信息，请联系客户服务。 | 请检查输入信息或联系微信支付 |
| SYSTEMERROR | 系统错误 | 系统错误 | 请联系微信支付技术支持 |
| INVALID_REQUEST | H5支付权限申请失败 | 商户被处罚，不允许申请开通H5支付权限。 | 商户支付权限被处罚，请先联系运营人员解除。 |
| INVALID_REQUEST | H5支付权限申请失败 | 提交的H5经营网址或支付域名存在风险，请联系对接BD处理。 | 经营网址或者H5支付域名命中黑名单，请联系运营人员申请豁免。 |
Customer Service Tel
Business Development
9:00-18:00
Monday-Friday GMT+8
Technical Support
WeChat Pay Global
ICP证