綠界科技檢查碼(CheckMacValue)產生器

在串接綠界科技的金流、物流、電子發票等服務時，在發送給 API 介接網址的參數中，其中一個必填的參數為 “CheckMacValue” （檢查碼）。本文分享如何以 Node.js 產生檢查碼。

Comic screenshot of a robot checking mails thoroughly and carefully in an office — style raw — s 2 — ar 3:2 — v 6.0

什麼是檢查碼？為什麼需要檢查碼？

檢查碼機制說明：https://developers.ecpay.com.tw/?p=2902

檢查碼 (CheckMacValue)就是將發送給綠界科技系統的所有參數，經過本機制的計算後，最後得到的雜湊值(Hash)。因此檢查碼本身也是個(必填的)參數。檢查碼目的是為了確認參數發送者是本人，而非假冒。

進一步了解雜湊演算法與其應用，請參閱： 用 Node.js 輕鬆實現雜湊演算法 — — Hash 與 Hmac

程式碼(Node.js)

GitHub 連結：https://github.com/evojroan/checkmacvaluegen

執行前請先確認可執行 Node.js。

只要修改部份的變數，例如 parameters 裡面的參數與參數值，再執行程式碼，console 就會顯示計算檢查碼的逐一步驟。

concept art of human working with robots in the office — ar 3:2 — style raw — s 10 — v 6.0

請注意 URL Encode 規則

在技術文件中的第三步驟「將整串字串進行URL encode」。JavaScript 雖然有內建 URL Encode 的函式，也就是 encodeURI() 與 encodeURIComponent()，但並非經過函式編碼就完成，還要進一步地搭配 URLEncode 轉換表比對。

例如符號 ! 經過 encodeURLComponent() 編碼後結果是 %21，但依據轉換表，要維持 !；空格(space) 經過 encodeURLComponent() 編碼後結果是 %20，但依據轉換表，應該要改成 +。

有這樣的差異主要是因為 JavaScript 以 UTF-8 進行編解碼，而綠界系統使用有很多種編碼方式 的 .NET，導致兩者編碼結果不同，因此 encodeURLComponent() 後還要再檢查轉換表。

常見錯誤：CheckMacValue Error

在建立訂單時，有時會遇到 CheckMacValue Error。若遇到本錯誤，先參閱本文章：CheckMacValue Error常見原因

廠商管理後台查詢 HashKey/IV 的途徑

檢查碼就是雜湊值的實際應用

只要 HashKey/IV 不外流，使用雜湊運算計算出的檢查碼能夠確認發送資訊的來源正確，進而確保串接各種服務的資訊安全。