Appendix / Checksum

Description

When sending data to ECPay’s API, the payload of key and values must go through the checksum to generate the value of [CheckMacValue]. Following demonstrates how the checksum works.

For example, following is the text/plain to be generated into CheckMacValue.

				
					MerchantID=2000933&MerchantTradeNo=A20130312153023&MerchantTradeDate=2013/03/12 15:30:23&LogisticsType=CVS&LogisticsSubType=FAMIC2C&GoodsAmount=1000&IsCollection=N&ServerReplyURL=https://www.ecpay.com.tw/ServerReplyURL&SenderName=SteveJones&ReceiverName=MarkHarrison&ReceiverStoreID=001779

Steps of the the checksum generation

(1) Sort alphabetically (A-Z) and link the key and value with an ampersand (&) (ECPay’s API accepts the content-type: application/x-www-form-urlencoded).

				
					GoodsAmount=1000&IsCollection=N&LogisticsSubType=FAMIC2C&LogisticsType=CVS&MerchantID=2000933&MerchantTradeDate=2013/03/12 15:30:23&MerchantTradeNo=A20130312153023&ReceiverName=MarkHarrison&ReceiverStoreID=001779&SenderName=SteveJones&ServerReplyURL=https://www.ecpay.com.tw/ServerReplyURL

(2)Sandwich the above string with HashKey and HashIV.

				
					HashKey=XBERn1YOvpM9nfZc&GoodsAmount=1000&IsCollection=N&LogisticsSubType=FAMIC2C&LogisticsType=CVS&MerchantID=2000933&MerchantTradeDate=2013/03/12 15:30:23&MerchantTradeNo=A20130312153023&ReceiverName=MarkHarrison&ReceiverStoreID=001779&SenderName=SteveJones&ServerReplyURL=https://www.ecpay.com.tw/ServerReplyURL&HashIV=h1ONHk4P4yqbl5LK

(3)Do urlencode the entire string

				
					HashKey%3dXBERn1YOvpM9nfZc%26GoodsAmount%3d1000%26IsCollection%3dN%26LogisticsSubType%3dFAMIC2C%26LogisticsType%3dCVS%26MerchantID%3d2000933%26MerchantTradeDate%3d2013%2f03%2f12+15%3a30%3a23%26MerchantTradeNo%3dA20130312153023%26ReceiverName%3d%e6%94%b6%e4%bb%b6%e8%80%85%e5%a7%93%e5%90%8d%26ReceiverStoreID%3d001779%26SenderName%3d%e5%af%84%e4%bb%b6%e8%80%85%e5%a7%93%e5%90%HashKey%3dXBERn1YOvpM9nfZc%26GoodsAmount%3d1000%26IsCollection%3dN%26LogisticsSubType%3dFAMIC2C%26LogisticsType%3dCVS%26MerchantID%3d2000933%26MerchantTradeDate%3d2013%2f03%2f12+15%3a30%3a23%26MerchantTradeNo%3dA20130312153023%26ReceiverName%3dMarkHarrison%26ReceiverStoreID%3d001779%26SenderName%3dSteveJones%26ServerReplyURL%3dhttps%3a%2f%2fwww.ecpay.com.tw%2fServerReplyURL%26HashIV%3dh1ONHk4P4yqbl5LK%26ServerReplyURL%3dhttps%3a%2f%2fwww.ecpay.com.tw%2fServerReplyURL%26HashIV%3dh1ONHk4P4yqbl5LK

Sample of PHP urlencoding

				
					HashKey%3dXBERn1YOvpM9nfZc%26GoodsAmount%3d1000%26IsCollection%3dN%26LogisticsSubType%3dFAMIC2C%26LogisticsType%3dCVS%26MerchantID%3d2000933%26MerchantTradeDate%3d2013%2f03%2f12%2015%3a30%3a23%26MerchantTradeNo%3dA20130312153023%26ReceiverName%3dMarkHarrison%26ReceiverStoreID%3d001779%26SenderName%3dSteveJones%26ServerReplyURL%3dhttps%3a%2f%2fwww.ecpay.com.tw%2fServerReplyURL%26HashIV%3dh1ONHk4P4yqbl5LK

(4)Lowercase the string

				
					hashkey%3dxbern1yovpm9nfzc%26goodsamount%3d1000%26iscollection%3dn%26logisticssubtype%3dfamic2c%26logisticstype%3dcvs%26merchantid%3d2000933%26merchanttradedate%3d2013%2f03%2f12+15%3a30%3a23%26merchanttradeno%3da20130312153023%26receivername%3dmarkharrison%26receiverstoreid%3d001779%26sendername%3dstevejones%26serverreplyurl%3dhttps%3a%2f%2fwww.ecpay.com.tw%2fserverreplyurl%26hashiv%3dh1onhk4p4yqbl5lk

Sample of PHP

				
					hashkey%3dxbern1yovpm9nfzc%26goodsamount%3d1000%26iscollection%3dn%26logisticssubtype%3dfamic2c%26logisticstype%3dcvs%26merchantid%3d2000933%26merchanttradedate%3d2013%2f03%2f12%2015%3a30%3a23%26merchanttradeno%3da20130312153023%26receivername%3dmarkharrison%26receiverstoreid%3d001779%26sendername%3dstevejones%26serverreplyurl%3dhttps%3a%2f%2fwww.ecpay.com.tw%2fserverreplyurl%26hashiv%3dh1onhk4p4yqbl5lk

(5)Replace characters according to the urlencode conversion table (used if using PHP for URL encoding)

				
					hashkey%3dxbern1yovpm9nfzc%26goodsamount%3d1000%26iscollection%3dn%26logisticssubtype%3dfamic2c%26logisticstype%3dcvs%26merchantid%3d2000933%26merchanttradedate%3d2013%2f03%2f12+15%3a30%3a23%26merchanttradeno%3da20130312153023%26receivername%3dmarkharrison%26receiverstoreid%3d001779%26sendername%3dstevejones%26serverreplyurl%3dhttps%3a%2f%2fwww.ecpay.com.tw%2fserverreplyurl%26hashiv%3dh1onhk4p4yqbl5lk

(6)Use MD5 encryption to generate the hash value (CheckMacValue)

				
					MD5: 754c5d1365035da34d2cd91cc256f18c

(7)Uppercase it

				
					MD5: 754C5D1365035DA34D2CD91CC256F18C

Special Note：

(1) When receiving data from Green World, [CheckMacValue] must be verified.

(2) Ensure that the result of URL Encode function matches with the .NET encoding (ecpay) parameter value in the URL Encode conversion table in the appendix. Any mismatched characters must be replaced using character replacement function in order to avoid non-compliance.For example, PHP URL Encode function will encode ! as %21, which does not match .NET encoding (ecpay), hence after PHP URL Encode process, the str_replace function must be used to change %21 back to !.The following uses PHP to illustrate a 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 function of other programming languages, please follow the code conversion rules of that particular programming language.

Green World