金流上線前的 20 項驗收清單：確保你不會忘記任何致命細節

金流上線不像一般功能部署——出了問題影響的是真金白銀。以下 20 項清單是從多個專案的實戰經驗中濃縮出來的，涵蓋四大面向。建議在上線前逐一勾選，每一項都確認後再按下部署按鈕。

【參數與環境設定】一、API 端點已從 payment-stage.ecpay.com.tw 切換為 payment.ecpay.com.tw。二、MerchantID 已更換為正式帳號，並確認該帳號已通過綠界審核且處於啟用狀態。三、HashKey 與 HashIV 已更換為正式環境的金鑰，且儲存在伺服器端的環境變數中，未寫死在程式碼或前端 Bundle 裡。四、ReturnURL 指向正式伺服器的 HTTPS 網址，走標準 443 Port，且該網址對外可訪問。五、OrderResultURL 與 ClientBackURL 均指向正式網站的對應頁面。六、如果使用站內付 2.0，確認四個環境設定（Token 端點、JS SDK 網址、初始化端點、交易端點）全部已切換到正式環境。

【付款邏輯驗證】七、每一種你支援的付款方式（信用卡、ATM、超商代碼、超商條碼、Apple Pay）都已在測試環境中完整走過一次成功付款流程。八、MerchantTradeNo 的生成邏輯確保全域唯一，長度不超過 20 個字元，且僅包含英數字。九、TotalAmount 為正整數，無小數點，且與訂單系統中的金額一致。十、ItemName 的長度不超過 400 個字元，多個商品以 # 分隔，且不包含特殊符號。十一、如果使用信用卡分期，已確認 CreditInstallment 參數中的期數已在綠界後台開通。十二、如果使用定期定額，PeriodAmount 等於 TotalAmount，且 PeriodReturnURL 已正確設定並能處理後續每期的扣款通知。

【錯誤處理與安全】十三、ReturnURL 的處理邏輯會驗證 CheckMacValue，且驗證失敗時會記錄完整的 Request Body 供事後分析，但不會更新訂單狀態。十四、ReturnURL 的處理邏輯會比對 TradeAmt 與原始訂單金額是否一致。十五、ReturnURL 的處理邏輯具備冪等性——同一筆訂單的重複通知不會造成狀態異常或重複出貨。十六、ReturnURL 在驗證通過後會立即回應純文字 1|OK，業務邏輯（發信、更新庫存等）在背景非同步執行。十七、程式碼中沒有殘留對 SimulatePaid 參數的特殊處理邏輯，或已透過環境判斷確保該邏輯在正式環境中不會觸發。

【監控與對帳】十八、設置告警機制：當 ReturnURL 回應非 200 狀態碼或處理時間超過 10 秒時，主動通知負責人。十九、設置主動對帳排程：定期使用綠界的「查詢訂單 API」掃描狀態為「待付款」超過預期時間的訂單，主動確認其實際付款狀態。二十、確認對帳檔案的解析腳本已更新，能正確處理 2025 年 4 月起新增的 ProcessFee 欄位，且以欄位名稱而非位置索引進行解析。

這份清單的設計原則是「寧可多確認一次，不可少確認一次」。金流系統的可靠度不是靠寫出漂亮的程式碼，而是靠紀律——每次上線都走一遍完整的檢查流程。把這份清單存進你的專案管理工具，讓它成為每次部署前的 Gate。