进件子商户API
最新更新时间：2024.03.27 版本说明
机构提交子商户资料，微信支付系统会为每个子商户创建子商户号。
注意： • 本接口请求的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 | 是/否 | BodyH5申请资料，需要申请H5支付权限时填写。 |
敏感字段加密说明：对于包含了敏感信息的参数，如联系方式等，我们增加了“字段加密”的安全机制，保护敏感信息只能被数据的接收方看到。
加密步骤：
1、获取微信支付平台证书和对应的平台证书序列号，获取微信支付平台证书。 本接口请求http头的“Wechatpay-Serial”需要传平台证书序列号。
2、使用微信支付平台证书的公钥，对于需要加密的参数值进行RSA加密。Java语言的加密方法的填充方案使用 RSA/ECB/PKCS1Padding ;PHP填充方式为OPENSSL_PKCS1_PADDING。
3、加密后的密文，使用base64编码后，作为请求中相应参数的值。
请求示例
{
"sp_appid": "wx82ec4jy334ner1",
"sp_mchid": "2422128905",
"name": "Merchant name",
"shortname": "shortname",
"office_phone": "+86075586010000",
"contact": {
"email": "gP32/1QSaIpKlaFbWgP3hr8W3+YTtiavMRbOJJ6dATymJzxx/b4YPOTKdeRApW6Nt2ZZB9reZ1x45XhIEF/Ztb6mqfFVb6LxpJlHgDL/zpUG51551XQ3Ww+/kVCJcokiIiT1bSwEcCe6tPL2cmdsOEjlTikyrasLc1bG8vaG/i361r0vX9w56O2Mgv3OnJ4fr4xnmxNcVrJnk1f/gBSIiCUWA0163f3LM4KifQelEuz/WtroeKAzRDiI0/pOvXfwrYDK==",
"name": "Vxjsrod2RT2aGxeI5i+Z2C4arXYGXZuwE8IrRf6uYu6S5dy4Igw7kjvYWYCNfsgcdXyfjdA4KVntbgSa3zic+ERsOd5u+SNKkaFSH3SwYtpcCyaUMvICTw/6AOY/qy+He9la/gxObgi4zkxvLJmZTJVualTVJWWCIvcuDArW8Kfqp8rBl+IxDEgCojoEmqE7ymVReslGBXWiaPS1UsZx1QJyez3/ijzBa4AKch3XuPx6d3qvM+J8iMx/b94LAfpTihU/j==",
"phone": "l8JH2dAGLNJ8P5DENoMV0eW4JgIquV2ZO4conHnZp48g/eVpgvIfMj4Ge6LRVENW4eZksErJnYCQB+EOFEGR0lMhA1LexPLu0en08iM2ghkftYWAsOD4JPkvvc36SAfWal29eoZh4maO6kOGW7G4uBua6JoMsEjR6uuw5Gw5DC2eikcdkDBGk9vHSP/oxRs3Qu8a83GikhLgdpAPitXbZX/TEPG5SUg8Fx4BCMCKOfxy8uakq2/EeCtyBMjaiheUePoA=="
},
"business_category": 644,
"merchant_country_code": "344",
"merchant_type": "ENTERPRISE",
"registration_certificate_number": "519723407213085723",
"registration_certificate_date": "2022-06-03",
"settlement_bank_number": "559304578245298347923856",
"business": {
"business_type": "ONLINE",
"mcc": "5344",
"mini_program": "wx8888888888888888"
},
"director": {
"name": "Tom",
"number": "1234567890"
}
}
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时返回，详细说明见下 |
返回示例
{
"sub_mchid": "20000100",
"verification_status": "Approved"
}
4. 错误码
| 错误码 | 描述 | 解决方案 |
|---|---|---|
| PARAM_ERROR | 请求参数未按指引进行填写 | 具体参数格式可以查看文档 |
| SYSTEM_ERROR | 后台系统返回错误 | 系统异常，请使用原参数重新发起 |
| INVALID_REQUEST | 商户系统异常导致，商户权限异常、重复请求支付、证书错误、频率限制、商户号不存在、appid和mchid不存在绑定关系、渠道号不对等 | 请根据接口返回的详细错误描述信息检查您的程序，具体可以查询detail 字段返回的详细信息 |
| INVALID_REQUEST | 没有api创建子商户的权限 | 请登录商户管理后台人工录入子商户信息 |
| INVALID_REQUEST | 商户唯一标识已经存在，请更换 | 针对不同的子商户，请定义唯一的标识 |
| INVALID_REQUEST | 商户被处罚，不允许申请开通H5支付权限。 | 商户支付权限被处罚，请先联系运营人员解除 |
| INVALID_REQUEST | 提交的H5经营网址或支付域名存在风险，请联系对接BD处理。 | 经营网址或者H5支付域名命中黑名单，请联系运营人员申请豁免 |
页面导航
