綠界金流 API 串接前必讀：ReturnURL、OrderResultURL、ClientBackURL 一次搞懂

串接綠界金流時，最多人栽跟頭的不是 CheckMacValue 的計算，而是 ReturnURL、OrderResultURL、ClientBackURL 這三個參數的角色混淆。把通知訂單狀態的 URL 搞錯，輕則訂單顯示不同步讓消費者困惑，重則完全漏掉付款通知導致已收款卻未出貨。以下用表格和流程拆解它們的差異。

先看定義。ReturnURL 是「Server 端」的付款結果通知網址。消費者付款完成後，綠界的伺服器會主動用 HTTP POST 的方式，把付款結果送到這個網址。這個過程完全在後端發生，跟消費者的瀏覽器無關。你的程式收到後應該驗證 CheckMacValue、判斷 RtnCode 是否為 1、更新訂單狀態、然後回傳純文字 1|OK。

OrderResultURL 是「Client 端」的付款結果跳轉網址。消費者付款完成後，綠界會把消費者的瀏覽器重新導向到這個網址，同時在 POST body 裡帶上付款結果參數。它的作用是讓消費者看到「付款成功」或「付款失敗」的頁面。

ClientBackURL 是最單純的一個——它只是在綠界付款頁面上產生一個「返回商店」的按鈕，點了之後會把消費者帶回這個網址。注意，它不帶任何參數回來，純粹是一個連結跳轉。

三者的關鍵差異整理如下。觸發方式：ReturnURL 是綠界伺服器主動 POST 到你的伺服器；OrderResultURL 是消費者的瀏覽器被重新導向；ClientBackURL 是消費者手動點擊按鈕跳轉。可靠性：ReturnURL 最可靠，因為不依賴消費者的瀏覽器——即使消費者付完款就關掉網頁，你的伺服器還是收得到；OrderResultURL 依賴消費者的瀏覽器完成跳轉，如果消費者關掉頁面、斷網、或瀏覽器出問題，就不會觸發；ClientBackURL 需要消費者主動點擊，完全不可靠。適用的付款方式：ReturnURL 適用所有付款方式；OrderResultURL 不支援非即時付款（ATM、CVS、BARCODE）和銀聯卡；ClientBackURL 適用所有付款方式但不帶參數。

理解了差異之後，正確的架構設計原則是：「以 ReturnURL 作為唯一的訂單狀態更新來源」。所有的付款成功判斷、庫存扣減、出貨觸發，都應該在 ReturnURL 的處理邏輯裡完成。OrderResultURL 只負責前端頁面的呈現——顯示「付款成功，感謝購買」或「付款失敗，請重試」。

但這裡有一個進階問題需要處理：ReturnURL 和 OrderResultURL 沒有保證的先後順序。綠界的文件明確寫到「會依當下連線速度與系統執行速度而定」。也就是說，有可能消費者的瀏覽器已經跳到了 OrderResultURL 的頁面，但 ReturnURL 的通知還沒送到你的伺服器。這時候如果 OrderResultURL 的頁面直接讀資料庫的訂單狀態，就會顯示「未付款」。解決方案有三種：OrderResultURL 的頁面本身也帶有驗證和狀態更新邏輯（雙寫保險）；前端頁面用 Polling 每隔幾秒查詢一次訂單狀態直到更新；或是使用 WebSocket 讓後端在收到 ReturnURL 通知後即時推送狀態到前端。

最後提幾個常見的踩坑注意事項。第一，ReturnURL 如果沒有正確回傳 1|OK，綠界會重試通知，頻率是 5 到 15 分鐘一次，當天最多四次。常見的錯誤回傳值包括 "1|OK"（多了引號）、1|ok（小寫）、以及字串前後多了空白或換行。第二，ReturnURL 和 OrderResultURL 不要設成同一個網址，否則程式邏輯會混亂。第三，測試階段建議先不要設 OrderResultURL，讓付款結果頁停留在綠界上，這樣如果有錯誤訊息你可以直接看到。第四，因資安政策規定，ReturnURL 只接受 HTTPS（443 port）且必須使用合法的 Domain Name，不能用 IP 位址。