CheckMacValue檢查碼的運作方式
繁中 | ENG
串接全方位金流、物流整合時，發送的 Request 會有參數 CheckMacValue (檢查碼)。CheckMacValue 的作用是辨別收到的訊息並分假冒。如果缺少本機制，則任何人假冒特店或是綠界發送訊息，對方也無從確認。
特店的金鑰 (HashKey、HashIV) 只有特店與綠界知道，將所有發送的參數加上金鑰後經過特定的計算過程，便能得到雜湊值，也就是 CheckMacValue 。將對方發送的訊息，以同樣的金鑰與計算方式算出 CheckMacValue ，比對後若一致，就能確定訊息來源是對方。
全方位金流 CheckMacValue 計算方式：https://developers.ecpay.com.tw/?p=2902
物流整合 CheckMacValue 計算方式：https://developers.ecpay.com.tw/?p=7424
以全方位金流為例，以下是大致流程。
一、建立訂單
1. 準備好建立訂單的參數，並將這些參數以金鑰計算出檢查碼 。
2. 參數與檢查碼就是要傳給綠界的 Request。
3. 綠界收到特店的 Request 後，會根據特店的參數自行再次計算檢查碼，並比對再行計算的檢查碼，以及特店提供的檢查碼。
4. 比對正確，表示確實是特店發送的，而非假冒。導轉到全方位金流付款頁面。
5. 於全方位金流頁面完成付款。
二、付款結果通知
6. 完成付款後，綠界傳送付款結果通知給特店，包含許多參數以及檢查碼。
7. 特店根據收到的參數再行計算檢查碼，並比對綠界提供的檢查碼。
8. 比對正確，表示確實是綠界發送的，而非假冒。
每步驟說明如下。
1. 準備好建立訂單的參數，並將這些參數以金鑰計算出檢查碼
準備好建立訂單的參數
{
"ChoosePayment": "ALL",
"EncryptType": "1",
"ItemName": "myItem",
"MerchantID": "3002607",
"MerchantTradeDate": "2025/02/08 09:27:23",
"MerchantTradeNo": "ECPay1738978043",
"PaymentType": "aio",
"ReturnURL": "https://08f6-211-23-76-78.ngrok-free.app/returnurl.php",
"TotalAmount": "30",
"TradeDesc": "Trade"
}
並將這些參數以金鑰計算出檢查碼
(1) 將傳遞參數依照第一個英文字母，由A到Z的順序來排序(遇到第一個英名字母相同時，以第二個英名字母來比較，以此類推)，並且以&方式將所有參數串連。
ChoosePayment=ALL&EncryptType=1&ItemName=myItem&MerchantID=3002607&MerchantTradeDate=2025/02/08 09:27:23&MerchantTradeNo=ECPay1738978043&PaymentType=aio&ReturnURL=https://08f6-211-23-76-78.ngrok-free.app/returnurl.php&TotalAmount=30&TradeDesc=Trade
(2) 參數最前面加上HashKey、最後面加上 HashIV
HashKey=pwFHCqoQZGmho4w6&ChoosePayment=ALL&EncryptType=1&ItemName=myItem&MerchantID=3002607&MerchantTradeDate=2025/02/08 09:27:23&MerchantTradeNo=ECPay1738978043&PaymentType=aio&ReturnURL=https://08f6-211-23-76-78.ngrok-free.app/returnurl.php&TotalAmount=30&TradeDesc=Trade&HashIV=EkRm7iFT261dpevs
(3) 將整串字串進行URL encode
HashKey%3DpwFHCqoQZGmho4w6%26ChoosePayment%3DALL%26EncryptType%3D1%26ItemName%3DmyItem%26MerchantID%3D3002607%26MerchantTradeDate%3D2025%2F02%2F08+09%3A27%3A23%26MerchantTradeNo%3DECPay1738978043%26PaymentType%3Daio%26ReturnURL%3Dhttps%3A%2F%2F08f6-211-23-76-78.ngrok-free.app%2Freturnurl.php%26TotalAmount%3D30%26TradeDesc%3DTrade%26HashIV%3DEkRm7iFT261dpevs
(4) 轉為小寫
hashkey%3dpwfhcqoqzgmho4w6%26choosepayment%3dall%26encrypttype%3d1%26itemname%3dmyitem%26merchantid%3d3002607%26merchanttradedate%3d2025%2f02%2f08+09%3a27%3a23%26merchanttradeno%3decpay1738978043%26paymenttype%3daio%26returnurl%3dhttps%3a%2f%2f08f6-211-23-76-78.ngrok-free.app%2freturnurl.php%26totalamount%3d30%26tradedesc%3dtrade%26hashiv%3dekrm7ift261dpevs
(5) 以 sha256 方式產生雜凑值
f1fb466ed0d6713dac7158ab6705914e37c93bd44fb8fa44c17f80cd17bb5728
(6) 再轉大寫產生 CheckMacValue
F1FB466ED0D6713DAC7158AB6705914E37C93BD44FB8FA44C17F80CD17BB5728
2. 參數與檢查碼就是要傳給綠界的 Request (以 JSON 形式呈現僅是於本文易於閱讀，實際上發送時請遵循 API 的傳輸協定)
{
"ChoosePayment": "ALL",
"EncryptType": "1",
"ItemName": "myItem",
"MerchantID": "3002607",
"MerchantTradeDate": "2025/02/08 09:27:23",
"MerchantTradeNo": "ECPay1738978043",
"PaymentType": "aio",
"ReturnURL": "https://08f6-211-23-76-78.ngrok-free.app/returnurl.php",
"TotalAmount": "30",
"TradeDesc": "Trade",
"CheckMacValue":"F1FB466ED0D6713DAC7158AB6705914E37C93BD44FB8FA44C17F80CD17BB5728"
}3. 綠界收到特店的 Request 後，會根據特店的參數自行再次計算檢查碼，並比對再行計算的檢查碼，以及特店提供的檢查碼
4. 比對正確，表示確實是特店發送的，而非假冒。導轉到全方位金流付款頁面
5. 於全方位金流頁面完成付款
6. 完成付款後，綠界傳送付款結果通知給特店，包含許多參數以及檢查碼
CustomField1=&CustomField2=&CustomField3=&CustomField4=&MerchantID=3002607&MerchantTradeNo=ECPay1738978034&PaymentDate=2025/02/08 09:32:20&PaymentType=Credit_CreditCard&PaymentTypeChargeFee=1&RtnCode=1&RtnMsg=交易成功&SimulatePaid=0&StoreID=&TradeAmt=30&TradeDate=2025/02/08 09:27:18&TradeNo=2502080927183709&CheckMacValue=C66199663DD43BF01058218601BEE874315E5FF57A1FE112A9114AC3701947BA
7. 特店根據收到的參數再行計算檢查碼，並比對綠界提供的檢查碼。
(1) 將傳遞參數依照第一個英文字母，由A到Z的順序來排序(遇到第一個英名字母相同時，以第二個英名字母來比較，以此類推)，並且以&方式將所有參數串連。
CustomField1=&CustomField2=&CustomField3=&CustomField4=&MerchantID=3002607&MerchantTradeNo=ECPay1738978034&PaymentDate=2025/02/08 09:32:20&PaymentType=Credit_CreditCard&PaymentTypeChargeFee=1&RtnCode=1&RtnMsg=交易成功&SimulatePaid=0&StoreID=&TradeAmt=30&TradeDate=2025/02/08 09:27:18&TradeNo=2502080927183709
(2) 參數最前面加上HashKey、最後面加上 HashIV
HashKey=pwFHCqoQZGmho4w6&CustomField1=&CustomField2=&CustomField3=&CustomField4=&MerchantID=3002607&MerchantTradeNo=ECPay1738978034&PaymentDate=2025/02/08 09:32:20&PaymentType=Credit_CreditCard&PaymentTypeChargeFee=1&RtnCode=1&RtnMsg=交易成功&SimulatePaid=0&StoreID=&TradeAmt=30&TradeDate=2025/02/08 09:27:18&TradeNo=2502080927183709&HashIV=EkRm7iFT261dpevs
(3) 將整串字串進行URL encode
HashKey%3DpwFHCqoQZGmho4w6%26CustomField1%3D%26CustomField2%3D%26CustomField3%3D%26CustomField4%3D%26MerchantID%3D3002607%26MerchantTradeNo%3DECPay1738978034%26PaymentDate%3D2025%2F02%2F08+09%3A32%3A20%26PaymentType%3DCredit_CreditCard%26PaymentTypeChargeFee%3D1%26RtnCode%3D1%26RtnMsg%3D%E4%BA%A4%E6%98%93%E6%88%90%E5%8A%9F%26SimulatePaid%3D0%26StoreID%3D%26TradeAmt%3D30%26TradeDate%3D2025%2F02%2F08+09%3A27%3A18%26TradeNo%3D2502080927183709%26HashIV%3DEkRm7iFT261dpevs
(4) 轉為小寫
hashkey%3dpwfhcqoqzgmho4w6%26customfield1%3d%26customfield2%3d%26customfield3%3d%26customfield4%3d%26merchantid%3d3002607%26merchanttradeno%3decpay1738978034%26paymentdate%3d2025%2f02%2f08+09%3a32%3a20%26paymenttype%3dcredit_creditcard%26paymenttypechargefee%3d1%26rtncode%3d1%26rtnmsg%3d%e4%ba%a4%e6%98%93%e6%88%90%e5%8a%9f%26simulatepaid%3d0%26storeid%3d%26tradeamt%3d30%26tradedate%3d2025%2f02%2f08+09%3a27%3a18%26tradeno%3d2502080927183709%26hashiv%3dekrm7ift261dpevs
(5) 以 sha256 方式產生雜凑值
c66199663dd43bf01058218601bee874315e5ff57a1fe112a9114ac3701947ba
(6) 再轉大寫產生 CheckMacValue
C66199663DD43BF01058218601BEE874315E5FF57A1FE112A9114AC3701947BA
8. 比對正確，表示確實是綠界發送的，而非假冒。
CheckMacValue 都是 C66199663DD43BF01058218601BEE874315E5FF57A1FE112A9114AC3701947BA，比對正確。
請注意：
(1) HashKey、 HashIV 僅可用來計算 CheckMacValue，不可用來當參數發送。
(2)特店發給綠界的 CheckMacValue 與綠界發給特店的 CheckMacValue 不同，因為兩方用來計算的參數也不同。
以上就是 CheckMacValue 的基本運作流程說明。若遇到 CheckMaValue Error (10200073)，請再參閱 CheckMacValue Error 常見原因，或聯繫技術支援並提供所有參數。
How does CheckMacValue Work?
繁中 | ENG
When integrating All In One Payment and Logistics API, the parameter CheckMacValue is to verify received messages in case of forgeries. Otherwise, anyone could impersonate a merchant or ECPay when sending messages.
The HashKey and HashIV are confidential credentials shared exclusively between the merchant and ECPay. The CheckMacValue is generated by performing a hash calculation on all request parameters using these credentials as cryptographic keys.
The receiver generates CheckMacValue with the same HashKey and Hash IV to verify the sender’s identity and prevents impersonation attacks.
All In One CheckMacValue Mechanism: https://developers.ecpay.com.tw/?p=16623
Logistics Mechanism: https://developers.ecpay.com.tw/?p=22539
Take All In One payment for exmple, here’s the general process flow:
I. Creating an order
1. Prepare the order parameters and generate the CheckMacValue using the credentials.
2. These parameters along with the CheckMacValue are to be sent to ECPay as thr Request.
3. Upon receiving the merchant’s Request, ECPay recalculates the CheckMacValue using the received parameters and compares it with the one from the Request.
4. If the values match, it confirms the Request is genuinely from the merchant, not an impostor. The user is then redirected to the All In One payment page.
5. Payment is completed on the payment platform page.
II. Payment Notification
6. After payment completion, ECPay sends a payment notification to the merchant, including various parameters and a CheckMacValue.
7. The merchant recalculates the CheckMacValue using the received parameters and compares it with the CheckMacValue provided by ECPay.
Every step is explained below.
1. Prepare the order parameters
{
"ChoosePayment": "ALL",
"EncryptType": "1",
"ItemName": "myItem",
"MerchantID": "3002607",
"MerchantTradeDate": "2025/02/08 09:27:23",
"MerchantTradeNo": "ECPay1738978043",
"PaymentType": "aio",
"ReturnURL": "https://08f6-211-23-76-78.ngrok-free.app/returnurl.php",
"TotalAmount": "30",
"TradeDesc": "Trade"
}
Generate the CheckMacValue using the credentials
(1) The query string to be be sorted alphabetically (A-Z) and linked with an ampersand (&)
ChoosePayment=ALL&EncryptType=1&ItemName=myItem&MerchantID=3002607&MerchantTradeDate=2025/02/08 09:27:23&MerchantTradeNo=ECPay1738978043&PaymentType=aio&ReturnURL=https://08f6-211-23-76-78.ngrok-free.app/returnurl.php&TotalAmount=30&TradeDesc=Trade
(2) The query string will be sandwiched by HashKey in the front and HashIV at the bottom.
HashKey=pwFHCqoQZGmho4w6&ChoosePayment=ALL&EncryptType=1&ItemName=myItem&MerchantID=3002607&MerchantTradeDate=2025/02/08 09:27:23&MerchantTradeNo=ECPay1738978043&PaymentType=aio&ReturnURL=https://08f6-211-23-76-78.ngrok-free.app/returnurl.php&TotalAmount=30&TradeDesc=Trade&HashIV=EkRm7iFT261dpevs
(3) The entire string will go through URL encoding.
HashKey%3DpwFHCqoQZGmho4w6%26ChoosePayment%3DALL%26EncryptType%3D1%26ItemName%3DmyItem%26MerchantID%3D3002607%26MerchantTradeDate%3D2025%2F02%2F08+09%3A27%3A23%26MerchantTradeNo%3DECPay1738978043%26PaymentType%3Daio%26ReturnURL%3Dhttps%3A%2F%2F08f6-211-23-76-78.ngrok-free.app%2Freturnurl.php%26TotalAmount%3D30%26TradeDesc%3DTrade%26HashIV%3DEkRm7iFT261dpevs
(4) Switched to lowercase
hashkey%3dpwfhcqoqzgmho4w6%26choosepayment%3dall%26encrypttype%3d1%26itemname%3dmyitem%26merchantid%3d3002607%26merchanttradedate%3d2025%2f02%2f08+09%3a27%3a23%26merchanttradeno%3decpay1738978043%26paymenttype%3daio%26returnurl%3dhttps%3a%2f%2f08f6-211-23-76-78.ngrok-free.app%2freturnurl.php%26totalamount%3d30%26tradedesc%3dtrade%26hashiv%3dekrm7ift261dpevs
(5) The string is then encrypted using SHA256 to generate a hash value
f1fb466ed0d6713dac7158ab6705914e37c93bd44fb8fa44c17f80cd17bb5728
(6) It is then converted into upper case to generate a CheckMacValue
F1FB466ED0D6713DAC7158AB6705914E37C93BD44FB8FA44C17F80CD17BB5728
2. These parameters along with the CheckMacValue are to be sent to ECPay as the Request (The JSON format is for readability purposes only. When making actual API requests, please comply with the API’s transmission protocol.)
{
"ChoosePayment": "ALL",
"EncryptType": "1",
"ItemName": "myItem",
"MerchantID": "3002607",
"MerchantTradeDate": "2025/02/08 09:27:23",
"MerchantTradeNo": "ECPay1738978043",
"PaymentType": "aio",
"ReturnURL": "https://08f6-211-23-76-78.ngrok-free.app/returnurl.php",
"TotalAmount": "30",
"TradeDesc": "Trade",
"CheckMacValue":"F1FB466ED0D6713DAC7158AB6705914E37C93BD44FB8FA44C17F80CD17BB5728"
}
3. ECPay recalculates the CheckMacValue based on received parameters and compares it with the merchant-provided CheckMacValue.
4. Upon successful validation, confirming merchant authenticity, redirect to All In One payment page.
5. Complete payment on All In One payment page.
6. After payment completion, ECPay sends a payment notification to the merchant, including various parameters and a CheckMacValue.
CustomField1=&CustomField2=&CustomField3=&CustomField4=&MerchantID=3002607&MerchantTradeNo=ECPay1738978034&PaymentDate=2025/02/08 09:32:20&PaymentType=Credit_CreditCard&PaymentTypeChargeFee=1&RtnCode=1&RtnMsg=交易成功&SimulatePaid=0&StoreID=&TradeAmt=30&TradeDate=2025/02/08 09:27:18&TradeNo=2502080927183709&CheckMacValue=C66199663DD43BF01058218601BEE874315E5FF57A1FE112A9114AC3701947BA
7. The merchant recalculates the CheckMacValue using the received parameters and compares it with the CheckMacValue provided by ECPay.
(1) The query string to be be sorted alphabetically (A-Z) and linked with an ampersand (&)
CustomField1=&CustomField2=&CustomField3=&CustomField4=&MerchantID=3002607&MerchantTradeNo=ECPay1738978034&PaymentDate=2025/02/08 09:32:20&PaymentType=Credit_CreditCard&PaymentTypeChargeFee=1&RtnCode=1&RtnMsg=交易成功&SimulatePaid=0&StoreID=&TradeAmt=30&TradeDate=2025/02/08 09:27:18&TradeNo=2502080927183709
(2) The query string will be sandwiched by HashKey in the front and HashIV at the bottom.
HashKey=pwFHCqoQZGmho4w6&CustomField1=&CustomField2=&CustomField3=&CustomField4=&MerchantID=3002607&MerchantTradeNo=ECPay1738978034&PaymentDate=2025/02/08 09:32:20&PaymentType=Credit_CreditCard&PaymentTypeChargeFee=1&RtnCode=1&RtnMsg=交易成功&SimulatePaid=0&StoreID=&TradeAmt=30&TradeDate=2025/02/08 09:27:18&TradeNo=2502080927183709&HashIV=EkRm7iFT261dpevs
(3) The entire string will go through URL encoding.
HashKey%3DpwFHCqoQZGmho4w6%26CustomField1%3D%26CustomField2%3D%26CustomField3%3D%26CustomField4%3D%26MerchantID%3D3002607%26MerchantTradeNo%3DECPay1738978034%26PaymentDate%3D2025%2F02%2F08+09%3A32%3A20%26PaymentType%3DCredit_CreditCard%26PaymentTypeChargeFee%3D1%26RtnCode%3D1%26RtnMsg%3D%E4%BA%A4%E6%98%93%E6%88%90%E5%8A%9F%26SimulatePaid%3D0%26StoreID%3D%26TradeAmt%3D30%26TradeDate%3D2025%2F02%2F08+09%3A27%3A18%26TradeNo%3D2502080927183709%26HashIV%3DEkRm7iFT261dpevs
(4) Switched to lowercase
hashkey%3dpwfhcqoqzgmho4w6%26customfield1%3d%26customfield2%3d%26customfield3%3d%26customfield4%3d%26merchantid%3d3002607%26merchanttradeno%3decpay1738978034%26paymentdate%3d2025%2f02%2f08+09%3a32%3a20%26paymenttype%3dcredit_creditcard%26paymenttypechargefee%3d1%26rtncode%3d1%26rtnmsg%3d%e4%ba%a4%e6%98%93%e6%88%90%e5%8a%9f%26simulatepaid%3d0%26storeid%3d%26tradeamt%3d30%26tradedate%3d2025%2f02%2f08+09%3a27%3a18%26tradeno%3d2502080927183709%26hashiv%3dekrm7ift261dpevs
(5) The string is then encrypted using SHA256 to generate a hash value
c66199663dd43bf01058218601bee874315e5ff57a1fe112a9114ac3701947ba
(6) It is then converted into upper case to generate a CheckMacValue
C66199663DD43BF01058218601BEE874315E5FF57A1FE112A9114AC3701947BA
8. If the values match, it confirms the notification is genuinely from ECPay, not an impostor.
CheckMacValues are both C66199663DD43BF01058218601BEE874315E5FF57A1FE112A9114AC3701947BA. Match confirmed.
Note:
(1)HashKey and HashIV are only for generating CheckMacValue. They cannot be sent as parameters.
(2)The CheckMacValue sent from the merchant to ECPay and the one sent from ECPay to the merchant are different, since the parameters used for generating are different.
The above describes the basic flow of CheckMacValue. If you encounter a CheckMacValue Error (10200073), please kindly contact TechSupport and provide all of the parameters.
