平臺收付通（二級商戶進(jìn)件）開發(fā)指引
1. 接口規(guī)則
為了在保證支付安全的前提下，帶給商戶簡單、一致且易用的開發(fā)體驗，我們推出了全新的微信支付APIv3接口。該版本API的具體規(guī)則請參考“APIv3接口規(guī)則”
2. 開發(fā)準(zhǔn)備
2.1. 搭建和配置開發(fā)環(huán)境
為了幫助開發(fā)者調(diào)用開放接口，我們提供了JAVA、PHP、GO三種語言版本的開發(fā)庫，封裝了簽名生成、簽名驗證、敏感信息加/解密、媒體文件上傳等基礎(chǔ)功能（更多語言版本的開發(fā)庫將在近期陸續(xù)提供）
測試步驟：
1、根據(jù)自身開發(fā)語言，選擇對應(yīng)的開發(fā)庫并構(gòu)建項目，具體配置請參考下面鏈接的詳細(xì)說明：
? wechatpay-java（推薦）wechatpay-apache-httpclient，適用于Java開發(fā)者。
? wechatpay-php（推薦）、wechatpay-guzzle-middleware，適用于PHP開發(fā)者
注：當(dāng)前開發(fā)指引接口PHP示例代碼采用wechatpay-guzzle-middleware版本
? wechatpay-go，適用于Go開發(fā)者
更多資源可前往微信支付開發(fā)者社區(qū)搜索查看
2、創(chuàng)建加載商戶私鑰、加載平臺證書、初始化httpClient的通用方法
@Before
public void setup() throws IOException {
// 加載商戶私鑰（privateKey：私鑰字符串）
PrivateKey merchantPrivateKey = PemUtil
.loadPrivateKey(new ByteArrayInputStream(privateKey.getBytes("utf-8")));
// 加載平臺證書（mchId：商戶號,mchSerialNo：商戶證書序列號,apiV3Key：V3密鑰）
AutoUpdateCertificatesVerifier verifier = new AutoUpdateCertificatesVerifier(
new WechatPay2Credentials(mchId, new PrivateKeySigner(mchSerialNo, merchantPrivateKey)),apiV3Key.getBytes("utf-8"));
// 初始化httpClient
httpClient = WechatPayHttpClientBuilder.create()
.withMerchant(mchId, mchSerialNo, merchantPrivateKey)
.withValidator(new WechatPay2Validator(verifier)).build();
}
@After
public void after() throws IOException {
httpClient.close();
}
3、基于接口的示例代碼，替換請求參數(shù)后可發(fā)起測試
說明：
? 上面的開發(fā)庫為微信支付官方開發(fā)庫，其它沒有審核或者控制下的第三方工具和庫，微信支付不保證它們的安全性和可靠性
通過包管理工具引入SDK后，可根據(jù)下面每個接口的示例代碼替換相關(guān)參數(shù)后進(jìn)行快速測試
? 開發(fā)者如果想詳細(xì)了解簽名生成、簽名驗證、敏感信息加/解密、媒體文件上傳等常用方法的具體代碼實現(xiàn)，可閱讀下面的詳細(xì)說明：
1.簽名生成
2.簽名驗證
3.敏感信息加解密
? 如想更詳細(xì)的了解我們的接口規(guī)則，可查看我們的接口規(guī)則指引文檔
2.2. 業(yè)務(wù)開發(fā)配置-二級商戶進(jìn)件
1、 平臺需確認(rèn)是否已開通收付通工具箱，詳細(xì)可前往平臺收付通介紹查看。
2、待進(jìn)件的二級商戶是否符合進(jìn)件要求，相關(guān)要求可以前往二級商戶入駐介紹查看。
3. 快速接入
3.1. 業(yè)務(wù)流程圖-二級商戶進(jìn)件
重要步驟說明：
步驟一： 平臺通過請求二級商戶進(jìn)件接口幫助二級商戶提交商戶進(jìn)件資料。進(jìn)件參數(shù)中包含了敏感信息參數(shù)，此類參數(shù)要求進(jìn)行加密，詳見 接口規(guī)則。
步驟二： 提交進(jìn)件資料后，平臺需通過微信支付返回的“微信支付申請單號”和“業(yè)務(wù)申請編號”來請求查詢申請狀態(tài)API接口查詢二級商戶進(jìn)件狀態(tài)。
步驟三： 進(jìn)件成功后，若二級商戶需修改結(jié)算賬號時，平臺可通過請求修改商戶結(jié)算賬號API接口來幫助二級商戶修改賬號信息。
步驟四： 平臺通過請求查詢商戶結(jié)算賬號API接口來查詢修改情況。
3.2. API接入-二級商戶進(jìn)件
本文檔展示了如何使用微信支付服務(wù)端 SDK 快速接入平臺收付通產(chǎn)品，完成與微信支付對接的部分。
注意：
- 文檔中的代碼示例是用來闡述 API 基本使用方法，代碼中的示例參數(shù)需替換成商戶自己賬號及請求參數(shù)才能跑通。
- 以下接入步驟僅提供參考，請商戶結(jié)合自身業(yè)務(wù)需求進(jìn)行評估、修改。
3.2.1. 【服務(wù)端】二級商戶進(jìn)件申請
步驟說明：平臺可使用該接口，幫助其二級商戶進(jìn)件成為微信支付商戶。
示例代碼
public void Applyments() throws Exception{
//請求URL
HttpPost httpPost = new HttpPost("https://api.mch.weixin.qq.com/v3/ecommerce/applyments/");
// 請求body參數(shù)
String reqdata = "{"
+ "\"organization_type\":\"2\","
+ "\"business_license_info\": {"
+ "\"business_license_copy\":\"47ZC6GC-vnrbEny__Ie_An5-tCpqxucuxi-vByf3Gjm7KE53JXvGy9tqZm2XAUf-4KGprrKhpVBDIUv0OF4wFNIO4kqg05InE4d2I6_H7I4\","
+ "\"business_license_number\":\"123456789012345678\","
+ "\"merchant_name\":\"騰訊科技有限公司\","
+ "\"legal_person\":\"張三\""
+ "},"
+ "\"organization_cert_info\": {"
+ "\"organization_copy\":\"47ZC6GC-vnrbEny__Ie_An5-tCpqxucuxi-vByf3Gjm7KE53JXvGy9tqZm2XAUf-4KGprrKhpVBDIUv0OF4wFNIO4kqg05InE4d2I6_H7I4\","
+ "\"organization_time\":\"[\"2014-01-01\","\"長期\"]\","
+ "\"organization_number\":\"12345679-A\""
+ "},"
+ "\"id_card_info\": {"
+ "\"id_card_copy\":\"jTpGmxUX3FBWVQ5NJTZvlKX_gdU4cRz7z5NxpnFuAxhBTEO_PvWkfSCJ3zVIn001D8daLC-ehEuo0BJqRTvDujqhThn4ReFxikqJ5YW6zFQ\","
+ "\"id_card_national\":\"47ZC6GC-vnrbEny__Ie_An5-tCpqxucuxi-vByf3Gjm7KE53JXvGy9tqZm2XAUf-4KGprrKhpVBDIUv0OF4wFNIO4kqg05InE4d2I6_H7I4\","
+ "\"id_card_name\":\"pVd1HJ6zyvPedzGaV+X3qtmrq9bb9tPROvwia4ibL+F6mfjbzQIzfb3HHLEjZ4YiR/cJiCrZxnAqi+pjeKIEdkwzXRAI7FUhrfPK3SNjaBTEu9GmsugMIA9r3x887Q+ODuC8HH2nzAn7NGpE/e3yiHgWhk0ps5k5DP/2qIdGdONoDzZelrxCl/NWWNUyB93K9F+C1JX2IMttdY+aQ6zBlw0xnOiNW6Hzy7UtC+xriudjD5APomty7/mYNxLMpRSvWKIjOv/69bDnuC4EL5Kz4jBHLiCyOb+tI0m2qhZ9evAM+Jv1z0NVa8MRtelw/wDa4SzfeespQO/0kjiwfqdfg==\","
+ "\"id_card_number\":\"UZFETyabYFFlgvGh6R4vTzDELiPas3jC94/srAbSaPaWSM+1rhGLcsybPLeJdVOpCeDxNBMDK+/N0nOiZZ4ka9+5RgzvA2rJx+NztYUbN209rq0Y/NP50T9yk0m6A4xUoFWgk/8qteRHtP5VHahNhSh8nHo31V33t8edSlN9HJG6diRj7p5JPImDyM1q56+p25edl3+cOtuZtj8TJDl/hB+GaWve9X1WUpkZbKlJgBxp+XhaW707k9XrILvfD+rSGTOeU/ev4/OiEb5W4WPGJ+3iLoQvhnz3+aQZX9+gn9uRzWcHu2Kr17fhsM+MRkgVcwzI2UqhR9iuGTunRPRVFg==\","
+ "\"id_card_valid_time\":\"2026-06-06\""
+ "},"
+ "\"need_account_info\":true,"
+ "\"account_info\": {"
+ "\"bank_account_type\":\"74\","
+ "\"account_name\":\"fTA4TXc8yMOwFCYeGPktOOSbOBei3KA8RAMO9h/5Y0ZMR46viedrDurCbQTC/sCC9BWuG5oeR8flymK/Z4dN0/7XDSDfqT5Nggq9WwTL+OZdMorqTE6Z0G3f3Bi3c+GVvYOCZyVdoinksPEUwyosEtwupM3ufXSZT36DvsS8K9jOBnIXjGaQtP94FFlh58WR0GuEkMt9KT2NuA+fE4KDScRzSZn3TL5Izdt+7anPS6Uh4K7wPnUWHGxCQdZu0G4B4YjP7ync8UeLu4jAkCziq4lngnU3rKfFiqwMtyOA179x15za7+kWmo2hfaC7xumTqXR7/NyRHpFKXURQFcmmw==\","
+ "\"account_bank\":\"工商銀行\(zhòng)","
+ "\"bank_address_code\":\"110000\","
+ "\"bank_branch_id\":\"402713354941\","
+ "\"bank_name\":\"施秉縣農(nóng)村信用合作聯(lián)社城關(guān)信用社\","
+ "\"account_number\":\"d+xT+MQCvrLHUVDWv/8MR/dB7TkXM2YYZlokmXzFsWs35NXUot7C0NcxIrUF5FnxqCJHkNgKtxa6RxEYyba1+VBRLnqKG2fSy/Y5qDN08Ej9zHCwJjq52Wg1VG8MRugli9YMI1fI83KGBxhuXyemgS/hqFKsfYGiOkJqjTUpgY5VqjtL2N4l4z11T0ECB/aSyVXUysOFGLVfSrUxMPZy6jWWYGvT1+4P633f+R+ki1gT4WF/2KxZOYmli385ZgVhcR30mr4/G3HBcxi13zp7FnEeOsLlvBmI1PHN4C7Rsu3WL8sPndjXTd75kPkyjqnoMRrEEaYQE8ZRGYoeorwC+w==\""
+ "},"
+ "\"contact_info\": {"
+ "\"contact_type\":\"65\","
+ "\"contact_name\":\"pVd1HJ6zyvPedzGaV+X3qtmrq9bb9tPROvwia4ibL+F6mfjbzQIzfb3HHLEjZ4YiR/cJiCrZxnAqi+pjeKIEdkwzXRAI7FUhrfPK3SNjaBTEu9GmsugMIA9r3x887Q+ODuC8HH2nzAn7NGpE/e3yiHgWhk0ps5k5DP/2qIdGdONoDzZelrxCl/NWWNUyB93K9F+jC1JX2IMttdY+aQ6zBlw0xnOiNW6Hzy7UtC+xriudjD5APomty7/mYNxLMpRSvWKIjOv/69bDnuC4EL5Kz4jBHLiCyOb+tI0m2qhZ9evAM+Jv1z0NVa8MRtelw/wDa4SzfeespQO/0kjiwfqdfg==\","
+ "\"contact_id_card_number\":\"UZFETyabYFFlgvGh6R4vTzDELiPas3jC94/srAbSaPaWSM+1rhGLcsybPLeJdVOpCeDxNBMDK+/N0nOiZZ4ka9+5RgzvA2rJx+NztYUbN209rq0Y/NP50T9yk0m6A4xUoFWgk/8qteRHtP5VHahNhSh8nHo31V33t8edSlN9HJG6diRj7p5JPImDyM1q56+p25edl3+cOtuZtj8TJDl/hB+GaWve9X1WUpkZbKlJgBxp+XhaW707k9XrILvfD+rSGTOeU/ev4/OiEb5W4WPGJ+3iLoQvhnz3+aQZX9+gn9uRzWcHu2Kr17fhsM+MRkgVcwzI2UqhR9iuGTunRPRVFg==\","
+ "\"mobile_phone\":\"Uy5Hb0c5Se/orEbrWze/ROHu9EPAs/CigDlJ2fnyzC1ppJNBOYGyc89xUgZZoPIRnPWsvJ5oevXNdBK3IUz9WHs9iQKpeUksvoLQMsykc8LDu7MMpayKWNVozldcRugH++MltTBKWTkv/oOcwkZattMGgP4CtpbN6djDK1PcAmIDgdFD2ZvCIDCtJg1V/YafUBJdBTvNLXa/jNzjZaypsUn1BRO6fx8aaNn7XyTv7JrfQZE4UDH4gfMFOj8YDqQ+IvDbkuNhaLZExOEz/UcnxeN5mfGr2MdkPrOzF+xJmUZUn1nafZxENrqcBszhYQUlu5zn6o2uZpBhAsQwd3QAjw==\","
+ "\"contact_email\":\"Uy5Hb0c5Se/orEbrWze/ROHu9EPAs/CigDlJ2fnyzC1ppJNBOYGyc89xUgZZoPIRnPWsvJ5oevXNdBK3IUz9WHs9iQKpeUksvoLQMsykc8LDu7MMpayKWNVozldcRugH++MltTBKWTkv/oOcwkZattMGgP4CtpbN6djDK1PcAmIDgdFD2ZvCIDCtJg1V/YafUBJdBTvNLXa/jNzjZaypsUn1BRO6fx8aaNn7XyTv7JrfQZE4UDH4gfMFOj8YDqQ+IvDbkuNhaLZExOEz/UcnxeN5mfGr2MdkPrOzF+xJmUZUn1nafZxENrqcBszhYQUlu5zn6o2uZpBhAsQwd3QAjw==\""
+ "},"
+ "\"sales_scene_info\": {"
+ "\"store_name\":\"愛燒烤\","
+ "\"store_url\":\"http://www.qq.com\","
+ "\"store_qr_code\":\"jTpGmxUX3FBWVQ5NJTZvlKX_gdU4cRz7z5NxpnFuAxhBTEO_PvWkfSCJ3zVIn001D8daLC-ehEuo0BJqRTvDujqhThn4ReFxikqJ5YW6zFQ\""
+ "},"
+ "\"merchant_shortname\":\"愛燒烤\","
+ "\"out_request_no\":\"APPLYMENT_00000000001\","
+ "\"qualifications\":\"[\"jTpGmxUX3FBWVQ5NJTZvlKX_gdU4cRz7z5NxpnFuAxhBTEO_PvWkfSCJ3zVIn001D8daLC-ehEuo0BJqRTvDujqhThn4ReFxikqJ5YW6zFQ\","\"47ZC6GC-vnrbEny__Ie_An5-tCpqxucuxi-vByf3Gjm7KE53JXvGy9tqZm2XAUf-4KGprrKhpVBDIUv0OF4wFNIO4kqg05InE4d2I6_H7I4"]\","
+ "\"business_addition_pics\":\"["jTpGmxUX3FBWVQ5NJTZvlKX_gdU4cRz7z5NxpnFuAxhBTEO_PvWkfSCJ3zVIn001D8daLC-ehEuo0BJqRTvDujqhThn4ReFxikqJ5YW6zFQ","47ZC6GC-vnrbEny__Ie_An5-tCpqxucuxi-vByf3Gjm7KE53JXvGy9tqZm2XAUf-4KGprrKhpVBDIUv0OF4wFNIO4kqg05InE4d2I6_H7I4"]\","
+ "\"business_addition_desc\":\"特殊情況，說明原因\""
+ "}";
StringEntity entity = new StringEntity(reqdata,"utf-8");
entity.setContentType("application/json");
httpPost.setEntity(entity);
httpPost.setHeader("Accept", "application/json");
//完成簽名并執(zhí)行請求
CloseableHttpResponse response = httpClient.execute(httpPost);
try {
int statusCode = response.getStatusLine().getStatusCode();
if (statusCode == 200) { //處理成功
System.out.println("success,return body = " + EntityUtils.toString(response.getEntity()));
} else if (statusCode == 204) { //處理成功，無返回Body
System.out.println("success");
} else {
System.out.println("failed,resp code = " + statusCode+ ",return body = " + EntityUtils.toString(response.getEntity()));
throw new IOException("request failed");
}
} finally {
response.close();
}
}更多參數(shù)、響應(yīng)詳情及錯誤碼請參見二級商戶進(jìn)件申請API接口文檔
3.2.2.【服務(wù)端】查詢進(jìn)件申請狀態(tài)
步驟說明：平臺可使用該接口，幫助其二級商戶查詢進(jìn)件狀態(tài)。
示例代碼：
public void QueryApplyments() throws Exception{
//請求URL
HttpGet httpGet = new HttpGet("https://api.mch.weixin.qq.com/v3/ecommerce/applyments/out-request-no/APPLYMENT_00000000001");
httpGet.setHeader("Accept", "application/json");
//完成簽名并執(zhí)行請求
CloseableHttpResponse response = httpClient.execute(httpGet);
try {
int statusCode = response.getStatusLine().getStatusCode();
if (statusCode == 200) { //處理成功
System.out.println("success,return body = " + EntityUtils.toString(response.getEntity()));
} else if (statusCode == 204) { //處理成功，無返回Body
System.out.println("success");
} else {
System.out.println("failed,resp code = " + statusCode+ ",return body = " + EntityUtils.toString(response.getEntity()));
throw new IOException("request failed");
}
} finally {
response.close();
}
}更多參數(shù)、響應(yīng)詳情及錯誤碼請參見查詢進(jìn)件申請狀態(tài)API接口文檔
3.2.3.【服務(wù)端】修改結(jié)算賬號
步驟說明：二級商戶結(jié)算賬號錯誤或者變更，平臺可通過該接口進(jìn)行修改。
示例代碼：
public void UpdataSettlement() throws Exception{
//請求URL
HttpPost httpPost = new HttpPost("https://api.mch.weixin.qq.com/v3/apply4sub/sub_merchants/{sub_mchid}/modify-settlement");
// 請求body參數(shù)
String reqdata = "{"
+ "\"account_type\":\"ACCOUNT_TYPE_BUSINESS\","
+ "\"account_bank\":\"工商銀行\(zhòng)","
+ "\"bank_address_code\":\"110000\","
+ "\"bank_name\":\"施秉縣農(nóng)村信用合作聯(lián)社城關(guān)信用社\","
+ "\"bank_branch_id\":\"402713354941\","
+ "\"account_number\":\"d+xT+MQCvrLHUVDWv/8MR/dB7TkXM2YYZlokmXzFsWs35NXUot7C0NcxIrUF5FnxqCJHkNgtxa6RxEYyba1+VBRLnqKG2fSy/Y5qDN08Ej9zHCwJjq52Wg1VG8MRugli9YMI1fI83KGBxhuXyemgS/hqFKsfYGiOJqjTUpgY5VqjtL2N4l4z11T0ECB/aSyVXUysOFGLVfSrUxMPZy6jWWYGvT1+4P633f+R+ki1gT4WF/2KxZOYmi385ZgVhcR30mr4/G3HBcxi13zp7FnEeOsLlvBmI1PHN4C7Rsu3WL8sPndjXTd75kPkyjqnoMRrEEaQE8ZRGYoeorwC+w==\""
+ "}";
StringEntity entity = new StringEntity(reqdata,"utf-8");
entity.setContentType("application/json");
httpPost.setEntity(entity);
httpPost.setHeader("Accept", "application/json");
//完成簽名并執(zhí)行請求
CloseableHttpResponse response = httpClient.execute(httpPost);
try {
int statusCode = response.getStatusLine().getStatusCode();
if (statusCode == 200) { //處理成功
System.out.println("success,return body = " + EntityUtils.toString(response.getEntity()));
} else if (statusCode == 204) { //處理成功，無返回Body
System.out.println("success");
} else {
System.out.println("failed,resp code = " + statusCode+ ",return body = " + EntityUtils.toString(response.getEntity()));
throw new IOException("request failed");
}
} finally {
response.close();
}
}更多參數(shù)、響應(yīng)詳情及錯誤碼請參見修改結(jié)算賬號API接口文檔
3.2.4. 【服務(wù)端】查詢結(jié)算賬號
步驟說明：平臺可使用該接口，幫助其二級商戶查詢結(jié)算賬號。
示例代碼：
public void GetSettlement() throws Exception{
//請求URL
HttpGet httpGet = new HttpGet("https://api.mch.weixin.qq.com/v3/apply4sub/sub_merchants/1900006491/settlement");
httpGet.setHeader("Accept", "application/json");
//完成簽名并執(zhí)行請求
CloseableHttpResponse response = httpClient.execute(httpGet);
try {
int statusCode = response.getStatusLine().getStatusCode();
if (statusCode == 200) { //處理成功
System.out.println("success,return body = " + EntityUtils.toString(response.getEntity()));
} else if (statusCode == 204) { //處理成功，無返回Body
System.out.println("success");
} else {
System.out.println("failed,resp code = " + statusCode+ ",return body = " + EntityUtils.toString(response.getEntity()));
throw new IOException("request failed");
}
} finally {
response.close();
}
}更多參數(shù)、響應(yīng)詳情及錯誤碼請參見查詢結(jié)算賬號API接口文檔
4. 常見問題
Q:平臺收付通進(jìn)件調(diào)用“二級商戶進(jìn)件接口”返回：貴司涉及保險業(yè)務(wù)并提供《經(jīng)營保險業(yè)務(wù)許可證》/《保險業(yè)務(wù)法人等級證書》等，其他公司提供相關(guān)資質(zhì)
A:返回這個報錯，請求參數(shù)中請上傳“特殊資質(zhì)（qualifications）”字段
Q:平臺收付通進(jìn)件調(diào)用“查詢進(jìn)件申請狀態(tài)接口”沒有返回“法人驗證鏈接legal_validation_url”
A:主體類型為“黨政、機(jī)關(guān)及事業(yè)單位 /其他組織”時，只能匯款驗證，是不會返回法人驗證鏈接的。接入流程說明文檔中的第4點也有說明
Q:平臺收付通進(jìn)件“查詢申請狀態(tài)接口”：開戶狀態(tài)為“已凍結(jié)”是在什么情況下出現(xiàn)？ 開戶成功之后會出現(xiàn)凍結(jié)情況嗎
A:申請狀態(tài)“已凍結(jié)”是審核人員認(rèn)為有風(fēng)險時候，會凍結(jié)。開戶成功后，基本不會出現(xiàn)“已凍結(jié)”
Q:平臺收付通進(jìn)件調(diào)用“二級商戶進(jìn)件接口”返回：商戶簡稱取值有誤，你輸入的商戶簡稱涉及敏感字段，不符合相關(guān)規(guī)定，請檢查后重新輸入
A:參數(shù)merchant_shortname命中敏感字段，請更換一個新的簡稱重新提交
Q:平臺收付通進(jìn)件調(diào)用“二級商戶進(jìn)件接口”返回：身份證結(jié)束日期有誤，結(jié)束日期必須晚于當(dāng)前60天
A:參數(shù)id_card_valid_time錯誤，請嚴(yán)格按照文檔要求傳參，這個參數(shù)的規(guī)則如下：
1）請?zhí)顚懮矸葑C有效期的結(jié)束時間，注意參照示例中的格式
2）若證件有效期為長期，請?zhí)顚懀洪L期
3）證件有效期需大于60天