綠界金流串接的重點流程
綠界金流串接教學的核心，是先完成綠界金流申請，取得商店代號 MerchantID、介接 HashKey、HashIV，再依照綠界金流 API 規格建立訂單、產生 CheckMacValue、送出付款表單，最後接收付款結果通知並更新訂單狀態。綠界 ECPay 提供 AllInOne 全方位金流介接，可支援信用卡、ATM 虛擬帳號、CVS 超商代碼等付款方式，開發者可依網站技術選擇 PHP、Java、C#、Node.js、JavaScript 或 Wix 後端方式串接。
綠界金流適合哪些網站使用
綠界金流常見於自架電商、品牌官網、課程網站、會員訂閱、活動報名與接案收款頁面。只要網站需要線上收款，就可以透過綠界 API 或 SDK 建立訂單並導向綠界付款頁。
如果你的網站是 WordPress、Laravel、CodeIgniter、Spring Boot、ASP.NET、Node.js Express，通常可以直接使用官方技術文件或 SDK 串接。若是 Wix，則需特別注意 Wix 前端不能直接暴露 HashKey、HashIV，應改由 Wix 後端程式或外部伺服器處理付款參數與驗證。
綠界金流申請與後台設定
綠界申請個人與公司戶差異
進行綠界金流申請前，商家需要先註冊綠界 ECPay 會員。常見申請身分包含個人會員與公司／商業登記會員。綠界申請個人通常適合個人賣家、創作者、小型接案者或尚未成立公司的收款需求；公司戶則適合有統編、發票、品牌官網與正式營運需求的商家。
實際可啟用的服務項目、收款方式、撥款條件與審核文件，會依綠界官方規範與申請身分而異。建議在串接前先登入綠界廠商管理後台，確認要使用的付款方式是否已開通，例如信用卡一次付清、ATM、超商代碼等。
取得 MerchantID、HashKey、HashIV
完成會員註冊與服務開通後，需登入綠界廠商管理後台，進入「系統開發管理」或「系統介接設定」，取得以下資訊：
必備介接資訊
| 欄位 | 用途 | 注意事項 |
|---|---|---|
| MerchantID | 商店代號，用來識別商家 | 測試環境與正式環境通常不同 |
| HashKey | 產生 CheckMacValue 的金鑰之一 | 不可放在前端公開程式碼 |
| HashIV | 產生 CheckMacValue 的金鑰之一 | 應存放於後端環境變數或設定檔 |
| ReturnURL | 綠界付款結果通知網址 | 必須可由綠界伺服器連線 |
| OrderResultURL | 消費者付款完成後導回頁 | 不應只依此更新訂單付款狀態 |
| ClientBackURL | 消費者返回商店按鈕網址 | 用於導回網站，不等於付款確認 |
付款狀態應以 ReturnURL 的伺服器端通知為主要依據，不能只依使用者瀏覽器導回頁面判斷付款成功，因為使用者可能關閉視窗、網路中斷或導回失敗。
綠界 API 串接基本觀念
建立訂單與導向付款頁
綠界 API 教學中最重要的第一步，是由商家網站建立一筆站內訂單，接著依綠界規格組成付款參數。常見欄位包含 MerchantTradeNo、MerchantTradeDate、TotalAmount、TradeDesc、ItemName、ReturnURL、ChoosePayment 等。
MerchantTradeNo 必須唯一，不能重複送出。若訂單編號重複，綠界會依規格回應錯誤，因此實務上常用日期時間、流水號或資料庫訂單 ID 組成唯一交易編號。
CheckMacValue 驗證
CheckMacValue 是綠界金流 API 的安全驗證重點。送出付款請求前，商家端必須依照官方規則將參數排序、組合 HashKey 與 HashIV、進行 URL Encode，最後依指定加密方式產生 CheckMacValue。
付款結果通知回來時，也要重新計算 CheckMacValue 進行比對。只有驗證通過，且回傳交易狀態符合成功條件，才能將訂單改為已付款。
付款結果通知與訂單更新
綠界會將付款結果送到 ReturnURL。網站後端收到通知後，應完成以下步驟：
ReturnURL 處理順序
- 接收綠界 POST 參數。
- 檢查 MerchantID 與 MerchantTradeNo 是否存在。
- 重新計算並比對 CheckMacValue。
- 檢查 RtnCode、TradeNo、PaymentDate 等付款資訊。
- 確認訂單金額是否與站內資料一致。
- 更新訂單狀態為已付款或付款失敗。
- 回應綠界指定格式，常見為
1|OK。
若沒有正確回應，綠界可能會依機制重送通知，因此後端更新訂單時要具備冪等性，避免重複入帳、重複寄信或重複出貨。
不同技術的綠界串接方式比較
技術方案分析表
| 串接方式 | 適合對象 | 優點 | 注意事項 |
|---|---|---|---|
| 綠界金流串接 PHP | WordPress 外掛、自架 PHP、Laravel、CodeIgniter | 生態成熟，範例多，部署容易 | HashKey、HashIV 必須放後端 |
| 綠界金流串接教學 Java | Spring Boot、Java 電商、企業系統 | 適合大型系統與嚴謹架構 | 設定檔路徑與 XML 讀取需確認 |
| 綠界 API 教學 C# | ASP.NET、.NET Core、企業內部系統 | 與 Windows Server、IIS 整合度高 | 需處理編碼、排序與加密一致性 |
| 綠界 Java SDK | Java 專案使用官方 SDK | 可減少手寫參數與加密錯誤 | SDK 版本與官方文件需同步確認 |
| Node.js / JavaScript | Express、Next.js API Routes、Nuxt Server API | 適合前後端整合與 API 架構 | 不可在純前端產生 CheckMacValue |
| Wix 綠界金流串接教學 | Wix 網站、低程式碼網站 | 適合已有 Wix 官網者 | 通常需 Wix Backend 或外部伺服器 |
綠界金流串接 PHP 教學重點
PHP 串接流程
綠界金流串接 PHP 的基本做法，是在後端建立付款參數陣列，依官方規則產生 CheckMacValue，再輸出 HTML form 自動送出到綠界付款網址。正式環境與測試環境的 API URL 不同，開發時需確認目前使用的是測試參數或正式參數。
PHP 串接時建議將 MerchantID、HashKey、HashIV 放在 .env 或伺服器環境變數中，不要直接寫在公開 GitHub 專案。若使用 Laravel，可將付款建立、付款通知、訂單更新拆成 Service 與 Controller，讓流程更清楚。
PHP 常見錯誤
常見錯誤包含 MerchantTradeNo 重複、TotalAmount 與站內訂單金額不一致、ReturnURL 無法被外部連線、CheckMacValue 編碼錯誤，以及測試與正式環境參數混用。若付款頁無法開啟，通常要先檢查 API URL、參數名稱、必要欄位與 CheckMacValue。
綠界金流串接教學 Java 與綠界 Java SDK
Java SDK 使用觀念
綠界金流串接教學 Java 通常會使用官方 Java SDK 或依 API 文件自行實作。綠界對有收款需求的賣家會員提供完整交易介接 API，Java 版套件可用於建立訂單、接受付款通知、查詢訂單等金流交易。
若使用綠界 Java SDK，需確認 SDK 版本、設定檔位置、測試環境參數與正式環境參數。部分開發者曾遇到設定檔讀取問題，例如 EcpayPayment.xml 路徑錯誤或部署後無法取得設定檔。這類問題通常與專案結構、resources 路徑、打包方式或伺服器工作目錄有關。
Java 實作建議
Java 專案可將綠界串接拆成以下模組：
Java 後端模組建議
- PaymentService：建立綠界付款參數。
- EcpayConfig：集中管理 MerchantID、HashKey、HashIV。
- PaymentCallbackController：接收 ReturnURL 通知。
- OrderService：更新站內訂單狀態。
- LogService：記錄綠界回傳資料與錯誤訊息。
這樣可避免把付款邏輯散落在 Controller，也方便日後加入信用卡、ATM、CVS 或訂單查詢功能。
綠界 API 教學 C# 重點
C# 串接注意事項
綠界 API 教學 C# 的重點與其他後端語言相同：建立訂單、產生 CheckMacValue、送出付款請求、接收 ReturnURL、驗證回傳資料。使用 ASP.NET Core 時，建議將金鑰存放於 appsettings.json 搭配環境變數或機密管理工具，正式機不可將敏感資訊寫死在程式碼中。
C# 特別要注意字串排序、URL Encode 結果、大小寫轉換與雜湊演算法是否與綠界官方文件一致。若 CheckMacValue 驗證失敗，應先輸出參數排序前後的紀錄，但不要在正式環境 Log 中暴露 HashKey、HashIV。
Wix 綠界金流串接教學
Wix 串接限制與建議做法
Wix 綠界金流串接教學的關鍵在於：不要只用 Wix 前端頁面直接呼叫綠界 API。因為綠界付款參數需要 HashKey 與 HashIV 產生 CheckMacValue，若放在前端 JavaScript，使用者可從瀏覽器看到敏感資訊，會造成安全風險。
較安全的做法是使用 Wix Backend 或另外架設一個後端服務，例如 Node.js、PHP、Java 或 C# API。流程如下：
Wix 串接流程
- Wix 前端送出商品與訂單資料到後端。
- 後端建立站內訂單。
- 後端產生綠界付款參數與 CheckMacValue。
- Wix 頁面導向後端產生的付款表單或付款入口。
- 消費者至綠界付款頁完成付款。
- 綠界通知後端 ReturnURL。
- 後端更新訂單狀態，Wix 前端查詢結果並顯示完成頁。
若 Wix 原生付款功能不符合需求，才需要自行串接綠界；若只是簡單商店，應先比較 Wix 內建付款、第三方服務與自架後端的維護成本。
綠界金流 API 支援的付款方式
AllInOne 常見付款類型
綠界 AllInOne 提供多種付款方式，可依商家需求選擇。常見選項包含信用卡、ATM 虛擬帳號、CVS 超商代碼等。不同付款方式會有不同通知流程，例如 ATM 與 CVS 可能會先產生取號結果，再等待消費者實際付款後收到付款結果通知。
付款方式比較
| 付款方式 | 適合情境 | 串接重點 |
|---|---|---|
| 信用卡一次付清 | 即時付款、電商結帳 | 付款完成後通常較快取得結果 |
| ATM 虛擬帳號 | 客單價較高、不想刷卡者 | 需處理取號與實際付款通知 |
| CVS 超商代碼 | 無信用卡族群、超商付款 | 需注意代碼有效期限與付款通知 |
| 網路 ATM | 具網銀使用者 | 依綠界支援狀態與官方文件確認 |
實際可用付款方式、費率與功能狀態，應以綠界官方後台與最新技術文件為準。
金流串接費用與成本評估
費用不只看交易手續費
金流串接費用通常包含多個面向，不應只看單筆交易手續費。商家需要評估綠界官方公告費率、信用卡手續費、ATM 或超商代碼費用、撥款條件、退款處理、電子發票需求，以及工程串接成本。
如果委託工程師或網站公司串接，費用還會受到網站架構、付款方式數量、是否要串物流或電子發票、是否需要後台對帳、是否要串會員系統影響。若是既有網站改版，還需檢查資料庫訂單狀態、庫存流程與通知信是否能正確配合。
成本評估清單
- 綠界官方最新費率與合約條件。
- 要開通的付款方式數量。
- 是否需要測試環境與正式環境切換。
- 是否需要訂單查詢 API。
- 是否需要退款、取消授權或請退款流程。
- 是否需要串接電子發票、物流或超商取貨。
- 網站是否已有訂單系統。
- 是否需要資安檢查與 Log 紀錄。
- 是否需要後台對帳報表。
- 後續維護與 API 文件更新成本。
測試環境與正式上線檢查
上線前必做測試
完成綠界 API 教學的開發後，不能只測付款頁是否開啟，還要測完整交易生命週期。建議至少測試信用卡成功、付款失敗、取消付款、ReturnURL 通知、OrderResultURL 導回、重複通知、金額不一致防護、訂單編號重複、伺服器逾時與 Log 紀錄。
上線檢查清單
- MerchantID、HashKey、HashIV 已切換正式環境。
- 付款 API URL 已切換正式網址。
- ReturnURL 使用 HTTPS 且可公開存取。
- CheckMacValue 驗證可正常通過。
- 訂單金額與商品明細不可被前端竄改。
- 訂單狀態更新具備防重複處理。
- 付款成功後才出貨、開通課程或啟用會員權限。
- 錯誤訊息不顯示 HashKey、HashIV。
- 後台可查詢綠界交易編號 TradeNo。
- 已備份正式環境設定與部署紀錄。
常見串接錯誤與排除方向
CheckMacValue 驗證失敗
這是最常見問題。應檢查參數排序、URL Encode 規則、HashKey 與 HashIV 是否正確、測試正式環境是否混用、大小寫轉換是否符合官方文件。不同語言的 URL Encode 結果可能有差異，需依綠界最新技術文件調整。
ReturnURL 收不到通知
可能原因包含網址不是公開 HTTPS、伺服器防火牆阻擋、路由設定錯誤、程式回應非綠界要求格式、網站需要登入才能存取通知網址。ReturnURL 應為公開可接收 POST 的後端端點，不應是前端頁面。
Java SDK 設定檔找不到
若使用 Java SDK 並遇到類似 fileURL is null 或設定檔讀取失敗，應檢查 EcpayPayment.xml 是否放在 SDK 或專案要求的資源路徑、打包後是否被包含、執行環境是否能讀取該檔案。建議將設定管理標準化，避免本機可跑、正式機失敗。
結論
綠界金流串接的關鍵不是單純把付款頁打開，而是要完整處理訂單建立、付款參數、CheckMacValue、ReturnURL 通知、訂單狀態更新與上線安全。無論你搜尋的是綠界金流串接 PHP、綠界金流串接教學 Java、綠界 API 教學 C#、Wix 綠界金流串接教學，或想使用綠界 Java SDK，核心原則都相同：敏感金鑰放後端、付款狀態以伺服器通知為準、所有金額與訂單都要回查驗證。
若是正式營運網站，建議先完成綠界金流申請，確認綠界申請個人或公司戶適用條件，再依官方綠界金流 API 文件進行測試。金流串接費用則應同時評估官方費率、付款方式、工程開發與後續維護，才能讓網站收款流程穩定、安全且可長期營運。
常見問題
1. 綠界金流串接一定要使用 SDK 嗎？
不一定。可以使用官方 SDK，也可以依照綠界金流 API 文件自行實作。SDK 可減少參數與加密錯誤，但自行實作彈性較高，適合熟悉 API 流程的開發者。
2. 綠界金流申請需要多久？
實際審核時間會依綠界官方流程、申請身分、文件完整度與服務項目而異。建議在網站開發初期就先申請，避免金流尚未開通而延誤上線。
3. 綠界申請個人可以串接金流嗎？
綠界申請個人通常可用於個人收款需求，但實際可啟用的付款方式、額度、撥款與審核條件，仍需以綠界官方公告與後台狀態為準。
4. 綠界金流串接 PHP 最常見錯誤是什麼？
常見錯誤包括 CheckMacValue 產生錯誤、ReturnURL 無法連線、MerchantTradeNo 重複、正式與測試參數混用，以及 HashKey、HashIV 放在前端或公開程式碼中。
5. Wix 可以直接串綠界金流嗎？
可以串接，但不建議只用 Wix 前端處理。較安全做法是透過 Wix Backend 或外部伺服器產生付款參數與 CheckMacValue，再導向綠界付款頁。
6. 綠界 Java SDK 適合哪些專案？
綠界 Java SDK 適合 Java、Spring Boot 或企業級後端系統。使用時要注意 SDK 版本、設定檔路徑、測試正式環境切換，以及部署後是否能正確讀取設定。
7. 綠界 API 教學 C# 需要注意什麼？
綠界 API 教學 C# 需特別注意參數排序、URL Encode、雜湊演算法、大小寫轉換與 CheckMacValue 驗證。正式環境中不可記錄或暴露 HashKey、HashIV。
8. 付款成功頁可以當作付款成功依據嗎？
不建議。付款成功應以 ReturnURL 伺服器端通知為準。OrderResultURL 或付款完成導回頁主要是給消費者查看結果，不應作為唯一入帳依據。
9. 金流串接費用怎麼估算？
金流串接費用包含綠界官方費率、付款方式費用、工程開發、測試、維護、後台對帳與可能的電子發票、物流串接成本。實際費用應依網站需求與官方最新公告評估。
10. 綠界金流串接上線前要測什麼？
至少要測付款成功、付款失敗、取消付款、ReturnURL 通知、CheckMacValue 驗證、重複通知、金額驗證、訂單編號唯一性、正式環境參數與後台交易查詢。