簡介本資源是《網(wǎng)聯(lián)條碼支付收單機構(gòu)聯(lián)調(diào)環(huán)境接入指引》官方文檔2018年5月版面向互聯(lián)網(wǎng)支付領(lǐng)域收單機構(gòu)的技術(shù)對接人員與系統(tǒng)集成工程師解決條碼支付系統(tǒng)聯(lián)調(diào)接入中的身份認證、網(wǎng)絡(luò)白名單配置、接口地址調(diào)用及證書管理等核心問題。文檔為單文件Word格式.docx共1個文件大小96KB內(nèi)容結(jié)構(gòu)清晰涵蓋收單機構(gòu)基本信息填報規(guī)范、12組測試源IP白名單要求、支付寶/微信全鏈路交易接口統(tǒng)一下單、退款查詢等及SFTP對賬地址、證書序列號申請流程與HTTPS回調(diào)約束等實操要點。目前已有173人學習下載讀者可直接獲取標準化接入?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)條碼支付收單機構(gòu)聯(lián)調(diào)環(huán)境接入指引不是說明書是收單系統(tǒng)上線前的「白名單證書IP」三重校驗清單你手上有微信/支付寶掃碼收單能力也跑通了自家商戶進件、訂單生成、支付回調(diào)但一連網(wǎng)聯(lián)聯(lián)調(diào)環(huán)境就卡在「403 Forbidden」或「SSL handshake failed」——不是代碼寫錯了而是你根本沒看清這份《網(wǎng)聯(lián)條碼支付_收單機構(gòu)聯(lián)調(diào)環(huán)境接入指引_20180504_1030.docx》里埋的三個硬性準入條件白名單IP必須一次性報全、證書序列號不能抄錯位、回調(diào)地址連域名都不讓用。這不是開發(fā)文檔是網(wǎng)聯(lián)側(cè)對收單機構(gòu)網(wǎng)絡(luò)身份、密鑰體系、通信路徑的聯(lián)合校驗單。它不教你寫Java還是Python只告訴你哪幾個IP要提前備案、哪個證書序列號該填在哪張表、為什么用SFTP對賬卻要單獨開22端口白名單、以及為什么你測試時能下單卻收不到交易完成通知——八成是HTTPS回調(diào)地址寫了域名而非IP。適合正在對接網(wǎng)聯(lián)條碼支付的收單技術(shù)負責人、支付中臺工程師、以及被業(yè)務(wù)方催著“下周必須過聯(lián)調(diào)”的后端同學。別急著寫接口先拿這份指引核對你的網(wǎng)絡(luò)拓撲和密鑰管理流程。2. 收單機構(gòu)側(cè)準入準備從金融機構(gòu)編碼到源IP白名單的實操閉環(huán)2.1 金融機構(gòu)編碼與機構(gòu)身份綁定為什么Z2026742000018不能填錯一位網(wǎng)聯(lián)平臺所有接口調(diào)用的身份校驗不依賴API Key或AppID而直接錨定「金融機構(gòu)編碼」這一央行頒發(fā)的唯一標識。以示例中的Z2026742000018為例其結(jié)構(gòu)為Z表示非銀行支付機構(gòu)區(qū)別于銀行類B開頭2026742機構(gòu)注冊地行政區(qū)劃代碼武漢東湖新技術(shù)開發(fā)區(qū)000018該區(qū)域內(nèi)機構(gòu)序號提示該編碼需與你在網(wǎng)聯(lián)自助驗證平臺注冊時提交的《支付業(yè)務(wù)許可證》信息完全一致。若曾變更過公司名稱或注冊地址務(wù)必確認許可證副本上的編碼未更新否則證書申請會因主體不一致被拒。實際操作中該編碼將嵌入以下兩處關(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:機構(gòu)編碼無效}且不記錄日志——這意味著你查Nginx access log或業(yè)務(wù)日志都看不到失敗痕跡只能靠抓包確認Header是否攜帶。2.2 聯(lián)調(diào)測試證書RSA vs SM2選型決策與序列號填坑指南文檔明確標注「√RSA □SM2」但這不是勾選題而是合規(guī)性前置判斷RSA適用于已具備國密改造計劃但尚未落地的機構(gòu)兼容性高調(diào)試工具鏈成熟OpenSSL、Postman均原生支持SM2強制用于新接入機構(gòu)或金融監(jiān)管重點檢查場景需額外部署國密SSL庫如gmssl且網(wǎng)聯(lián)側(cè)SM2證書分加簽證書序列號4000227191與加密證書序列號4000227192二者不可混用關(guān)鍵動作不是“選算法”而是確認證書序列號歸屬注意文檔強調(diào)“收單機構(gòu)的證書序列號 ≠ 網(wǎng)聯(lián)的證書序列號”。你填在聯(lián)調(diào)配置表里的4002481432必須是你自己在自助驗證平臺申請并下載的私鑰對應(yīng)證書的序列號而非網(wǎng)聯(lián)提供的4000068829RSA或4000227191SM2加簽。抄錯會導致簽名驗簽失敗網(wǎng)聯(lián)返回{code:SIGN_VERIFY_FAIL,msg:簽名驗證失敗}。實操步驟以RSA為例登錄自助驗證平臺https://221.122.73.123/login進入【證書管理】→【申請測試證書】→選擇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ā)場景則簽名永遠無法通過網(wǎng)聯(lián)驗簽。2.3 源IP白名單為什么必須一次性報全12個IP且不能含內(nèi)網(wǎng)地址網(wǎng)聯(lián)聯(lián)調(diào)環(huán)境采用雙向白名單機制你訪問網(wǎng)聯(lián)221.122.73.120:9443等需開放源IP白名單網(wǎng)聯(lián)回調(dià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è)負載均衡節(jié)點列表。若你只報了其中3個IP其余9個節(jié)點發(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)地址導致白名單失效。驗證方法在服務(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表面看是標準HTTPS實則隱含三層協(xié)議約束端口強制9443非443且網(wǎng)聯(lián)未提供HTTP重定向直接訪問http://或https://:443均返回400 Bad Request雙向TLS認證除客戶端證書即你申請的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)地址格式錯誤}實操中易錯點開發(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端口獨立白名單且不走HTTPS網(wǎng)聯(lián)對賬文件傳輸不使用HTTPS API而采用SFTP協(xié)議SSH File Transfer Protocol地址為221.122.73.126:22這帶來三個硬性要求22端口需單獨開通白名單與交易API的9443端口白名單無關(guān)必須向網(wǎng)聯(lián)提交221.122.73.126的22端口訪問權(quán)限申請SFTP用戶憑證非HTTP Token需在自助驗證平臺生成SFTP專用賬號格式如Z2026742000018_sftp及密碼該密碼與證書密碼無關(guān)文件命名與解密強綁定下載的Z2026742000018_20240520.zip需用網(wǎng)聯(lián)提供的SM4密鑰解密密鑰通過自助平臺下載而非證書私鑰典型錯誤流程用OpenSSL私鑰解壓zip → 報錯invalid password以為密碼是證書密碼 → 浪費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握手階段即斷開不進入HTTP層。解決確認.pfx導出時勾選“包括所有證書到證書鏈”用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舊版默認使用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確認規(guī)則存在netstat -tlnp | grep :443確認Web服務(wù)綁定0.0.0.0:443而非127.0.0.1:443用tcpdump -i any port 443 and host 221.122.73.98抓包確認請求是否到達4.4 現(xiàn)象退款接口返回{code:INVALID_SIGN,msg:簽名參數(shù)錯誤}原因微信退款要求sign_typeHMAC-SHA256但網(wǎng)聯(lián)網(wǎng)關(guān)強制轉(zhuǎn)換為RSA簽名且簽名原文需按網(wǎng)聯(lián)規(guī)范排序非微信原始順序。解決不直接復用微信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無需回車頁面自動刷新或臨時導入網(wǎng)聯(lián)根證書下載NETUNION ROOT CA.cer→ Chrome【設(shè)置】→【隱私和安全】→【安全】→【管理證書】→【受信任的根證書頒發(fā)機構(gòu)】→【導入】5. 聯(lián)調(diào)環(huán)境驗證技巧用三組curl命令快速定位90%的問題5.1 TLS握手層驗證確認證書與白名單雙生效執(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ù)邏輯層驗證用預置測試用例觸發(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)都強制走一遍這三組curl先openssl s_client看證書再curl -H X-Inst-Code看網(wǎng)關(guān)最后用測試商戶號跑通一筆NATIVE下單。少一個環(huán)節(jié)后面三天都在查日志。這份指引不是讓你讀完就懂而是給你一張可逐項打鉤的檢查清單——白名單、證書、IP、回調(diào)地址四者缺一不可。希望幫到你。本文還有配套的精品資源點擊獲取