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=促銷方案
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
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.
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.
6c51c9e6888de861fd62fb1dd17029fc742634498fd813dc43d4243b5685b840
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.