進(jìn)件子商戶API
最新更新時(shí)間：2024.03.27 版本說明
機(jī)構(gòu)提交子商戶資料，微信支付系統(tǒng)會為每個(gè)子商戶創(chuàng)建子商戶號。
注意： ? 本接口請求的header需包含Idempotency-Key參數(shù)，它是一個(gè)由商戶側(cè)生成的唯一key，微信服務(wù)器使用該值來識別多次重試是否為同一請求，該字段長度64位，可包含字母和數(shù)字。
注意： 1. 接口說明
適用對象:機(jī)構(gòu)模式
請求URL: https://apihk.mch.weixin.qq.com/v3/global/merchants
請求方式: POST
Path指該參數(shù)為路徑參數(shù)
Query指該參數(shù)為URL參數(shù)
Body指該參數(shù)需在請求JSON傳參
2. 請求參數(shù)
| 參數(shù)名 | 變量 | 類型[長度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 機(jī)構(gòu)appid | sp_appid | string[1,32] | 是 | Body機(jī)構(gòu)在微信公眾平臺申請服務(wù)號對應(yīng)的APPID 注意：僅適用于機(jī)構(gòu)模式 示例值：wx8888888888888888 |
| 機(jī)構(gòu)商戶號 | sp_mchid | string[1,32] | 是 | Body微信支付分配的機(jī)構(gòu)商戶號 注意：僅適用于機(jī)構(gòu)模式 示例值：3200000001 |
| 商戶名稱 | name | string[1,128] | 是 | Body完整的商家實(shí)體名稱必須與公司的官方注冊文件（例如營業(yè)執(zhí)照、公司注冊證書、工商注冊證等）中的注冊名稱完全相同。 示例值：Merchant name |
| 子商戶簡稱 | shortname | string[1,64] | 是 | Body子商戶簡稱，用于微信訂單詳情和支付成功頁展示 示例值：Merchant shortname |
| 公司電話 | office_phone | string[1,32] | 是 | Body請指定客戶服務(wù)電話號碼。請使用電話號碼前綴。前綴列表請參見附錄。 示例值：+86075586010000 |
| 聯(lián)系人信息 | contact | object | 是 | Body聯(lián)系人信息，詳細(xì)說明見 |
| 行業(yè)類目 | business_category | int | 是 | Body根據(jù)您的營業(yè)執(zhí)照規(guī)定業(yè)務(wù)類別，請參考微信支付的商業(yè)類目列表 示例值：644 |
| 渠道號 | channel_id | string[1,20] | 否 | Body機(jī)構(gòu)在微信商戶管理后臺創(chuàng)建的渠道號，如有渠道號請?zhí)顚? 示例值：3200000001 |
| 注冊國家或區(qū)域 | merchant_country_code | string[1,3] | 是 | Body子商戶公司注冊的國家或區(qū)域，詳見國家/地區(qū)代碼 示例值：344 |
| 商戶類型 | merchant_type | string[1,10] | 是 | Body 取值ENTERPRISE或INDIVIDUAL 若商戶為自然人或獨(dú)資經(jīng)營者，請選擇INDIVIDUAL。 示例值：ENTERPRISE |
| 公司注冊文件編號 | registration_certificate_number | string[1,50] | 是 | Body 公司注冊文件編號。 若商戶為自然人，請?zhí)峁┒禄蜇?fù)責(zé)人的ID號。 若商戶為獨(dú)資經(jīng)營者，請?zhí)峁┆?dú)資經(jīng)營的業(yè)務(wù)資質(zhì)證書編號。 示例值：5555-8888 |
| 公司注冊文件過期時(shí)間 | registration_certificate_date | string[1,10] | 是 | Body 公司注冊文件過期時(shí)間。 取值為過期的日期或取值為“PERMANENT”，“N/A”, 若取值為日期，格式為YYYY-MM-DD，比如2020-10-16。 若商戶為自然人，請?zhí)峁┒禄蜇?fù)責(zé)人的ID號過期日期。 若商戶為獨(dú)資經(jīng)營者，請?zhí)峁┆?dú)資經(jīng)營的業(yè)務(wù)資質(zhì)證書編號過期日期。 示例值：2020-10-16 |
| 公司注冊文件照片 | registration_certificate_copy | string[1,128] | 否 | Body請?zhí)峁┕咀晕募膹?fù)印件。如果商家是自然人（個(gè)人），請?zhí)峁┒禄蜇?fù)責(zé)人的身份證復(fù)印件。如果商家是獨(dú)資經(jīng)營者（個(gè)體戶），請?zhí)峁I業(yè)執(zhí)照的復(fù)印件。取值為《上傳圖片API》返回的media ID。 示例值：w7yQFawBtja5uEdm_aoXokv2SDoEmHIPs |
| 子商戶銀行結(jié)算賬戶信息 | settlement_bank_number | string[1,128] | 否 | Body子商戶的結(jié)算銀行賬戶信息 示例值：555588889999 |
| 業(yè)務(wù)信息 | business | object | 是 | Body業(yè)務(wù)信息，具體請參考business對象列表 |
| 董事信息 | director | object | 是/否 | Body董事信息，當(dāng)商戶類型為ENTERPRISE必傳，具體請參考director對象列表 |
| 負(fù)責(zé)人信息 | principal | object | 是/否 | Body負(fù)責(zé)人信息，當(dāng)商戶類型為INDIVIDUAL必傳，具體請參考principal對象列表 |
| 是否申請H5支付權(quán)限 | apply_h5_payment | boolean | 否 | 是否為子商戶申請H5支付權(quán)限。 需要申請H5支付權(quán)限時(shí)此字段為true。 示例值：true |
| H5支付申請資料資料 | h5_payment_apply_info | object | 是/否 | BodyH5申請資料，需要申請H5支付權(quán)限時(shí)填寫。 |
敏感字段加密說明：對于包含了敏感信息的參數(shù)，如聯(lián)系方式等，我們增加了“字段加密”的安全機(jī)制，保護(hù)敏感信息只能被數(shù)據(jù)的接收方看到。
加密步驟：
1、獲取微信支付平臺證書和對應(yīng)的平臺證書序列號，獲取微信支付平臺證書。 本接口請求http頭的“Wechatpay-Serial”需要傳平臺證書序列號。
2、使用微信支付平臺證書的公鑰，對于需要加密的參數(shù)值進(jìn)行RSA加密。Java語言的加密方法的填充方案使用 RSA/ECB/PKCS1Padding ;PHP填充方式為OPENSSL_PKCS1_PADDING。
3、加密后的密文，使用base64編碼后，作為請求中相應(yīng)參數(shù)的值。
請求示例
{
"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. 返回參數(shù)
正常返回
| 參數(shù)名 | 變量 | 類型[長度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 子商戶號 | sub_mchid | string[1,32] | 是 | 微信支付分配的子商戶號 注意：僅適用于機(jī)構(gòu)模式 示例值：1900000109 |
| 審核狀態(tài) | verification_status | string[1,32] | 是 | 描述子商戶的審核狀態(tài)： Under Review：微信支付審核中，子商戶暫無交易權(quán)限，無法發(fā)起交易 （需至微信支付商戶平臺查詢子商戶審核狀態(tài)，審核通過后才可交易） Approved：微信支付審核通過，子商戶可發(fā)起正常交易 示例值：Under Review |
| 驗(yàn)證狀態(tài)描述 | description | string[1,128] | 否 | 審核狀態(tài)描述。 示例值：該子商戶需要通過審核才可生效。請登錄商戶平臺檢查審核狀態(tài)。 |
| H5支付權(quán)限狀態(tài) | h5_authorization_state | string[1, 32] | 是 | apply_h5_payment為YES時(shí)返回，描述子商戶的H5支付權(quán)限狀態(tài)： APPROVED：已有H5權(quán)限 UNAUTHORIZED：未獲得H5權(quán)限，也未申請過H5權(quán)限 UNDER_REVIEW：H5權(quán)限申請當(dāng)前在審核中 REJECTED：H5權(quán)限申請被駁回 UNDER_PUNISHMENT：曾經(jīng)申請并獲得H5權(quán)限，但當(dāng)前權(quán)限被處罰，請聯(lián)系BD處理； APPLICATION_FAILED：H5權(quán)限申請單創(chuàng)建失敗 示例值：APPROVED |
異常返回
| 參數(shù)名 | 變量 | 類型[長度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 返回狀態(tài)碼 | code | string[1, 32] | 是 | 錯(cuò)誤碼，枚舉值見錯(cuò)誤碼列表 示例值：INVALID_REQUEST |
| 返回信息 | message | string[1, 256] | 是 | 返回信息，如非空，為錯(cuò)誤原因 示例值：參數(shù)格式校驗(yàn)錯(cuò)誤 |
| 詳細(xì)的錯(cuò)誤描述 | detail | object | 否 | 當(dāng)code為PARAM_ERROR時(shí)返回，詳細(xì)說明見下 |
返回示例
{
"sub_mchid": "20000100",
"verification_status": "Approved"
}
4. 錯(cuò)誤碼
| 錯(cuò)誤碼 | 描述 | 解決方案 |
|---|---|---|
| PARAM_ERROR | 請求參數(shù)未按指引進(jìn)行填寫 | 具體參數(shù)格式可以查看文檔 |
| SYSTEM_ERROR | 后臺系統(tǒng)返回錯(cuò)誤 | 系統(tǒng)異常，請使用原參數(shù)重新發(fā)起 |
| INVALID_REQUEST | 商戶系統(tǒng)異常導(dǎo)致，商戶權(quán)限異常、重復(fù)請求支付、證書錯(cuò)誤、頻率限制、商戶號不存在、appid和mchid不存在綁定關(guān)系、渠道號不對等 | 請根據(jù)接口返回的詳細(xì)錯(cuò)誤描述信息檢查您的程序，具體可以查詢detail 字段返回的詳細(xì)信息 |
| INVALID_REQUEST | 沒有api創(chuàng)建子商戶的權(quán)限 | ?請登錄商戶管理后臺人工錄入子商戶信息 |
| INVALID_REQUEST | 商戶唯一標(biāo)識已經(jīng)存在，請更換 | 針對不同的子商戶，請定義唯一的標(biāo)識 |
| INVALID_REQUEST | 商戶被處罰，不允許申請開通H5支付權(quán)限。 | 商戶支付權(quán)限被處罰，請先聯(lián)系運(yùn)營人員解除 |
| INVALID_REQUEST | 提交的H5經(jīng)營網(wǎng)址或支付域名存在風(fēng)險(xiǎn)，請聯(lián)系對接BD處理。 | 經(jīng)營網(wǎng)址或者H5支付域名命中黑名單，請聯(lián)系運(yùn)營人員申請豁免 |
頁面導(dǎo)航
