newebpay-gateway

作 品 介 紹

名 稱 ： newebpay-gateway · 藍新金流付款閘道

線 上 ： https://github.com/penink-WH/newebpay-gateway

類 型 ： 金流收款系統（PHP 5.2 + MySQL 5.x，純網頁無框架）

技 術 ： PHP 5.2 相容 / MySQL 5.x / 藍新金流 NewebPay MPG API

授 權 ： MIT License

一、這是什麼

一套「金流閘道」程式，專門解決這種需求：公司有很多網站（購物網、

會員系統、活動頁），但只有一個藍新金流的商店代號。這個程式放在中間，

讓各網站把付款需求「轉送」進來，統一收單、統一記錄。

它怎麼運作

1. 來源站台 POST 一筆付款需求過來（訂單編號、金額、品項、付款方式）

2. 系統建單，顯示付款資訊頁面給消費者看

3. 消費者按「確認付款」，依藍新規範以瀏覽器 POST 表單導向藍新 MPG 閘道

→ 線上刷卡（信用卡一次付清／分期）或 ATM 虛擬帳號

4. 藍新把結果送回來（幕後通知／前台返回／ATM 取號三個入口）

5. 系統驗簽、解密、核對金額後更新訂單，再回呼來源站台

三支主要頁面

• pay_request.php 驅動付款：接收轉送 → 顯示付款資訊 → 導向藍新
• pay_notify.php 接收付款結果：驗簽解密、更新 MySQL、回呼來源站台
• pay_query.php 交易查詢：狀態、事件時間軸、回呼紀錄、手動重送

特別設計

• 兩階段准入：先查用戶代碼／允許連入的 IP／來源網站，通過才比對簽章
• 全程留痕：收到需求、確認、導向、藍新結果、回呼成敗都寫 MySQL
• 回呼可靠：HMAC 簽章、逾時重試、逐次記錄 HTTP 與回應內容
• 防重複出貨：同一狀態不重複回呼；重複轉送同一訂單編號不會重複建單
• 防偽造：TradeSha 驗證、金額核對、timestamp 防重放
• 金額防呆：每個站台可設單筆金額上限，擋下「把分當成元」多收 100 倍的

上線事故；可疑金額另留 WARN 紀錄

• 設定診斷：後台一頁看出 HTTPS、live/test、金鑰強度、哪些站台沒設 IP 白名單
• 模擬面板：測試環境可自行產生成功／失敗／取消／取號／重複通知／

偽造通知／金額不符／回呼失敗等各種狀態，不必真的打到藍新就能自我驗證

• 雙環境：測試（ccore）／正式（core）一鍵切換

二、製作過程

1. 先讀規格，不猜

藍新官方技術手冊下載連結已失效，改以公開的規格整理與多份實作

交叉比對，確認 AES-256-CBC（32 bytes 補齊）、TradeSha、CheckValue、

CheckCode 四組演算法，避免照抄到過時的舊版 API。

2. 用「標準向量」驗證加解密

最怕的是加密寫錯卻看起來能跑。於是拿官方手冊裡的範例金鑰與請求

字串做加密，要求產出的前 16 bytes 必須等於手冊列出的值——

AES 第一個 block 只受前 16 bytes 明文影響，這個比對足以證明

金鑰、IV、cipher 選項、補齊方式全部正確。測試中真的抓到自己第一版

少了一個 0（16 bytes 補齊 vs 官方 32 bytes），靠這道標準向量抓到。

3. PHP 5.2 是硬限制

不寫 namespace、不用短陣列、不用 ?? 、不用 closure、不用 __DIR__；

AES 在 PHP 5.3 才有 openssl_encrypt，所以另外寫了 mcrypt 後端

（MCRYPT_RIJNDAEL_128 ＋ 32 碼金鑰 ＝ AES-256）。

同時讓資料庫層在 mysql_ / mysqli / PDO 之間自動切換，

同一份程式碼能跑在 5.2 與現代 PHP 上（本機測試用 PHP 8.5 驗證）。

4. 測試不能只靠「看起來對」

寫了模擬藍新（MPG 付款頁、ATM 取號、結果回呼、查詢 API）與模擬來源

站台，用 HTTP 實際呼叫跑完整條路徑，62 項斷言涵蓋正常流程與攻擊情境

（錯簽章、過期 timestamp、偽造 TradeSha、金額不符、重複通知…）。

5. 真的用瀏覽器走一遍

自動化測試之外，開瀏覽器實際操作：來源站台填單 → 確認付款 → 藍新頁 →

付款完成 → 後台明細，並截圖用視覺模型確認版面與資料無誤。

三、使用教學

安裝

0. Windows：直接雙擊 deploy\windows-deploy.cmd（會自動部署並自我檢查）

1. 上傳檔案，複製 config.sample.php 為 config.php

2. 填入資料庫、藍新商店代號／HashKey／HashIV、BASE_URL、ADMIN_PASSWORD

3. 開 install.php 建立資料表（完成後請刪除）

4. 在 pay_sources 建立來源站台（回呼網址、簽章金鑰、可回呼網域）

來源站台呼叫範例

$fields = array('source'=>'shop', 'source_order_no'=>'SO20260001',

'amount'=>480, 'pay_type'=>'both', 'timestamp'=>time());

ksort($fields); // 依 key 排序

$parts = array(); foreach ($fields as $k=>$v) $parts[] = "$k=$v";

$fields['sign'] = strtoupper(hash_hmac('sha256', implode('&',$parts), $secret));

// POST 整包到 pay_request.php，回傳 JSON 內含 order_no 與 pay_url

測試

bash _dev/run_tests.sh # 一鍵：起服務＋補資料表＋跑完 105 項測試

php _dev/test_crypto.php # 加解密標準向量 14 項

php _dev/test_e2e.php # 端對端流程 91 項（含准入管制與 RESULT 導回）

# 需要模擬藍新時，config.php 指到 _dev/mock_newebpay_gateway.php

四、注意事項

⚠ config.php 含有金鑰與密碼，務必自行建立且不可外流、不可進版控

⚠ 藍新測試帳號（4000-2211-1111-1111）與示範金鑰僅供測試，

正式收款請改用自己的商店參數與正式網址（NEWEB_ENV = live）

⚠ 上線前請做完 README〈安全注意事項與上線檢查〉的清單，並刪除 install.php、_dev/、demo/

⚠ 付款成功以幕後通知（NotifyURL）為準，前台返回（ReturnURL）僅供顯示，

兩者不可視為同一件事

⚠ 本作品僅提供程式實作，金流與資安風險由部署者自行評估與承擔

五、保存資訊

GitHub ： https://github.com/penink-WH/newebpay-gateway

授權 ： MIT License

語言 ： PHP（相容 5.2 以上）、SQL

測試 ： _dev/run_tests.sh（一鍵）、test_crypto.php（20 項）、test_e2e.php（118 項）

Windows ： deploy\windows-deploy.cmd（自動部署 + 自我檢查）

專案頁 ： https://wh-penink.pages.dev/projects/newebpay-gateway/