第三章：收錢才是硬道理 - ECPay 綠界金流串接原理與 Webhook 災難預防

在我們之前的實戰課程中，我們已經學會了如何把文章鎖起來、如何把網站變得漂亮、如何用 GA 追蹤流量。但在真實的商業 SaaS 網站中，這一切努力的最終目的只有一個：「讓使用者按下付款按鈕，進入刷卡頁面，並且在銀行扣款成功後，系統自動幫他解鎖他買的課程。」

很多新手工程師在自己練習寫 Side Project 時，都會做一個「假的結帳按鈕」，按下去跳出一個 "結帳成功" 的 Alert 就算完成了。一旦他們真的要接案、遇到需要串接「真實台灣金流 (如綠界科技 ECPay)」時，通常都會卡關一兩個禮拜，甚至因為邏輯寫錯，導致客人錢被扣了、課程卻沒開通，引發嚴重的客訴糾紛。

這章我們不寫那些複雜的 SHA256 加密程式碼 (因為那些髒活應該交給 Vibe Prompt 讓 AI 去幫我們刻)，我們要把重點放在：帶你用上帝視角，看透金流串接的底層架構與運作邏輯。

🎯 本章目標

深入理解線上金流串接的三個核心階段。
認識非同步通知 ReturnURL (Webhook) 的重要性，這是保住你商譽的關鍵。
學習如何撰寫高水準的 Vibe Prompt，讓 AI 幫你寫出符合資安標準的金流 API。

💸 金流串接的三大核心階段 (以綠界為例)

不管你是串接綠界 (ECPay)、藍新 (NewebPay) 還是國際大廠 Stripe，線上刷卡的底層邏輯都離不開這三個標準階段：

階段一：建立訂單與防偽簽章 (Create Order)

當使用者在你的網站看中了一個 $3000 元的尊榮大禮包，並滿懷期待地按下「立即購買」時，你的前端網頁絕對不能直接跳轉。

前端必須先發送一個 API 請求給你的後端 (例如 Next.js 的 Route Handler 或 FastAPI)。你的後端必須完成以下動作：

去資料庫建立一筆「未付款」狀態的訂單記錄，並產生一個絕對不重複的訂單編號 (例如 ORDER20240901001)。
拿出你存放在 .env 裡的機密 HashKey 與 HashIV (這絕對不能讓前端知道)。
把訂單資訊 (金額 3000、商品名) 依照綠界規定的古怪規則進行排序，然後用 HashKey 進行 SHA256 加密，產生一個被稱為 CheckMacValue (防偽檢查碼) 的字串。
將這些資料打包成一個隱藏的 HTML Form 表單，回傳給前端。

階段二：轉址進入無塵室 (Redirect to Payment Gateway)

前端收到那個帶有 CheckMacValue 的 HTML 表單後，透過 JavaScript 自動 Submit 出去 (Auto-Submit)。這時候，使用者的畫面就會瞬間跳轉離開你的網站，進入綠界 (ECPay) 官方的綠色刷卡頁面。

為什麼要這麼做？ 因為你的伺服器沒有通過國際信用卡 PCI DSS 資安認證。如果你敢讓使用者在你的網頁上輸入「信用卡 16 碼」，只要發生一次外洩，你這輩子可能都賠不完。所以我們把這個最高風險的「無塵室」交給綠界。這一步，你完全碰不到信用卡號碼，你只負責等結果。

階段三：非同步回呼通知 (Return URL / Webhook) - 最易翻車的雷區

這是所有新手工程師最容易犯下致命錯誤的一環！

當使用者在綠界刷卡成功後，他可能會在跳轉回你網站的那 1 秒鐘內，手滑把瀏覽器關掉了；或者他在搭高鐵，過山洞時手機斷網了。這時候，如果你把「解鎖課程寫入資料庫」的邏輯，寫在前端跳轉回來的「成功感謝頁面 (ClientRedirectURL)」上，你就會遇到一堆「我明明付了錢卻不能看課」的客訴！

💡 業界標準的正確做法： 在階段一時，你要傳送一個 ReturnURL (例如 https://api.your-website.com/ecpay/callback) 給綠界。當綠界確認銀行扣款成功後，綠界的超級電腦會在背景 (Background)，主動發送一個 HTTP POST 請求給你的這個網址。

這就跟你之前開發 Line Bot 接收使用者訊息的 Webhook 概念一模一樣！你的這個 Webhook API 收到綠界的通知後，必須再次用 HashKey 驗證對方的簽章，確保這不是駭客偽造的請求，確認無誤後，你的後端才會去資料庫將訂單狀態改為「已付款」並解鎖課程權限。最後，你的 API 必須回傳一個純文字 1|OK 給綠界，告訴綠界「我收到了」。

這種非同步的架構，確保了即使使用者的手機爆炸了，只要他的信用卡扣款成功，你的資料庫依然能準確無誤地完成訂單。

🤖 讓 Vibe Coding 幫你度過雷區

綠界金流的加密規則非常複雜繁瑣 (要照字母排序、要轉大小寫、某些符號還要特別 encode)。這時候，身為架構師的你，千萬不要自己對著綠界那份又厚又舊的 PDF 文件一行一行刻程式碼！ 這太不 Vibe 了。

🔥【終極 Vibe Prompt 實戰建議】 如果你要在專案中加入綠界金流，請把這段精確的咒語丟給 Cursor 或 Claude：

我需要在目前的 Next.js App Router (Node.js 環境) 專案中串接台灣的 ECPay (綠界金流)。 請幫我寫兩支 API Routes： 1. /api/ecpay/createOrder：接收前端傳來的金額與商品名稱。請實作完整的 ECPay AIO 介面 SHA256 加密邏輯 (CheckMacValue)，計算完成後，回傳一組可以自動 Submit 跳轉至綠界測試環境的 HTML Form 字串。 2. /api/ecpay/callback：這是接收綠界付款成功背景通知 (ReturnURL) 的 Webhook。請實作反向的 CheckMacValue 驗證邏輯。驗證成功後，在終端機印出訂單編號，並務必回傳 '1|OK' 字串給綠界。 請確保你的加密邏輯處理了所有特殊的 URL Encode 轉換規則，並且環境變數使用 ECPay_HashKey 與 ECPay_HashIV。

當 AI 幫你產出程式碼後，你只需要填入你的金鑰，一台能為你 24 小時收錢的印鈔機引擎，就這樣輕鬆打造完成了！