綠界金流串接的十個坑:每天在收單的團隊經驗談

綠界 ECPay 大概是台灣電商最普及的金流,文件也算齊全,但真正上線收單之後你會發現:有些坑文件沒寫清楚,有些坑文件寫了但你不會注意到,直到第一筆真實訂單卡住。我們的自營電商用綠界全家族——信用卡、超商代碼、貨到付款、超商取貨物流、Apple Pay——每天真實收單,以下十個坑,每一個都有訂單編號可以對。

串接階段的坑

1. CheckMacValue 驗證失敗,九成是編碼問題。參數要照字母序排列、URL encode 之後還要做綠界指定的字元置換(它模擬的是 .NET 的編碼行為)。自己手刻很容易在空白字元的兩種編碼寫法之間陣亡,建議直接用官方 SDK 或把置換表寫成測試案例。
2. MerchantTradeNo 一旦用過,永遠不能重用。包括「付款失敗」的那筆。使用者刷卡失敗想重試?要產一個新的交易編號,不能拿舊的再送一次。我們的做法是訂單編號與金流交易編號分離,每次送金流都產新的交易號,後綴流水碼。
3. ReturnURL 和 OrderResultURL 是兩回事。ReturnURL 是 server-to-server 的付款通知,OrderResultURL 是把消費者導回你網站的前景跳轉。訂單狀態只能信前者,千萬不要在後者更新付款狀態——消費者關掉瀏覽器,你的訂單就永遠停在「處理中」。

收單之後的坑

4. 付款通知會重送,handler 必須冪等。綠界收不到你回應成功字串「1|OK」就會重試。如果你的通知處理沒做冪等,就會出現重複發信、重複開發票、甚至重複加點數。所有跟著付款觸發的動作,都要能安全地被執行第二次。順帶提醒:通知 handler 裡任何一段後續邏輯拋出例外,都可能害你回不出成功字串,進而觸發沒必要的重送——把「確認收到通知」和「後續處理」拆開,是比較穩的架構。
5. 不要只信 callback,要主動查單。網路世界什麼都可能掉。我們遇過通知延遲十幾分鐘的情況,消費者已經在 LINE 問「我付了怎麼還沒確認」。正解是 callback 之外再加排程主動查詢訂單狀態,雙保險。
6. 超商代碼有繳費期限,逾期訂單要有出路。代碼繳費的轉換天生有流失(拿了代碼不去繳的人不少),要設計逾期自動取消、釋放庫存、以及提醒繳費的挽回訊息。沒做這段的下場是:庫存被一堆永遠不會付款的訂單卡住,活動期間尤其致命。
7. 測試環境全綠不代表正式環境會動。測試環境的卡號永遠成功、代碼不用真的去超商繳,很多流程根本沒被走到。上線前用真實金流小額跑完整條鏈路,這件事重要到我們另外寫了一篇:第一筆訂單不該是除錯現場。

物流與進階功能的坑

8. 貨到付款金額變更,沒有「修改」這個選項。消費者改訂單內容導致金額變動,物流單不能改金額,只能作廢重開——而且重開要用全新的交易編號(呼應第 2 點)。我們把「作廢重開」做成後台一鍵操作,細節寫在超商物流筆記。
9. 物流查詢 API 有版本之分。舊版查詢回來的狀態欄位不完整,我們踩過之後全面改用 V5 查詢。串接前先確認你看的文件是哪一版。
10. Apple Pay 不是打開就有。要另外申請開通、完成網域驗證,而且測試流程需要真實的 Apple 裝置。排時程時把這段申請往返算進去。

金流串接的難,不在第一筆成功的訂單,在第一筆「不照劇本走」的訂單。

這十個坑我們都是用真實訂單換來的。如果你正要串金流,或已經串了但總覺得哪裡不穩,可以參考我們的電商系統建置服務——金流、發票、物流的完整鏈路是我們每天在營運的東西,不是接案時才翻文件現學的。