聯(lián)條碼支付聯(lián)調(diào)三重校驗：IP白名單、證書序列號與回調(diào)地址硬約束)
簡介本資源是《網(wǎng)聯(lián)條碼支付收單機(jī)構(gòu)聯(lián)調(diào)環(huán)境接入指引》官方文檔2018年5月版面向互聯(lián)網(wǎng)支付領(lǐng)域收單機(jī)構(gòu)的技術(shù)對接人員與系統(tǒng)集成工程師解決條碼支付系統(tǒng)聯(lián)調(diào)接入中的身份認(rèn)證、網(wǎng)絡(luò)白名單配置、接口地址調(diào)用及證書管理等核心問題。文檔為單文件Word格式.docx共1個文件大小96KB內(nèi)容結(jié)構(gòu)清晰涵蓋收單機(jī)構(gòu)基本信息填報規(guī)范、12組測試源IP白名單要求、支付寶/微信全鏈路交易接口統(tǒng)一下單、退款查詢等及SFTP對賬地址、證書序列號申請流程與HTTPS回調(diào)約束等實操要點(diǎn)。目前已有173人學(xué)習(xí)下載讀者可直接獲取標(biāo)準(zhǔn)化接入?yún)?shù)模板、平臺側(cè)聯(lián)調(diào)地址清單、簽名算法選型建議RSA/SM2、自助驗證平臺入口及關(guān)鍵注意事項如僅支持IP回調(diào)、需一次性提交全部測試IP大幅降低聯(lián)調(diào)環(huán)境部署門檻保障合規(guī)高效接入網(wǎng)聯(lián)條碼支付體系。1. 網(wǎng)聯(lián)條碼支付收單機(jī)構(gòu)聯(lián)調(diào)環(huán)境接入指引不是說明書是收單系統(tǒng)上線前的「白名單證書IP」三重校驗清單你手上有微信/支付寶掃碼收單能力也跑通了自家商戶進(jìn)件、訂單生成、支付回調(diào)但一連網(wǎng)聯(lián)聯(lián)調(diào)環(huán)境就卡在「403 Forbidden」或「SSL handshake failed」——不是代碼寫錯了而是你根本沒看清這份《網(wǎng)聯(lián)條碼支付_收單機(jī)構(gòu)聯(lián)調(diào)環(huán)境接入指引_20180504_1030.docx》里埋的三個硬性準(zhǔn)入條件白名單IP必須一次性報全、證書序列號不能抄錯位、回調(diào)地址連域名都不讓用。這不是開發(fā)文檔是網(wǎng)聯(lián)側(cè)對收單機(jī)構(gòu)網(wǎng)絡(luò)身份、密鑰體系、通信路徑的聯(lián)合校驗單。它不教你寫Java還是Python只告訴你哪幾個IP要提前備案、哪個證書序列號該填在哪張表、為什么用SFTP對賬卻要單獨(dú)開22端口白名單、以及為什么你測試時能下單卻收不到交易完成通知——八成是HTTPS回調(diào)地址寫了域名而非IP。適合正在對接網(wǎng)聯(lián)條碼支付的收單技術(shù)負(fù)責(zé)人、支付中臺工程師、以及被業(yè)務(wù)方催著“下周必須過聯(lián)調(diào)”的后端同學(xué)。別急著寫接口先拿這份指引核對你的網(wǎng)絡(luò)拓?fù)浜兔荑€管理流程。2. 收單機(jī)構(gòu)側(cè)準(zhǔn)入準(zhǔn)備從金融機(jī)構(gòu)編碼到源IP白名單的實操閉環(huán)2.1 金融機(jī)構(gòu)編碼與機(jī)構(gòu)身份綁定為什么Z2026742000018不能填錯一位網(wǎng)聯(lián)平臺所有接口調(diào)用的身份校驗不依賴API Key或AppID而直接錨定「金融機(jī)構(gòu)編碼」這一央行頒發(fā)的唯一標(biāo)識。以示例中的Z2026742000018為例其結(jié)構(gòu)為Z表示非銀行支付機(jī)構(gòu)區(qū)別于銀行類B開頭2026742機(jī)構(gòu)注冊地行政區(qū)劃代碼武漢東湖新技術(shù)開發(fā)區(qū)000018該區(qū)域內(nèi)機(jī)構(gòu)序號提示該編碼需與你在網(wǎng)聯(lián)自助驗證平臺注冊時提交的《支付業(yè)務(wù)許可證》信息完全一致。若曾變更過公司名稱或注冊地址務(wù)必確認(rèn)許可證副本上的編碼未更新否則證書申請會因主體不一致被拒。實際操作中該編碼將嵌入以下兩處關(guān)鍵位置HTTP Header 中的X-Inst-Code字段所有網(wǎng)聯(lián)交易請求必傳SFTP 對賬文件命名規(guī)則如Z2026742000018_20240520.zip若漏傳或錯傳網(wǎng)聯(lián)網(wǎng)關(guān)返回{code:INVALID_INST_CODE,msg:機(jī)構(gòu)編碼無效}且不記錄日志——這意味著你查Nginx access log或業(yè)務(wù)日志都看不到失敗痕跡只能靠抓包確認(rèn)Header是否攜帶。2.2 聯(lián)調(diào)測試證書RSA vs SM2選型決策與序列號填坑指南文檔明確標(biāo)注「√RSA □SM2」但這不是勾選題而是合規(guī)性前置判斷RSA適用于已具備國密改造計劃但尚未落地的機(jī)構(gòu)兼容性高調(diào)試工具鏈成熟OpenSSL、Postman均原生支持SM2強(qiáng)制用于新接入機(jī)構(gòu)或金融監(jiān)管重點(diǎn)檢查場景需額外部署國密SSL庫如gmssl且網(wǎng)聯(lián)側(cè)SM2證書分加簽證書序列號4000227191與加密證書序列號4000227192二者不可混用關(guān)鍵動作不是“選算法”而是確認(rèn)證書序列號歸屬注意文檔強(qiáng)調(diào)“收單機(jī)構(gòu)的證書序列號 ≠ 網(wǎng)聯(lián)的證書序列號”。你填在聯(lián)調(diào)配置表里的4002481432必須是你自己在自助驗證平臺申請并下載的私鑰對應(yīng)證書的序列號而非網(wǎng)聯(lián)提供的4000068829RSA或4000227191SM2加簽。抄錯會導(dǎo)致簽名驗簽失敗網(wǎng)聯(lián)返回{code:SIGN_VERIFY_FAIL,msg:簽名驗證失敗}。實操步驟以RSA為例登錄自助驗證平臺https://221.122.73.123/login進(jìn)入【證書管理】→【申請測試證書】→選擇RSA算法 → 提交下載.pfx文件含私鑰和.cer文件公鑰用OpenSSL提取序列號openssl x509 -in ./ca.cer -noout -serial # 輸出serial4002481432將該序列號填入聯(lián)調(diào)配置表「聯(lián)調(diào)測試證書序列號」欄若跳過第4步直接抄證書文件名如cert_4002481432.cer而實際證書序列號為4002481433常見于證書重發(fā)場景則簽名永遠(yuǎn)無法通過網(wǎng)聯(lián)驗簽。2.3 源IP白名單為什么必須一次性報全12個IP且不能含內(nèi)網(wǎng)地址網(wǎng)聯(lián)聯(lián)調(diào)環(huán)境采用雙向白名單機(jī)制你訪問網(wǎng)聯(lián)221.122.73.120:9443等需開放源IP白名單網(wǎng)聯(lián)回調(diào)你交易完成通知需你開放目標(biāo)IP白名單221.122.73.98文檔列出12個測試源IP103.25.21.32–103.25.21.45其中1103.25.21.38疑似筆誤應(yīng)為103.25.21.38這不是“可選范圍”而是網(wǎng)聯(lián)側(cè)負(fù)載均衡節(jié)點(diǎn)列表。若你只報了其中3個IP其余9個節(jié)點(diǎn)發(fā)出的請求將被防火墻直接丟棄表現(xiàn)為部分請求成功命中已白名單IP部分請求超時命中未白名單IP無響應(yīng)日志顯示“connection refused”而非“timeout”更隱蔽的坑在于禁止使用NAT后的真實出口IP。例如你服務(wù)器內(nèi)網(wǎng)IP為192.168.1.100經(jīng)NAT后出口為103.25.21.32則必須填寫103.25.21.32而非192.168.1.100。網(wǎng)聯(lián)網(wǎng)關(guān)校驗的是TCP連接建立時SYN包的源IPNAT設(shè)備若未開啟SNAT或MASQUERADE真實源IP仍為內(nèi)網(wǎng)地址導(dǎo)致白名單失效。驗證方法在服務(wù)器執(zhí)行curl -v https://221.122.73.120:9443/gateway/wechat/unifiedorder 21 | grep Connected to # 正常應(yīng)顯示Connected to 221.122.73.120 (221.122.73.120) port 9443 (#0) # 若顯示Failed to connect to 221.122.73.120 port 9443: Connection refused → 白名單未生效3. 網(wǎng)聯(lián)平臺側(cè)聯(lián)調(diào)地址解析從統(tǒng)一下單到SFTP對賬的協(xié)議級約束3.1 微信統(tǒng)一下單接口HTTPS 雙向TLS 回調(diào)地址IP硬限制網(wǎng)聯(lián)提供的微信統(tǒng)一下單地址https://221.122.73.120:9443/gateway/wechat/unifiedorder表面看是標(biāo)準(zhǔn)HTTPS實則隱含三層協(xié)議約束端口強(qiáng)制9443非443且網(wǎng)聯(lián)未提供HTTP重定向直接訪問http://或https://:443均返回400 Bad Request雙向TLS認(rèn)證除客戶端證書即你申請的4002481432證書外網(wǎng)聯(lián)服務(wù)端證書由CNnetunion-gateway簽發(fā)需在客戶端信任該CA證書鏈中包含NETUNION ROOT CA回調(diào)地址notify_url必須為IP微信側(cè)要求notify_url參數(shù)值為https://103.25.21.32:8443/callback若填https://pay.yourdomain.com/callback網(wǎng)聯(lián)網(wǎng)關(guān)在構(gòu)造微信請求時會直接拒絕返回{code:INVALID_NOTIFY_URL,msg:回調(diào)地址格式錯誤}實操中易錯點(diǎn)開發(fā)環(huán)境用localhost或127.0.0.1測試上線時未替換為白名單IP → 回調(diào)失敗Nginx反向代理配置中proxy_set_header Host $host未改為proxy_set_header Host 103.25.21.32→ 微信回調(diào)時Host頭為域名網(wǎng)聯(lián)校驗不通過3.2 SFTP對賬通道為何22端口獨(dú)立白名單且不走HTTPS網(wǎng)聯(lián)對賬文件傳輸不使用HTTPS API而采用SFTP協(xié)議SSH File Transfer Protocol地址為221.122.73.126:22這帶來三個硬性要求22端口需單獨(dú)開通白名單與交易API的9443端口白名單無關(guān)必須向網(wǎng)聯(lián)提交221.122.73.126的22端口訪問權(quán)限申請SFTP用戶憑證非HTTP Token需在自助驗證平臺生成SFTP專用賬號格式如Z2026742000018_sftp及密碼該密碼與證書密碼無關(guān)文件命名與解密強(qiáng)綁定下載的Z2026742000018_20240520.zip需用網(wǎng)聯(lián)提供的SM4密鑰解密密鑰通過自助平臺下載而非證書私鑰典型錯誤流程用OpenSSL私鑰解壓zip → 報錯invalid password以為密碼是證書密碼 → 浪費(fèi)2小時實際應(yīng)下載sm4_key_20240520.dat用gmssl sm4 -d -in Z2026742000018_20240520.zip -out data.csv -keyfile sm4_key_20240520.dat3.3 支付寶交易地址看似簡單卻卡在證書鏈驗證支付寶接口地址https://221.122.73.120:9443/gateway/alipay表面與微信同域但支付寶側(cè)要求客戶端證書必須包含完整證書鏈僅上傳.cer文件不夠需合并CA證書NETUNION ROOT CA.cer到同一PEM文件HTTP Header 必須帶X-Channel-Type: ALIPAY否則網(wǎng)關(guān)路由至微信通道返回{code:UNSUPPORTED_CHANNEL,msg:不支持的渠道類型}驗證證書鏈完整性命令openssl s_client -connect 221.122.73.120:9443 -servername 221.122.73.120 -cert ./client.pem -key ./client.key 2/dev/null | openssl x509 -noout -text | grep Issuer: # 正常應(yīng)顯示Issuer: CNNETUNION ROOT CA # 若顯示Issuer: CNyour-company-CA → 證書鏈缺失4. 常見問題排查12個IP白名單已開為什么還連不上4.1 現(xiàn)象curl測試返回curl: (35) SSL connect error原因客戶端證書未正確加載或證書私鑰密碼錯誤。網(wǎng)聯(lián)網(wǎng)關(guān)在TLS握手階段即斷開不進(jìn)入HTTP層。解決確認(rèn).pfx導(dǎo)出時勾選“包括所有證書到證書鏈”用openssl pkcs12 -info -in cert.pfx驗證私鑰密碼在curl中顯式指定證書和私鑰curl --cert ./client.pem --key ./client.key --cacert ./ca.pem \ -H X-Inst-Code: Z2026742000018 \ https://221.122.73.120:9443/gateway/wechat/unifiedorder4.2 現(xiàn)象SFTP連接成功但ls命令無響應(yīng)或get超時原因網(wǎng)聯(lián)SFTP服務(wù)啟用SFTP Subsystem而非SCP部分老舊SFTP客戶端如FileZilla舊版默認(rèn)使用SCP協(xié)議。解決FileZilla中【編輯】→【設(shè)置】→【連接】→【SFTP】→【添加密鑰文件】→ 選擇id_rsa非證書或改用命令行scp替代scp -P 22 -i ./sftp_key Z2026742000018_sftp221.122.73.126:/home/ftp/in/Z2026742000018_20240520.zip .4.3 現(xiàn)象交易成功但收不到transaction_complete回調(diào)原因回調(diào)地址雖為IP但服務(wù)器未監(jiān)聽該IP的443端口或防火墻攔截。網(wǎng)聯(lián)回調(diào)源IP固定為221.122.73.98需在你服務(wù)器放行該IP的443端口入站。解決iptables -L INPUT -n | grep 221.122.73.98確認(rèn)規(guī)則存在netstat -tlnp | grep :443確認(rèn)Web服務(wù)綁定0.0.0.0:443而非127.0.0.1:443用tcpdump -i any port 443 and host 221.122.73.98抓包確認(rèn)請求是否到達(dá)4.4 現(xiàn)象退款接口返回{code:INVALID_SIGN,msg:簽名參數(shù)錯誤}原因微信退款要求sign_typeHMAC-SHA256但網(wǎng)聯(lián)網(wǎng)關(guān)強(qiáng)制轉(zhuǎn)換為RSA簽名且簽名原文需按網(wǎng)聯(lián)規(guī)范排序非微信原始順序。解決不直接復(fù)用微信SDK的generateSign()而用網(wǎng)聯(lián)提供的Java簽名工具類NetUnionSignUtil.sign()關(guān)鍵參數(shù)順序必須為appid、mch_id、nonce_str、out_refund_no、out_trade_no、refund_fee、total_fee、transaction_id缺一不可順序不可變4.5 現(xiàn)象自助驗證平臺登錄后空白頁F12顯示net::ERR_CERT_DATE_INVALID原因平臺地址https://221.122.73.123/login使用自簽名證書且有效期截至2023年。瀏覽器拒絕加載。解決Chrome地址欄輸入thisisunsafe無需回車頁面自動刷新或臨時導(dǎo)入網(wǎng)聯(lián)根證書下載NETUNION ROOT CA.cer→ Chrome【設(shè)置】→【隱私和安全】→【安全】→【管理證書】→【受信任的根證書頒發(fā)機(jī)構(gòu)】→【導(dǎo)入】5. 聯(lián)調(diào)環(huán)境驗證技巧用三組curl命令快速定位90%的問題5.1 TLS握手層驗證確認(rèn)證書與白名單雙生效執(zhí)行以下命令觀察輸出中Verify return code和CONNECTED狀態(tài)openssl s_client -connect 221.122.73.120:9443 \ -servername 221.122.73.120 \ -cert ./client.pem \ -key ./client.key \ -CAfile ./ca.pem \ -verify_hostname 221.122.73.120 21 | grep -E (Verify return|CONNECTED|subject|issuer)? 正常輸出Verify return code: 0 (ok)CONNECTED(00000003)subjectCN Z2026742000018? 異常Verify return code: 21 (unable to verify the first certificate)→ CA證書未加載? 異常CONNECTED(00000000)→ 白名單未開或IP不對5.2 HTTP協(xié)議層驗證繞過業(yè)務(wù)邏輯直擊網(wǎng)關(guān)路由構(gòu)造最簡請求僅驗證網(wǎng)關(guān)是否接收curl -k -X POST \ -H Content-Type: application/json \ -H X-Inst-Code: Z2026742000018 \ -d {mch_id:Z2026742000018} \ https://221.122.73.120:9443/gateway/wechat/unifiedorder? 返回{code:MISSING_PARAM,msg:缺少必要參數(shù)}→ 網(wǎng)關(guān)已接收參數(shù)校驗層生效? 返回curl: (7) Failed to connect to 221.122.73.120 port 9443: Connection refused→ 白名單或防火墻問題? 返回{code:CERT_NOT_FOUND,msg:未找到對應(yīng)證書}→ 證書序列號未在網(wǎng)聯(lián)后臺注冊5.3 業(yè)務(wù)邏輯層驗證用預(yù)置測試用例觸發(fā)真實交易流網(wǎng)聯(lián)提供固定測試商戶號1900000109和測試密鑰893423DCD2344A13358182ECF7AB0001構(gòu)造統(tǒng)一下單請求curl -k -X POST \ -H Content-Type: application/json \ -H X-Inst-Code: Z2026742000018 \ -d { appid: wx1234567890, mch_id: 1900000109, nonce_str: a1b2c3d4e5f67890, body: test, out_trade_no: TEST$(date %s), total_fee: 1, spbill_create_ip: 103.25.21.32, notify_url: https://103.25.21.32:8443/callback, trade_type: NATIVE } \ https://221.122.73.120:9443/gateway/wechat/unifiedorder? 返回{code:SUCCESS,result_code:SUCCESS,code_url:weixin://...}→ 全鏈路打通? 返回{code:INVALID_MCH_ID,msg:商戶號無效}→ 未在網(wǎng)聯(lián)后臺開通測試商戶權(quán)限從那以后我每次啟動聯(lián)調(diào)都強(qiáng)制走一遍這三組curl先openssl s_client看證書再curl -H X-Inst-Code看網(wǎng)關(guān)最后用測試商戶號跑通一筆NATIVE下單。少一個環(huán)節(jié)后面三天都在查日志。這份指引不是讓你讀完就懂而是給你一張可逐項打鉤的檢查清單——白名單、證書、IP、回調(diào)地址四者缺一不可。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取 網(wǎng)聯(lián)條碼支付聯(lián)調(diào)三重校驗：IP白名單、證書序列號與回調(diào)地址硬約束
簡介本資源是《網(wǎng)聯(lián)條碼支付收單機(jī)構(gòu)聯(lián)調(diào)環(huán)境接入指引》官方文檔2018年5月版面向互聯(lián)網(wǎng)支付領(lǐng)域收單機(jī)構(gòu)的技術(shù)對接人員與系統(tǒng)集成工程師解決條碼支付系統(tǒng)聯(lián)調(diào)接入中的身份認(rèn)證、網(wǎng)絡(luò)白名單配置、接口地址調(diào)用及證書管理等核心問題。文檔為單文件Word格式.docx共1個文件大小96KB內(nèi)容結(jié)構(gòu)清晰涵蓋收單機(jī)構(gòu)基本信息填報規(guī)范、12組測試源IP白名單要求、支付寶/微信全鏈路交易接口統(tǒng)一下單、退款查詢等及SFTP對賬地址、證書序列號申請流程與HTTPS回調(diào)約束等實操要點(diǎn)。目前已有173人學(xué)習(xí)下載讀者可直接獲取標(biāo)準(zhǔn)化接入?yún)?shù)模板、平臺側(cè)聯(lián)調(diào)地址清單、簽名算法選型建議RSA/SM2、自助驗證平臺入口及關(guān)鍵注意事項如僅支持IP回調(diào)、需一次性提交全部測試IP大幅降低聯(lián)調(diào)環(huán)境部署門檻保障合規(guī)高效接入網(wǎng)聯(lián)條碼支付體系。1. 網(wǎng)聯(lián)條碼支付收單機(jī)構(gòu)聯(lián)調(diào)環(huán)境接入指引不是說明書是收單系統(tǒng)上線前的「白名單證書IP」三重校驗清單你手上有微信/支付寶掃碼收單能力也跑通了自家商戶進(jìn)件、訂單生成、支付回調(diào)但一連網(wǎng)聯(lián)聯(lián)調(diào)環(huán)境就卡在「403 Forbidden」或「SSL handshake failed」——不是代碼寫錯了而是你根本沒看清這份《網(wǎng)聯(lián)條碼支付_收單機(jī)構(gòu)聯(lián)調(diào)環(huán)境接入指引_20180504_1030.docx》里埋的三個硬性準(zhǔn)入條件白名單IP必須一次性報全、證書序列號不能抄錯位、回調(diào)地址連域名都不讓用。這不是開發(fā)文檔是網(wǎng)聯(lián)側(cè)對收單機(jī)構(gòu)網(wǎng)絡(luò)身份、密鑰體系、通信路徑的聯(lián)合校驗單。它不教你寫Java還是Python只告訴你哪幾個IP要提前備案、哪個證書序列號該填在哪張表、為什么用SFTP對賬卻要單獨(dú)開22端口白名單、以及為什么你測試時能下單卻收不到交易完成通知——八成是HTTPS回調(diào)地址寫了域名而非IP。適合正在對接網(wǎng)聯(lián)條碼支付的收單技術(shù)負(fù)責(zé)人、支付中臺工程師、以及被業(yè)務(wù)方催著“下周必須過聯(lián)調(diào)”的后端同學(xué)。別急著寫接口先拿這份指引核對你的網(wǎng)絡(luò)拓?fù)浜兔荑€管理流程。2. 收單機(jī)構(gòu)側(cè)準(zhǔn)入準(zhǔn)備從金融機(jī)構(gòu)編碼到源IP白名單的實操閉環(huán)2.1 金融機(jī)構(gòu)編碼與機(jī)構(gòu)身份綁定為什么Z2026742000018不能填錯一位網(wǎng)聯(lián)平臺所有接口調(diào)用的身份校驗不依賴API Key或AppID而直接錨定「金融機(jī)構(gòu)編碼」這一央行頒發(fā)的唯一標(biāo)識。以示例中的Z2026742000018為例其結(jié)構(gòu)為Z表示非銀行支付機(jī)構(gòu)區(qū)別于銀行類B開頭2026742機(jī)構(gòu)注冊地行政區(qū)劃代碼武漢東湖新技術(shù)開發(fā)區(qū)000018該區(qū)域內(nèi)機(jī)構(gòu)序號提示該編碼需與你在網(wǎng)聯(lián)自助驗證平臺注冊時提交的《支付業(yè)務(wù)許可證》信息完全一致。若曾變更過公司名稱或注冊地址務(wù)必確認(rèn)許可證副本上的編碼未更新否則證書申請會因主體不一致被拒。實際操作中該編碼將嵌入以下兩處關(guān)鍵位置HTTP Header 中的X-Inst-Code字段所有網(wǎng)聯(lián)交易請求必傳SFTP 對賬文件命名規(guī)則如Z2026742000018_20240520.zip若漏傳或錯傳網(wǎng)聯(lián)網(wǎng)關(guān)返回{code:INVALID_INST_CODE,msg:機(jī)構(gòu)編碼無效}且不記錄日志——這意味著你查Nginx access log或業(yè)務(wù)日志都看不到失敗痕跡只能靠抓包確認(rèn)Header是否攜帶。2.2 聯(lián)調(diào)測試證書RSA vs SM2選型決策與序列號填坑指南文檔明確標(biāo)注「√RSA □SM2」但這不是勾選題而是合規(guī)性前置判斷RSA適用于已具備國密改造計劃但尚未落地的機(jī)構(gòu)兼容性高調(diào)試工具鏈成熟OpenSSL、Postman均原生支持SM2強(qiáng)制用于新接入機(jī)構(gòu)或金融監(jiān)管重點(diǎn)檢查場景需額外部署國密SSL庫如gmssl且網(wǎng)聯(lián)側(cè)SM2證書分加簽證書序列號4000227191與加密證書序列號4000227192二者不可混用關(guān)鍵動作不是“選算法”而是確認(rèn)證書序列號歸屬注意文檔強(qiáng)調(diào)“收單機(jī)構(gòu)的證書序列號 ≠ 網(wǎng)聯(lián)的證書序列號”。你填在聯(lián)調(diào)配置表里的4002481432必須是你自己在自助驗證平臺申請并下載的私鑰對應(yīng)證書的序列號而非網(wǎng)聯(lián)提供的4000068829RSA或4000227191SM2加簽。抄錯會導(dǎo)致簽名驗簽失敗網(wǎng)聯(lián)返回{code:SIGN_VERIFY_FAIL,msg:簽名驗證失敗}。實操步驟以RSA為例登錄自助驗證平臺https://221.122.73.123/login進(jìn)入【證書管理】→【申請測試證書】→選擇RSA算法 → 提交下載.pfx文件含私鑰和.cer文件公鑰用OpenSSL提取序列號openssl x509 -in ./ca.cer -noout -serial # 輸出serial4002481432將該序列號填入聯(lián)調(diào)配置表「聯(lián)調(diào)測試證書序列號」欄若跳過第4步直接抄證書文件名如cert_4002481432.cer而實際證書序列號為4002481433常見于證書重發(fā)場景則簽名永遠(yuǎn)無法通過網(wǎng)聯(lián)驗簽。2.3 源IP白名單為什么必須一次性報全12個IP且不能含內(nèi)網(wǎng)地址網(wǎng)聯(lián)聯(lián)調(diào)環(huán)境采用雙向白名單機(jī)制你訪問網(wǎng)聯(lián)221.122.73.120:9443等需開放源IP白名單網(wǎng)聯(lián)回調(diào)你交易完成通知需你開放目標(biāo)IP白名單221.122.73.98文檔列出12個測試源IP103.25.21.32–103.25.21.45其中1103.25.21.38疑似筆誤應(yīng)為103.25.21.38這不是“可選范圍”而是網(wǎng)聯(lián)側(cè)負(fù)載均衡節(jié)點(diǎn)列表。若你只報了其中3個IP其余9個節(jié)點(diǎn)發(fā)出的請求將被防火墻直接丟棄表現(xiàn)為部分請求成功命中已白名單IP部分請求超時命中未白名單IP無響應(yīng)日志顯示“connection refused”而非“timeout”更隱蔽的坑在于禁止使用NAT后的真實出口IP。例如你服務(wù)器內(nèi)網(wǎng)IP為192.168.1.100經(jīng)NAT后出口為103.25.21.32則必須填寫103.25.21.32而非192.168.1.100。網(wǎng)聯(lián)網(wǎng)關(guān)校驗的是TCP連接建立時SYN包的源IPNAT設(shè)備若未開啟SNAT或MASQUERADE真實源IP仍為內(nèi)網(wǎng)地址導(dǎo)致白名單失效。驗證方法在服務(wù)器執(zhí)行curl -v https://221.122.73.120:9443/gateway/wechat/unifiedorder 21 | grep Connected to # 正常應(yīng)顯示Connected to 221.122.73.120 (221.122.73.120) port 9443 (#0) # 若顯示Failed to connect to 221.122.73.120 port 9443: Connection refused → 白名單未生效3. 網(wǎng)聯(lián)平臺側(cè)聯(lián)調(diào)地址解析從統(tǒng)一下單到SFTP對賬的協(xié)議級約束3.1 微信統(tǒng)一下單接口HTTPS 雙向TLS 回調(diào)地址IP硬限制網(wǎng)聯(lián)提供的微信統(tǒng)一下單地址https://221.122.73.120:9443/gateway/wechat/unifiedorder表面看是標(biāo)準(zhǔn)HTTPS實則隱含三層協(xié)議約束端口強(qiáng)制9443非443且網(wǎng)聯(lián)未提供HTTP重定向直接訪問http://或https://:443均返回400 Bad Request雙向TLS認(rèn)證除客戶端證書即你申請的4002481432證書外網(wǎng)聯(lián)服務(wù)端證書由CNnetunion-gateway簽發(fā)需在客戶端信任該CA證書鏈中包含NETUNION ROOT CA回調(diào)地址notify_url必須為IP微信側(cè)要求notify_url參數(shù)值為https://103.25.21.32:8443/callback若填https://pay.yourdomain.com/callback網(wǎng)聯(lián)網(wǎng)關(guān)在構(gòu)造微信請求時會直接拒絕返回{code:INVALID_NOTIFY_URL,msg:回調(diào)地址格式錯誤}實操中易錯點(diǎn)開發(fā)環(huán)境用localhost或127.0.0.1測試上線時未替換為白名單IP → 回調(diào)失敗Nginx反向代理配置中proxy_set_header Host $host未改為proxy_set_header Host 103.25.21.32→ 微信回調(diào)時Host頭為域名網(wǎng)聯(lián)校驗不通過3.2 SFTP對賬通道為何22端口獨(dú)立白名單且不走HTTPS網(wǎng)聯(lián)對賬文件傳輸不使用HTTPS API而采用SFTP協(xié)議SSH File Transfer Protocol地址為221.122.73.126:22這帶來三個硬性要求22端口需單獨(dú)開通白名單與交易API的9443端口白名單無關(guān)必須向網(wǎng)聯(lián)提交221.122.73.126的22端口訪問權(quán)限申請SFTP用戶憑證非HTTP Token需在自助驗證平臺生成SFTP專用賬號格式如Z2026742000018_sftp及密碼該密碼與證書密碼無關(guān)文件命名與解密強(qiáng)綁定下載的Z2026742000018_20240520.zip需用網(wǎng)聯(lián)提供的SM4密鑰解密密鑰通過自助平臺下載而非證書私鑰典型錯誤流程用OpenSSL私鑰解壓zip → 報錯invalid password以為密碼是證書密碼 → 浪費(fèi)2小時實際應(yīng)下載sm4_key_20240520.dat用gmssl sm4 -d -in Z2026742000018_20240520.zip -out data.csv -keyfile sm4_key_20240520.dat3.3 支付寶交易地址看似簡單卻卡在證書鏈驗證支付寶接口地址https://221.122.73.120:9443/gateway/alipay表面與微信同域但支付寶側(cè)要求客戶端證書必須包含完整證書鏈僅上傳.cer文件不夠需合并CA證書NETUNION ROOT CA.cer到同一PEM文件HTTP Header 必須帶X-Channel-Type: ALIPAY否則網(wǎng)關(guān)路由至微信通道返回{code:UNSUPPORTED_CHANNEL,msg:不支持的渠道類型}驗證證書鏈完整性命令openssl s_client -connect 221.122.73.120:9443 -servername 221.122.73.120 -cert ./client.pem -key ./client.key 2/dev/null | openssl x509 -noout -text | grep Issuer: # 正常應(yīng)顯示Issuer: CNNETUNION ROOT CA # 若顯示Issuer: CNyour-company-CA → 證書鏈缺失4. 常見問題排查12個IP白名單已開為什么還連不上4.1 現(xiàn)象curl測試返回curl: (35) SSL connect error原因客戶端證書未正確加載或證書私鑰密碼錯誤。網(wǎng)聯(lián)網(wǎng)關(guān)在TLS握手階段即斷開不進(jìn)入HTTP層。解決確認(rèn).pfx導(dǎo)出時勾選“包括所有證書到證書鏈”用openssl pkcs12 -info -in cert.pfx驗證私鑰密碼在curl中顯式指定證書和私鑰curl --cert ./client.pem --key ./client.key --cacert ./ca.pem \ -H X-Inst-Code: Z2026742000018 \ https://221.122.73.120:9443/gateway/wechat/unifiedorder4.2 現(xiàn)象SFTP連接成功但ls命令無響應(yīng)或get超時原因網(wǎng)聯(lián)SFTP服務(wù)啟用SFTP Subsystem而非SCP部分老舊SFTP客戶端如FileZilla舊版默認(rèn)使用SCP協(xié)議。解決FileZilla中【編輯】→【設(shè)置】→【連接】→【SFTP】→【添加密鑰文件】→ 選擇id_rsa非證書或改用命令行scp替代scp -P 22 -i ./sftp_key Z2026742000018_sftp221.122.73.126:/home/ftp/in/Z2026742000018_20240520.zip .4.3 現(xiàn)象交易成功但收不到transaction_complete回調(diào)原因回調(diào)地址雖為IP但服務(wù)器未監(jiān)聽該IP的443端口或防火墻攔截。網(wǎng)聯(lián)回調(diào)源IP固定為221.122.73.98需在你服務(wù)器放行該IP的443端口入站。解決iptables -L INPUT -n | grep 221.122.73.98確認(rèn)規(guī)則存在netstat -tlnp | grep :443確認(rèn)Web服務(wù)綁定0.0.0.0:443而非127.0.0.1:443用tcpdump -i any port 443 and host 221.122.73.98抓包確認(rèn)請求是否到達(dá)4.4 現(xiàn)象退款接口返回{code:INVALID_SIGN,msg:簽名參數(shù)錯誤}原因微信退款要求sign_typeHMAC-SHA256但網(wǎng)聯(lián)網(wǎng)關(guān)強(qiáng)制轉(zhuǎn)換為RSA簽名且簽名原文需按網(wǎng)聯(lián)規(guī)范排序非微信原始順序。解決不直接復(fù)用微信SDK的generateSign()而用網(wǎng)聯(lián)提供的Java簽名工具類NetUnionSignUtil.sign()關(guān)鍵參數(shù)順序必須為appid、mch_id、nonce_str、out_refund_no、out_trade_no、refund_fee、total_fee、transaction_id缺一不可順序不可變4.5 現(xiàn)象自助驗證平臺登錄后空白頁F12顯示net::ERR_CERT_DATE_INVALID原因平臺地址https://221.122.73.123/login使用自簽名證書且有效期截至2023年。瀏覽器拒絕加載。解決Chrome地址欄輸入thisisunsafe無需回車頁面自動刷新或臨時導(dǎo)入網(wǎng)聯(lián)根證書下載NETUNION ROOT CA.cer→ Chrome【設(shè)置】→【隱私和安全】→【安全】→【管理證書】→【受信任的根證書頒發(fā)機(jī)構(gòu)】→【導(dǎo)入】5. 聯(lián)調(diào)環(huán)境驗證技巧用三組curl命令快速定位90%的問題5.1 TLS握手層驗證確認(rèn)證書與白名單雙生效執(zhí)行以下命令觀察輸出中Verify return code和CONNECTED狀態(tài)openssl s_client -connect 221.122.73.120:9443 \ -servername 221.122.73.120 \ -cert ./client.pem \ -key ./client.key \ -CAfile ./ca.pem \ -verify_hostname 221.122.73.120 21 | grep -E (Verify return|CONNECTED|subject|issuer)? 正常輸出Verify return code: 0 (ok)CONNECTED(00000003)subjectCN Z2026742000018? 異常Verify return code: 21 (unable to verify the first certificate)→ CA證書未加載? 異常CONNECTED(00000000)→ 白名單未開或IP不對5.2 HTTP協(xié)議層驗證繞過業(yè)務(wù)邏輯直擊網(wǎng)關(guān)路由構(gòu)造最簡請求僅驗證網(wǎng)關(guān)是否接收curl -k -X POST \ -H Content-Type: application/json \ -H X-Inst-Code: Z2026742000018 \ -d {mch_id:Z2026742000018} \ https://221.122.73.120:9443/gateway/wechat/unifiedorder? 返回{code:MISSING_PARAM,msg:缺少必要參數(shù)}→ 網(wǎng)關(guān)已接收參數(shù)校驗層生效? 返回curl: (7) Failed to connect to 221.122.73.120 port 9443: Connection refused→ 白名單或防火墻問題? 返回{code:CERT_NOT_FOUND,msg:未找到對應(yīng)證書}→ 證書序列號未在網(wǎng)聯(lián)后臺注冊5.3 業(yè)務(wù)邏輯層驗證用預(yù)置測試用例觸發(fā)真實交易流網(wǎng)聯(lián)提供固定測試商戶號1900000109和測試密鑰893423DCD2344A13358182ECF7AB0001構(gòu)造統(tǒng)一下單請求curl -k -X POST \ -H Content-Type: application/json \ -H X-Inst-Code: Z2026742000018 \ -d { appid: wx1234567890, mch_id: 1900000109, nonce_str: a1b2c3d4e5f67890, body: test, out_trade_no: TEST$(date %s), total_fee: 1, spbill_create_ip: 103.25.21.32, notify_url: https://103.25.21.32:8443/callback, trade_type: NATIVE } \ https://221.122.73.120:9443/gateway/wechat/unifiedorder? 返回{code:SUCCESS,result_code:SUCCESS,code_url:weixin://...}→ 全鏈路打通? 返回{code:INVALID_MCH_ID,msg:商戶號無效}→ 未在網(wǎng)聯(lián)后臺開通測試商戶權(quán)限從那以后我每次啟動聯(lián)調(diào)都強(qiáng)制走一遍這三組curl先openssl s_client看證書再curl -H X-Inst-Code看網(wǎng)關(guān)最后用測試商戶號跑通一筆NATIVE下單。少一個環(huán)節(jié)后面三天都在查日志。這份指引不是讓你讀完就懂而是給你一張可逐項打鉤的檢查清單——白名單、證書、IP、回調(diào)地址四者缺一不可。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取