Appendix / Checksum Mechanism

Explanation

When transmitting data with ECPay, please refer to the respective APIs and include a checksum verification mechanism for the parameters sent within the “Data” field. Non-required parameters that are not sent can be excluded from the calculation.

The merchant must verify the accuracy of CheckMacValue and confirm if the corresponding notification has been processed. Failure to do so may expose the data transmission to unnecessary risks and losses due to potential tampering.

Special Note:

The merchant must check [CheckMacValue] to verify when they receive information transmitted by ECPay . If the merchant does not check, they may suffer from losses.
Please use SHA256 encryption to generate hash values.
If you are using .NET as the development language, please be aware that this specification has been revised to update the URLEncode encoding conversion method. It differs from the encoding method in the current ECPay “All-In-One API Document – Appendix/Checksum Mechanism“. It is recommended to use the “Uri.EscapeDataString” method for the conversion calculation.

Calculation Formula

CheckMacValue= SHA256(URLEncode(HashKey+Data plaintext+HashIV))

The checksum works as follows

(1) Extract the plaintext parameter Data as a string.

				
					{"MerchantID":"3085676","MerchantTradeNo":"CX202202221540568521"}

(2) The string will be sandwiched by HashKey in the front and HashIV at the bottom.

				
					7b53896b742849d3{"MerchantID":"3085676","MerchantTradeNo":"CX202202221540568521"}37a0ad3c6ffa428b

(3) The entire string will go through URL encoding.

				
					7b53896b742849d3%7B%22MerchantID%22%3A%223085676%22%2C%22MerchantTradeNo%22%3A%22CX202202221540568521%22%7D37a0ad3c6ffa428b

(4) Switched to lowercase.

				
					7b53896b742849d3%7b%22merchantid%22%3a%223085676%22%2c%22merchanttradeno%22%3a%22cx202202221540568521%22%7d37a0ad3c6ffa428b

(5) The string is then encrypted using SHA256 to generate a hash value.

				
					ce67bbd259ee38ba1c7fb7cc88c3bd91d3f082b46eaebd4e4e5f2184cb23349a

(6) It is then converted into upper case to generate a CheckMacValue.

				
					CE67BBD259EE38BA1C7FB7CC88C3BD91D3F082B46EAEBD4E4E5F2184CB23349A

PHP Example Code

				
					<?php
echo "(1)Extract the plaintext parameter Data as a string.<BR/>";
$data="{\"MerchantID\":\"3085676\",\"MerchantTradeNo\":\"CX202202221540568521\"}";
echo " $data <BR/>";

echo "(2)The string will be sandwiched by HashKey in the front and HashIV at the bottom.<BR/>";
$data="7b53896b742849d3".$data."37a0ad3c6ffa428b";
echo " $data <BR/>";

echo "(3)The entire string will go through URL encoding.<BR/>";
$txt = urlencode($data);
echo  " $txt <BR/>";

echo "(4)Switched to lowercase.<BR/>";
$txt = strtolower($txt);
echo  " $txt <BR/>";

echo "(5)The string is then encrypted using SHA256 to generate a hash value.<BR/>";
$txt =hash('sha256', $txt);
echo " $txt <BR/>";

echo "(6)It is then converted into upper case to generate a CheckMacValue.<BR/>";
$txt =strtoupper($txt);
echo " $txt <BR/>";

?>

Green World