Java 串接綠界金流的核心流程
要完成「綠界金流串接教學 Java」，重點不是只把付款頁面導過去，而是要正確完成訂單建立、參數組裝、CheckMacValue 檢查、付款結果通知接收、交易狀態更新與測試環境驗證。綠界提供的綠界全方位金流支援信用卡、ATM、CVS、BARCODE、WEBATM、TWQR 等付款方式，開發者可透過金流串接 API 或官方 SDK 建立訂單，將使用者導向綠界付款頁，再由綠界以 Server POST 通知商店系統付款結果。
在 Java 專案中，最常見的做法是使用官方 Java SDK，也就是開發者常搜尋的綠界 Java SDK、綠界金流 Java。SDK 可協助產生訂單參數、送出付款表單、處理 CheckMacValue，降低自行實作雜湊驗證時發生錯誤的機率。不過即使使用 SDK，仍必須理解綠界 API 的資料流，否則在 ReturnURL、ClientBackURL、MerchantTradeNo、HashKey、HashIV、測試特店代號等欄位上，很容易發生測試通過但正式環境失敗的問題。
串接前必備資料與官方文件
需要準備的綠界資料
進行綠界 API 測試 前，建議先準備下列資訊：
| 項目 | 用途 | 注意事項 |
|---|---|---|
| MerchantID | 特店編號 | 測試環境與正式環境不同 |
| HashKey | 產生 CheckMacValue | 不可外洩或放在前端 |
| HashIV | 產生 CheckMacValue | 必須與環境對應 |
| ReturnURL | 綠界後端通知付款結果 | 必須是可公開連線的 HTTPS 或可被綠界呼叫的網址 |
| ClientBackURL | 使用者付款後返回商店頁 | 不可用來判斷付款成功 |
| OrderResultURL | 信用卡付款結果頁 | 依付款情境設定 |
| MerchantTradeNo | 商店訂單編號 | 不可重複，長度與格式需符合文件 |
| TotalAmount | 訂單金額 | 測試與正式都要送整數金額 |
| TradeDesc / ItemName | 交易描述與商品名稱 | 特殊字元需留意編碼 |
綠界官方已將全方位金流 API 技術文件改為線上文件，開發者可至綠界開發者專區查閱最新規格。由於 API 規格、測試參數與付款方式可能調整，實作前不應只依賴舊文章或範例碼，應以官方文件為準。
綠界測試帳號與測試後台
綠界測試帳號 可用於測試特店後台登入、查詢訂單、模擬付款，以及確認商店系統是否能收到綠界後端發送的付款結果通知。測試環境常用於下列工作：
- 建立測試訂單。
- 導向綠界測試付款頁。
- 在測試後台查詢交易。
- 模擬 ATM、CVS、信用卡等付款結果。
- 檢查商店 ReturnURL 是否有收到 form_data 格式資料。
- 驗證 CheckMacValue 是否正確。
- 確認訂單狀態是否正確更新。
測試後台與正式後台資料不互通，測試 MerchantID、HashKey、HashIV 也不可直接套用到正式環境。
綠界全方位金流串接架構
付款流程說明
綠界全方位金流 的標準交易流程通常如下：
- 使用者在網站建立訂單。
- 商店後端產生 MerchantTradeNo。
- Java 後端組裝綠界付款參數。
- SDK 或程式產生 CheckMacValue。
- 後端回傳自動送出的 HTML form，或由伺服器導向綠界付款頁。
- 使用者在綠界頁面完成付款或取得繳費代碼。
- 綠界以 POST 將付款結果送至 ReturnURL。
- 商店驗證 CheckMacValue。
- 商店更新訂單狀態。
- 商店回應綠界指定格式，表示已接收通知。
其中最重要的是第 7 到第 9 步。很多初次串接者會誤以為使用者看到付款完成頁就代表訂單成功，但實務上必須以綠界後端通知或查詢 API 回傳結果作為訂單狀態依據。
form_data 轉換與後端接收
綠界回傳資料通常是 application/x-www-form-urlencoded 的 form_data 格式，不是 JSON。因此 Java 後端不可直接用 JSON body 解析，應使用表單參數接收，例如 Spring Boot 可透過 @RequestParam Map<String, String> 接收。
Java
@PostMapping(“/ecpay/return”)
public String ecpayReturn(@RequestParam Map<String, String> params) {
// 1. 取出綠界回傳參數
// 2. 驗證 CheckMacValue
// 3. 根據 RtnCode、MerchantTradeNo 更新訂單
// 4. 回覆綠界接收成功
return “1|OK”;
}
如果接收端錯用 @RequestBody 解析 JSON，常會發生收不到參數、CheckMacValue 驗證失敗，或付款成功但訂單沒有更新的問題。
Java 專案安裝與設定綠界 SDK
下載與導入 SDK
若使用 Java 串接，建議從綠界官方提供的 SDK 或 GitHub 來源取得範例。使用者提供的參考資料中提到 ECPayAIONode.js，也就是 Node.js 版本 SDK，做法是下載程式碼後把 ECPAYPaymentnodejs 內容作為模組匯入並命名為 ECPAY，用來建立 CVS、查詢付款狀態等。這個概念可對應到 Java：將綠界 Java SDK 加入專案，並以後端服務封裝付款建立、回傳驗證與查詢交易。
Java 專案常見導入方式包括：
- 將官方 Java SDK 放入專案。
- 確認 SDK 內的設定檔位置。
- 設定測試環境 MerchantID、HashKey、HashIV。
- 建立付款服務類別。
- 將建立訂單邏輯與付款導向邏輯分離。
- 將付款通知處理獨立成 ReturnURL Controller。
部分 Java SDK 版本會使用設定檔，例如 EcpayPayment.xml。若遇到 fileURL is null，通常表示 SDK 找不到設定檔，常見原因包含設定檔未放在 classpath、部署後路徑改變、IDE 執行與打包執行的資源路徑不同，或檔名大小寫不一致。
fileURL is null 常見排查
若卡在 fileURL is null，可依序檢查：
EcpayPayment.xml是否存在於src/main/resources。- 打包後 JAR/WAR 內是否真的包含該檔案。
- SDK 讀取設定檔的路徑是否與專案結構一致。
- 檔名大小寫是否正確。
- 使用 Maven 或 Gradle 時，resources 是否被正確打包。
- 若部署於 Tomcat、OSGi bundle 或容器環境，是否有 classloader 差異。
- 不要把設定檔剪下後放到無法被 classpath 讀取的位置。
OSGi bundle 方式串接時，初始化資源與 classloader 管理更容易出錯，建議先用最小化 Java 專案完成付款建立與通知接收，再導入正式架構。
建立付款訂單的 Java 實作重點
付款參數設計
綠界金流 Java 實作中，建立訂單時應至少處理下列欄位：
| 參數 | 說明 | 實作建議 |
|---|---|---|
| MerchantTradeNo | 商店訂單編號 | 使用系統訂單號加時間或流水號，避免重複 |
| MerchantTradeDate | 交易時間 | 格式需符合綠界文件 |
| TotalAmount | 金額 | 後端重新計算，不可完全信任前端 |
| TradeDesc | 交易描述 | 避免特殊符號造成編碼問題 |
| ItemName | 商品名稱 | 多商品依文件格式串接 |
| ReturnURL | 付款結果通知 | 用於後端更新訂單 |
| ChoosePayment | 付款方式 | ALL、Credit、ATM、CVS 等 |
| EncryptType | 加密類型 | 依官方文件建議設定 |
| CheckMacValue | 檢查碼 | 建議交由 SDK 或嚴格依文件產生 |
付款建立應由後端完成，避免前端傳入金額後直接送綠界。正確做法是前端只送出購物車或訂單 ID，後端查詢資料庫重新計算金額，再組裝金流參數。
Spring Boot 範例結構
以下是概念型結構，實際類別與方法名稱需依使用的綠界 Java SDK 版本調整：
Java
@Service
public class EcpayPaymentService {
public String createPaymentForm(Order order) {
// 1. 從資料庫取得訂單
// 2. 驗證訂單狀態是否可付款
// 3. 組裝綠界付款參數
// 4. 透過 SDK 產生自動提交表單
// 5. 回傳 HTML form 給前端或瀏覽器
return ”
“;
}
}
Java
@Controller
public class EcpayController {
@PostMapping(“/pay/ecpay”)
@ResponseBody
public String pay(@RequestParam String orderNo) {
// 呼叫 EcpayPaymentService 建立付款表單
return “”;
}
@PostMapping(“/pay/ecpay/return”)
@ResponseBody
public String paymentReturn(@RequestParam Map<String, String> params) {
// 驗證 CheckMacValue 並更新訂單
return “1|OK”;
}
}
這裡的重點不是複製範例碼，而是確保付款建立與付款通知都有獨立邏輯，並且資料庫訂單狀態更新具備冪等性。因為綠界可能重送通知，系統需避免重複出貨或重複加值。
CheckMacValue 驗證與交易安全
為什麼 CheckMacValue 很重要
CheckMacValue 是綠界金流串接中最重要的驗證機制之一，用於確認資料是否由合法來源產生，以及傳輸過程中是否被竄改。無論是送出付款請求或接收付款結果，都應依綠界官方規格產生或驗證 CheckMacValue。
常見錯誤包括：
- HashKey、HashIV 使用錯誤環境。
- 參數排序不符合規格。
- URL Encode 規則與官方文件不一致。
- 大小寫轉換錯誤。
- 未排除 CheckMacValue 本身再進行驗證。
- 使用前端資料直接更新訂單。
- 忽略回傳 RtnCode 與交易狀態。
若使用 SDK，仍建議閱讀官方 CheckMacValue 規則，因為在除錯時可以更快判斷是參數問題、編碼問題還是環境設定問題。
ReturnURL 不等於使用者回到頁面
ReturnURL 是綠界伺服器通知商店後端的網址，通常用來更新訂單狀態。ClientBackURL 則是付款完成後使用者點擊返回商店的網址，不能作為付款成功依據。原因是使用者可能關閉視窗、網路中斷，或付款方式屬於待繳費型態，例如 ATM、CVS，當下並不代表已完成付款。
正確判斷付款成功應依照：
- ReturnURL 收到綠界通知。
- CheckMacValue 驗證通過。
- RtnCode 或相關交易狀態符合成功條件。
- MerchantTradeNo 能對應到商店訂單。
- 金額與訂單金額一致。
- 訂單尚未被處理完成。
綠界 API、SDK 與不同技術情境比較
串接方式比較表
| 串接情境 | 適用對象 | 優點 | 注意事項 |
|---|---|---|---|
| 綠界 Java SDK | Spring Boot、Servlet、Java Web 系統 | 減少 CheckMacValue 與表單產生錯誤 | 需確認 SDK 版本與設定檔位置 |
| 直接串金流串接 API | 有完整後端能力的團隊 | 彈性最高，可完全控制流程 | 必須自行處理參數、編碼、驗證 |
| Node.js SDK | Node.js / Express 專案 | 可用 ECPayAIO_Node.js 快速建立付款 | 不適用純 Java 專案，但概念可參考 |
| PHP SDK | WordPress、Laravel、傳統 PHP 站台 | 官方範例多、上手快 | 架構需避免商業邏輯散落 |
| C# API 串接 | ASP.NET、.NET Core | 適合 Windows/.NET 生態 | 可參考綠界 API 教學 C#，但規格仍以官方文件為準 |
| Wix 串接 | 使用 Wix 架站者 | 可搭配外部後端或收款連結 | Wix 綠界金流串接教學 需注意 Wix 平台限制與後端能力 |
| 定期定額 API | 訂閱制、會員制 | 可自動週期扣款 | 綠界定期定額 API 需處理授權、週期、失敗扣款與取消機制 |
若是企業正式上線，建議優先選擇後端可控的串接方式，例如 Java SDK 或直接 API。若是 Wix 類型網站，因平台後端控制能力不同，常見做法是使用外部後端服務處理綠界付款流程，或使用綠界後台建立收款連結；若商品多、金額動態變化大，仍建議建立 API 串接架構。
常見付款方式與 API 功能
WEBATM、TWQR、CVS 與信用卡
綠界全方位金流支援多種付款方式，常見包含：
- 信用卡付款。
- ATM 虛擬帳號。
- WEBATM 網路轉帳。
- CVS 超商代碼。
- BARCODE 超商條碼。
- TWQR 行動支付。
- 定期定額信用卡扣款。
不同付款方式的交易狀態不同。信用卡通常可立即得到授權結果；ATM、CVS、BARCODE 則可能先產生繳費代碼，等消費者完成付款後才會收到付款成功通知。因此訂單狀態建議區分為「待付款」、「付款成功」、「付款失敗」、「已取消」、「逾期未付款」等，而不是只有成功與失敗。
綠界定期定額 API 注意事項
綠界定期定額 API 適合訂閱制、會員月費、定期服務費等場景。實作時除了建立第一筆授權或定期扣款設定，也要處理：
- 扣款週期。
- 扣款金額。
- 扣款失敗通知。
- 信用卡到期或授權失敗。
- 使用者取消訂閱。
- 後台對帳。
- 發票或收據流程。
- 個資與付款資料保護。
定期定額不應只當成一般單筆付款處理，因為它牽涉長期授權、會員權益與服務終止規則，正式上線前應完整測試不同扣款狀態。
綠界 API 測試與上線檢查
綠界 API 測試 清單
正式上線前，建議完成以下測試：
| 測試項目 | 檢查重點 |
|---|---|
| 建立訂單 | MerchantTradeNo 不重複，金額正確 |
| 導向付款頁 | 表單可正常送出，付款方式正確 |
| 信用卡付款 | 成功、失敗、取消付款都能處理 |
| ATM/CVS | 產生繳費資訊後狀態為待付款 |
| ReturnURL | 能收到綠界 POST 通知 |
| CheckMacValue | 回傳驗證必須通過 |
| 訂單更新 | 不可重複出貨或重複加值 |
| 查詢訂單 | 後台與商店資料一致 |
| 錯誤處理 | API 異常時有紀錄與告警 |
| 正式切換 | MerchantID、HashKey、HashIV、API URL 全部切換 |
測試環境成功不代表正式環境一定成功，因為正式環境的網域、SSL、伺服器防火牆、API 網址、商店審核狀態都可能不同。
測試通知接收的實務建議
ReturnURL 必須能被綠界伺服器呼叫，因此本機 localhost 無法直接作為測試通知網址。若在開發階段需要測試，可使用測試伺服器、內網穿透工具或部署到臨時 HTTPS 環境。測試時應完整記錄綠界回傳參數，但避免將 HashKey、HashIV、信用卡敏感資訊寫入公開 log。
此外，綠界回傳後商店應回應官方指定格式，例如常見的 1|OK。若沒有正確回應，綠界可能判定商店未成功接收通知，進而重送通知。
金流串接費用與營運成本
金流串接費用 不只看交易手續費
金流串接費用 通常包含幾個層面：金流服務商收取的交易手續費、特定付款方式費用、退款或撥款相關費用、開發人力成本、維護成本，以及日後對帳與客服成本。實際費率與條件會依綠界公告、商店類型、交易量、付款方式與合約而有所不同，正式導入前應查閱綠界官方費率頁或與綠界確認。
技術面也會影響成本。若網站只賣少量固定商品，使用綠界後台建立收款連結可能最快；若商品數量多、價格動態變化、需要會員訂單紀錄、庫存扣減、自動開立發票，則串接 SDK 或 API 會更符合長期維運需求。
Wix、C# 與跨平台串接補充
Wix 綠界金流串接教學 的限制
搜尋 Wix 綠界金流串接教學 的使用者，多半希望在 Wix 網站直接接綠界。需要注意的是，Wix 的付款整合能力會受到平台支援項目、所在地、商務方案與 Velo 後端能力限制。若無法直接安裝綠界付款模組，可考慮：
- 使用綠界後台建立收款連結。
- 透過外部 Java、Node.js 或 PHP 後端建立付款訂單。
- Wix 前端導向外部付款流程。
- 付款完成後由外部後端接收 ReturnURL。
- 再將訂單狀態同步回 Wix 或自有系統。
這種方式的關鍵是：金流邏輯仍應放在後端，不應把 HashKey、HashIV 放在 Wix 前端頁面。
綠界 API 教學 C# 與 Java 的差異
綠界 API 教學 C# 和 Java 串接本質相同，都是依官方 API 規格組參數、產生 CheckMacValue、接收 ReturnURL 並更新訂單。差異主要在 SDK 語法、框架接收表單資料的方式，以及部署環境。C# 常見於 ASP.NET Core，Java 常見於 Spring Boot、Servlet、Tomcat 或企業內部系統。無論使用哪種語言，安全原則與交易流程一致。
結論
綠界金流串接教學 Java 的成功關鍵，在於使用綠界 Java SDK 或金流串接 API 時，仍要理解完整交易流程：後端建立訂單、導向綠界付款、接收 form_data 通知、驗證 CheckMacValue、更新資料庫訂單狀態，並透過綠界測試帳號 完成各付款方式測試。若遇到 fileURL is null，應優先檢查 EcpayPayment.xml 是否正確放在 classpath 與打包資源中。
對正式上線而言，不能只確認付款頁能打開，也要測試 ReturnURL、重複通知、付款失敗、ATM/CVS 待付款、定期定額、退款與對帳流程。若是 Wix、C#、Node.js 或其他平台，串接語言不同，但核心規格相同；最終仍應以綠界官方文件、測試後台與正式環境驗證結果為準。
常見問題
1. Java 串接綠界金流一定要用 SDK 嗎？
不一定。可以直接串接金流串接 API，但使用綠界 Java SDK 可降低參數組裝與 CheckMacValue 錯誤風險。若團隊熟悉 API 規格，也可自行實作。
2. 綠界測試帳號可以直接用在正式環境嗎？
不可以。測試環境與正式環境的 MerchantID、HashKey、HashIV、API URL 不同，上線時必須全部切換成正式資料。
3. ReturnURL 和 ClientBackURL 有什麼不同？
ReturnURL 是綠界後端通知商店付款結果的網址，應用於更新訂單狀態。ClientBackURL 是使用者返回商店頁面的網址，不能作為付款成功依據。
4. 為什麼綠界回傳資料不是 JSON？
綠界付款結果通知常以 form_data 格式 POST，因此 Java 後端應使用表單參數接收，例如 Spring Boot 的 @RequestParam Map<String, String>。
5. CheckMacValue 驗證失敗怎麼辦？
先確認 HashKey、HashIV、API 環境、參數排序、URL Encode 規則、大小寫轉換，以及是否排除 CheckMacValue 本身再驗證。
6. fileURL is null 通常是什麼原因？
多半是 SDK 找不到設定檔，例如 EcpayPayment.xml 未放在 classpath、沒有被打包進 JAR/WAR、檔名錯誤或部署環境 classloader 差異。
7. ATM 或 CVS 產生代碼後算付款成功嗎？
不算。產生繳費代碼通常只代表待付款，需等消費者實際繳費後，綠界再通知商店付款成功。
8. Wix 可以串接綠界金流嗎？
可行方式取決於 Wix 平台能力。常見做法是透過外部後端處理綠界 API，Wix 前端只負責導向付款，不應在前端保存 HashKey、HashIV。
9. 綠界定期定額 API 適合哪些情境？
適合訂閱制、會員月費、定期服務費等情境。實作時需處理週期扣款、失敗通知、取消訂閱與會員權益。
10. 金流串接費用怎麼估算？
應同時評估交易手續費、付款方式費用、退款或撥款成本、開發人力、維護、對帳與客服成本。實際費率應以綠界官方公告或合約為準。