ECSHOP 整合交通銀行網銀在線支付插件開發實戰

項目背景與需求

近期接手一個電商專案，需求方指定必須接入交通銀行（交行）的網銀在線支付功能。經過調研發現，ECSHOP 官方並未內建此支付方式的插件，因此決定自行開發一套完整的支付模組。開發過程中參考了交行官方提供的 Demo 文檔，並針對 ECSHOP 的架構進行了適配優化。

插件安裝前的環境準備

在部署插件前，請務必先完成交通銀行網銀支付的伺服器端環境配置。具體安裝步驟可參考交行官方 Demo，核心要點在於：正確安裝前置機程式、配置通訊埠（預設 8080）、導入商戶憑證與密鑰。環境就緒後，將插件原始碼與語言包依路徑放置，最後進入 ECSHOP 後台「支付方式」模組安裝啟用即可。

核心插件原始碼解析

插件主文件位於 includes/modules/payment/bankcomm.php，採用 ECSHOP 標準支付模組結構，包含模組資訊註冊、支付表單生成、異步通知處理三大核心功能。

1. 模組基礎資訊註冊

在 $set_modules 判斷區塊中，定義了支付代碼、描述語言項、是否支持貨到付款、在線支付標識、手續費、作者、官網、版本號等元數據。此處將 is_online 設為 1，標識為純在線支付方式。

2. 支付提交邏輯 get_code()

此方法負責組裝交行要求的報文參數，包括：介面版本號、商戶號、訂單號、下單日期時間、交易類型（B2C）、金額、幣種、通知方式、回調 URL 等。關鍵步驟：

• 將所有參數按規範用 | 拼接成源字串
• 通過 Socket 連接本地前置機（tcp://127.0.0.1:8080）發送 XML 報文
• 解析前置機返回的 XML，提取 retCode、signMsg、orderUrl 等關鍵字段
• 若返回碼非「0」則拋出錯誤，否則生成自動提交的 HTML 表單導向銀行支付頁

3. 異步通知驗證 respond()

處理交行回調通知，核心流程：

1. 從 $_REQUEST['notifyMsg'] 取得原文與簽名
2. 再次通過 Socket 發送驗證報文（cb2200_verify）至前置機
3. 解析驗證結果，若 retCode 為空則驗證通過
4. 從原文中提取訂單號 pay_id，調用 order_paid() 更新訂單狀態為已付款

語言包配置

語言文件 languages/zh_cn/payment/bankcomm.php 定義了支付方式名稱、描述及支付按鈕文字，支援多語系擴展。

前端調用範例

<?php
include_once(ROOT_PATH . 'includes/modules/payment/bankcomm.php');
$order_['orderid'] = $order['order_sn'];
$order_['amount'] = $order['yd_price'];
$order_['orderMono'] = '測試訂單備註';
$order_['goodsURL'] = "https://".$_SERVER['HTTP_HOST'].'/respond.php?code=bankcomm';
$pay_code = new bankcomm;
$pay_button = $pay_code->get_code($order_);
$order['pay_button'] = $pay_button;
?>

開發心得與注意事項

1. 前置機通訊埠 必須與銀行端配置一致，預設 8080 但實際部署時需確認。
2. 商戶號 開發測試階段可使用交行提供的測試商戶號，正式上線前需替換為正式商戶號。
3. 回調 URL 需確保外網可訪問，且不攜帶額外參數干擾驗證邏輯。
4. 錯誤處理 建議在生產環境將 echo 輸出改為日誌記錄，避免敏感資訊洩露。
5. 編碼一致性 全鏈路保持 UTF-8，特別是 orderMono 等中文字段需經 htmlentities 處理。

此插件已在實際項目中穩定運行，歡迎同行提出優化建議，共同完善 ECSHOP 的支付生態。