Appendix / Checksum Mechanism

Checksum Mechanism

When POST data to ECPay , all parameters/fields and values must go through checksum except for the field [CheckMacValue]. The following demonstrates how checksum works step by step when calling API [AioCheckOut] (to create an order).

The following is an example of a query string to be encrypted

				
					TradeDesc=促銷方案&PaymentType=aio&MerchantTradeDate=2023/03/12 15:30:23&MerchantTradeNo=ecpay20230312153023&MerchantID=3002607&ReturnURL=https://www.ecpay.com.tw/receive.php&ItemName=Apple iphone 15&TotalAmount=30000&ChoosePayment=ALL&EncryptType=1

The checksum works as follows

(1) The query string to be be sorted alphabetically (A-Z) and linked with an ampersand (&).

				
					ChoosePayment=ALL&EncryptType=1&ItemName=Apple iphone 15&MerchantID=3002607&MerchantTradeDate=2023/03/12 15:30:23&MerchantTradeNo=ecpay20230312153023&PaymentType=aio&ReturnURL=https://www.ecpay.com.tw/receive.php&TotalAmount=30000&TradeDesc=促銷方案

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

				
					HashKey=pwFHCqoQZGmho4w6&ChoosePayment=ALL&EncryptType=1&ItemName=Apple iphone 15&MerchantID=3002607&MerchantTradeDate=2023/03/12 15:30:23&MerchantTradeNo=ecpay20230312153023&PaymentType=aio&ReturnURL=https://www.ecpay.com.tw/receive.php&TotalAmount=30000&TradeDesc=促銷方案&HashIV=EkRm7iFT261dpevs

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

				
					HashKey%3dpwFHCqoQZGmho4w6%26ChoosePayment%3dALL%26EncryptType%3d1%26ItemName%3dApple+iphone+15%26MerchantID%3d3002607%26MerchantTradeDate%3d2023%2f03%2f12+15%3a30%3a23%26MerchantTradeNo%3decpay20230312153023%26PaymentType%3daio%26ReturnURL%3dhttps%3a%2f%2fwww.ecpay.com.tw%2freceive.php%26TotalAmount%3d30000%26TradeDesc%3d%e4%bf%83%e9%8a%b7%e6%96%b9%e6%a1%88%26HashIV%3dEkRm7iFT261dpevs

Special Note：

If using PHP, use urlencode() (RFC 1866) and use str_replace() to replace the characters according to the urlencode conversion table.

(4) Switched to lowercase

				
					hashkey%3d5294y06jbispm5x9%26choosepayment%3dall%26encrypttype%3d1%26itemname%3dapple+iphone+7+%e6%89%8b%e6%a9%9f%e6%ae%bc%26merchantid%3d2000132%26merchanttradedate%3d2013%2f03%2f12+15%3a30%3a23%26merchanttradeno%3decpay20130312153023%26paymenttype%3daio%26returnurl%3dhttps%3a%2f%2fwww.ecpay.com.tw%2freceive.php%26totalamount%3d1000%26tradedesc%3d%e4%bf%83%e9%8a%b7%e6%96%b9%e6%a1%88%26hashiv%3dv77hokgq4kwxnnis

Special Note： Use strtolower() if you are using PHP.

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

				
					6c51c9e6888de861fd62fb1dd17029fc742634498fd813dc43d4243b5685b840

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

				
					6C51C9E6888DE861FD62FB1DD17029FC742634498FD813DC43D4243B5685B840

Special Note：

(1) 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.
(2) Please use SHA256 encryption to generate hash values.
(3) Please make sure that the the converted results after UrlEncode function in your language corresponds to the “.NET Encoding (ecpay)” value in the URLENCODE CONVERSION TABLE. If there are any unsupported characters, please use the character replacement function so the results will pass the checksum test.
For example: PHP urlencode function will encode ! Into %21, which is not accepted according to the “.NET encoding (ecpay)” rules, so the %21 will have to be converted back into ! With str_replace function after the PHP urlencode function. Here’s a PHP conversion example:

$sMacValue = str_replace(‘%2d’, ‘-‘, $sMacValue);
$sMacValue = str_replace(‘%5f’, ‘_’, $sMacValue);
$sMacValue = str_replace(‘%2e’, ‘.’, $sMacValue);
$sMacValue = str_replace(‘%21’, ‘!’, $sMacValue);
$sMacValue = str_replace(‘%2a’, ‘*’, $sMacValue);
$sMacValue = str_replace(‘%28’, ‘(‘, $sMacValue);
$sMacValue = str_replace(‘%29’, ‘)’, $sMacValue);

For conversion functions in other programming languages, please refer to the relevant encoding conversion rules.

Program example

Green World