
重點整理
- 綠界正式環境的特店編號、HashKey、HashIV,依官方文件在廠商後台「系統設定→系統介接設定→介接資訊」取得。
- HashKey、HashIV 用來計算檢查碼,綠界官方文件提醒要妥善保管;它等同金流密碼,不可貼群組或截圖外流。
- 綠界測試環境的資料只能在測試環境使用,上線前必須換成自己的正式資料。
- 接收付款通知的網址必須能從外部連線,只能用 80 或 443 連接埠,且要回傳 1|OK 格式。
- 金鑰應放在伺服器設定檔,不放前端程式碼,也不放進公開或多人共用的程式碼倉庫。
一句話重點: 要查詢綠界的特店編號(商店代號)、HashKey、HashIV,請登入綠界的正式廠商後台,依序進入「系統設定 → 系統介接設定 → 介接資訊」。這三樣是你的店家專屬的串接資料,其中 HashKey、HashIV 就像金流的密碼,只能交給負責串接的人,不要貼在群組,也不要讓截圖外流。測試環境另外提供一組公開的測試資料,不能用來收取真實款項。(本文依綠界官方文件整理,核對日期 2026-11-17;後台畫面與操作流程可能調整,請以綠界官方資訊為準。)
這三樣東西各是什麼?
| 名稱 | 白話說明 | 可以給誰 |
|---|---|---|
| 特店編號(MerchantID) | 綠界替你的店家編的專屬號碼,就像門牌號碼 | 串接的人 |
| HashKey | 用來計算「檢查碼」的金鑰 | 只給負責串接的人 |
| HashIV | 與 HashKey 搭配使用的第二把金鑰 | 只給負責串接的人 |
網站與綠界之間的每一筆訂單、每一次付款結果通知,都會附上一組「檢查碼」(CheckMacValue)。這組檢查碼是根據訂單內容,加上 HashKey、HashIV 計算出來的。雙方各自計算後再進行比對,就能確認訊息確實來自你的網站或綠界,沒有被冒充或竄改。
綠界官方文件也特別提醒,正式環境的特店編號、HashKey、HashIV 都是帳號專屬的識別資料,必須妥善保管,避免資料外洩造成資安風險。
所以,這些資料的重要性就像銀行帳戶的密碼。 一旦被別人取得,對方就有機會偽造看起來合法的請求。
去哪裡找?一步一步來
- 使用你的綠界會員帳號,登入正式環境的廠商後台:vendor.ecpay.com.tw。
- 在後台選單找到「系統設定」。
- 點選「系統介接設定」。
- 進入「介接資訊」,就能查看特店編號、HashKey、HashIV。
以上是綠界官方技術文件提供的操作路徑(見文末官方連結)。如果登入後發現選單名稱不同,通常是因為後台改版。這時請以綠界後台的實際畫面及官方客服說明為準,不要只參考第三方提供的舊版畫面截圖。
找不到「介接資訊」,或後台沒有這個選單怎麼辦? 可以依序檢查:
- 還沒完成特約申請。 如果只是註冊綠界會員,還沒有通過審核,就無法取得可以正式收款的串接資料。至於申請需要準備哪些文件、審核需要多久,請直接向綠界確認。
- 登入到測試後台。 綠界的測試後台(vendor-stage.ecpay.com.tw)和正式後台(vendor.ecpay.com.tw)是不同的網址,請確認自己登入的是正式後台。
- 其他帳號狀況。 如果確認以上兩點都沒有問題,卻還是找不到相關選單,請直接聯絡綠界客服。
測試資料和正式資料,不能混用
綠界另外提供測試環境(Stage),讓工程師在正式上線前測試金流串接功能。官方在測試環境資訊頁公開了測試用的特店編號、HashKey、HashIV,以及測試後台網址。
使用時要特別注意:
- 測試資料只能在測試環境使用。 正式上線前,一定要換成你自己的正式資料。綠界官方文件也明確提醒,不要將測試資料用在正式環境。
- 測試環境的付款只是模擬交易,不會真的扣款,也不會改變訂單狀態。模擬付款的通知會附帶標記,讓你的網站知道這不是真實交易。
- 官方測試頁也提醒了幾個串接時容易遇到的問題:接收付款通知的網址必須能從外部連線,而且只能使用 80 或 443 連接埠。網站收到通知後,必須回傳綠界規定的格式(`1|OK`),如果寫成 `1OK` 或 `OK` 都是錯誤的。另外,信用卡測試使用的有效月年必須晚於當下時間,否則會刷卡失敗。
- 不同服務使用的測試資料不一定相同。例如,綠界官方金流與電子發票的測試頁,列出的測試特店編號就不同。請依照你要串接的功能,到對應的官方頁面查詢。
本文不會提供任何金鑰,也建議你不要把真實的串接資料貼在文章、論壇或群組中。需要測試資料時,直接查看綠界官方頁面即可。
串接前,先把這 8 樣東西準備好
很多金流串接遇到的問題,不是程式太難寫,而是事前沒有把資料準備齊全。正式開始串接前,建議先確認以下事項。
1. 綠界會員與特約申請已完成
確認可以登入正式後台,也能查看介接資訊,才算完成這項準備。
申請需要的文件與審核時間,建議先向綠界詢問。由於審核進度不是你能控制的,這件事最好最早開始處理,避免影響後續串接。
2. 你要開放哪些付款方式
你打算提供信用卡、ATM 轉帳、超商代碼、超商條碼,還是分期付款?
不同付款方式的手續費率不同,而你的帳號實際可以使用哪些付款方式,也要以綠界的開通結果為準。
如果想先估算每個月大概需要支付多少手續費,可以使用〈金流手續費試算〉。這項工具依照綠界一般賣家的公開費率計算,實際費率仍以你和綠界簽訂的合約為準。
3. 要不要接物流或電子發票
除了線上付款,你的網站是否還需要超商取貨、宅配或開立電子發票?
這些都是不同的服務,各自有對應的官方技術文件與測試資料,需要分別向綠界確認是否已經開通。
4. 網站是不是已經有正式網址與 HTTPS
付款完成後,綠界會將付款結果通知你的網站,因此網站必須有可以從外部連線的網址。
如果網站還放在工程師的本機電腦,或只能從公司內部網路連線,就無法收到綠界的付款通知。
5. 誰來保管 HashKey 與 HashIV
建議只有一位負責人持有這組金鑰,再由他交給實際負責串接的工程師。
串接完成後,金鑰應存放在伺服器的設定檔中,不要直接寫在網頁前端的程式碼裡,也不要上傳到公開或多人共用的程式碼倉庫。
綠界官方文件要求妥善保管這組資料,而將金鑰存放在伺服器端,也是一般的資安做法。
6. 訂單成立與付款成功的流程
客人按下付款按鈕後,到訂單狀態變成「已付款」之前,網站需要執行哪些動作?
例如,庫存應該在什麼時候扣除?如果客人選擇超商代碼付款,卻超過期限沒有繳費,訂單該怎麼處理?
這些都屬於你的營運規則,必須先決定清楚,工程師才能在串接時把對應流程寫進系統。
7. 退款與對帳怎麼處理
綠界後台可以查詢交易紀錄,但網站上線後,還是需要有人負責日常的帳務處理。
建議事先確認:誰負責核對交易款項?客人提出退款時,又該由誰操作?
8. 上線前的真實付款試跑
測試環境順利通過,不代表正式環境就一定沒有問題,因為正式環境使用的是另一組串接資料。
上線前,建議使用小額款項實際刷卡付款,再進行退款,確認訂單狀態、付款通知與對帳流程都正常。
串接失敗,最常見的原因
如果付款時一直出現錯誤,或客人明明完成付款,網站的訂單狀態卻沒有更新,可以先從以下常見原因檢查:
- 拿測試資料連接正式環境,或反過來。 測試環境與正式環境使用不同的串接資料,不能混用。
- HashKey 與 HashIV 填反,或複製貼上時,不小心在前後多加了空白。依照官方的檢查碼算法,HashKey 要放在最前面,HashIV 則放在最後面一起計算。只要有任何一個字不正確,計算結果就無法通過比對。
- 檢查碼算錯。 參數順序、編碼方式或字元集,只要有任何一處不符合規定,雙方計算出來的檢查碼就會不同,綠界也會拒絕請求。這部分必須依照官方的「檢查碼機制」文件實作,詳細內容可參考綠界的檢查碼機制說明。
- 接收付款通知的網址被擋。 例如受到防火牆阻擋、必須登入才能存取,或使用了不允許的連接埠,導致綠界無法正常通知網站。
- 通知回傳格式不對。 依照官方說明,網站收到付款通知後,必須回傳 `1|OK`,代表已成功接收通知。如果寫成 `1OK` 或 `OK`,綠界都會視為沒有正確回應。
金鑰外洩了怎麼辦?
如果發現 HashKey 或 HashIV 不小心外洩,首先要停止繼續轉傳。不要再分享含有金鑰的截圖或訊息,並清除曾經存放這些資料的地方。
接著,聯絡綠界客服,確認金鑰是否可以更換、該如何更換,以及是否需要通知其他串接的系統。
金鑰更換後,你的網站也必須同步更新設定,否則付款會全部失敗。
至於能不能自行重新產生金鑰,本文沒有查到綠界官方的相關說明,請以綠界客服的回覆為準。
預防通常比事後補救更省事。建議平時就做好金鑰管理:只存放在伺服器、只提供給必要的人員,並在更換合作廠商或相關人員離職時,重新評估是否需要更換。
自己串,還是請人串?
如果你的網站使用現成平台提供的綠界外掛,通常只需要將特店編號、HashKey、HashIV 填入外掛設定頁,再設定好要開放的付款方式。
但如果是自行開發的網站、客製化購物網站或預約系統,就需要由工程師依照綠界官方技術文件進行串接,同時處理付款通知、退款及對帳等功能。
崴米做的是客製網站,金流與物流的〈金流與物流串接〉含綠界、藍新等金流商的申請流程協助、測試環境驗證,以及上線前的真實付款試跑。
購物網站整體的規劃見〈電商網站・購物網站架設〉。如果你已經有網站,想先請人看看串接得對不對,可以先申請〈免費網站健檢〉。
常見問題
特店編號跟商店代號是同一個東西嗎?
是。綠界官方文件使用的名稱是「特店編號」(MerchantID),一般口語則常稱為「商店代號」,兩者指的是同一個編號。
我只是想請廠商串接,要把 HashKey 給他嗎?
要,但交付方式很重要。
建議當面提供、透過通訊軟體私訊,或使用雙方約定的安全管道,直接交給實際負責串接的工程師。
不要把金鑰貼在群組裡,也不要放在郵件副本或雲端共用文件中。 串接完成後,也可以請廠商說明金鑰實際存放的位置。
測試環境的資料可以直接上線用嗎?
不行。測試資料只能用在測試環境,正式上線時,一定要換成你自己的正式特店編號、HashKey 與 HashIV。
如果拿測試資料連接正式環境,不會真的收到款項,也會造成付款失敗。
登入後台找不到「介接資訊」是怎麼回事?
先確認自己登入的是正式後台,而不是測試後台,接著檢查特約申請是否已經通過。
如果都確認沒問題,卻還是找不到「介接資訊」,請直接聯絡綠界客服。因為後台選單可能隨著系統改版或帳號類型而有所不同。
這篇的步驟會過期嗎?
有可能。金流商的後台畫面、申請流程和費率都可能調整。
本文核對日期為 2026-11-17。實際操作時,請以綠界官方技術文件與後台畫面為準:官方測試環境資訊、官方電子發票測試帳號資訊(英文)、官方檢查碼機制說明。
延伸閱讀
想把這件事交給我們處理?
金流與物流串接:信用卡、超商付款、宅配與超商取貨一次接好,訂單狀態自動回寫



