Checksum
The checksum field of each request and response is obtained by computing the concatenated values in order to obtain a block of text which is then hashed with SHA256. The hashing key is known to both parties (sender and receiver). This chapter illustrates how the checksum is performed and calculated for Request and Response JSON message and Request with a query string as parameter(s) of API service.
REMARKS:
DO NOT SKIP CHECKSUM VALIDATION: It is vital that all parties validate the checksum in EVERY request and response, as it is the only way to ensure that the JSON message or Query String have not been tampered with.
Decimals in JSON do not have trailing zeroes. For example:
1250.50 is represented as 1250.5
354.00 is represented as 354
However, when performing checksum, the amount must have 2-digit decimal points.
Sequence Number in JSON Array Object#
For the purpose of calculating checksum on the array of JSON objects, sequence number will be added to each objects in the array.
For example: as per JSON example below, each objects in the “terminals” array contains a sequence number (“seqNo”) which can be used to identify the order of that object inside the array and hence, the sequence number can tell which object in the array will be performing the checksum first.
Checksum for JSON Request and Response Message#
This chapter provides checksum example for Request and Response JSON message. To calculate the checksum for JSON message, the value of JSON objects have to be concatenated. The sequence of the concatenated values is placed based on the attribute name of JSON object in alphabetical order.
If JSON object contain another JSON objects, then, it shall be going thorough those JSON objects first in alphabetical order to concatenate their values until the last object of that branch is reached.
if JSON object is an array of objects, each object in an array then, will contain a sequence number (SeqNo) which represent the order of that object in an array. This sequence number will tell which object in an array will have to perform the checksum first which always start at sequence number one.
Again, concatenating the value based on the attribute name of JSON object in alphabetical order. After obtaining the concatenated values, apply the HASH SHA256 to it to obtain the checksum.
JSON message below will be used to show example checksum calculation.
As per JSON message above, the concatenated values will be in this order:
| Order # | Name | Value |
|---|---|---|
| 1 | pageInfo/totalPage | 10 |
| 2 | pageInfo/totalRecord | 250 |
| 3 | responseCode | 000 |
| 4 | terminals/seqNo | 1 |
| 5 | terminals/terminalID | 20001 |
| 6 | terminals/terminalName | Cashier 1 |
| 7 | terminals/seqNo | 2 |
| 8 | terminals/terminalID | 20002 |
| 9 | terminals/terminalName | Cashier 2 |
If "terminals" array is presented, then, traverse through objects in the array in accordance with sequence number of the object.
The result of the values concatenation is: “10250000120001Cashier 1220002 Cashier 2”
Then, calculates the checksum of the concatenated values using SHA256 and example hash key: ‘ABCDEF’
Hence, the checksum of this message is: BD0A1BBEDC9FA82E0C65586101862238202245CD09A53DE8E5E1A0E3D08A1C46
The checksum is then placed at the end of each request and response JSON message for integrity check.
Checksum for Request with Query String#
This chapter provides checksum example for the Request that contains query string. To calculate the checksum for the query string, the value of parameters has to be concatenated. The sequence of the values is in accordance with the name of parameter in alphabetical order. Then, apply the HASH SHA256 to the concatenated values to obtain the checksum.
Assumes that we call API method to get a list of terminal.
Request example without checksum:
https://{DomainName}/QRGW/v2/terminals?pageNo=1&pageSize=25&sortBy=terminalID&sortDirection=ASC&merchantID=20002
The API method accepts following parameters for a query string as per table below.
| Field Name | Type | Description | Example Value |
|---|---|---|---|
| pageSize | number | Number of transaction per page. | 25 |
| pageNo | number | Page index to navigate through all the pages | 1 |
| sortBy (Optional) | string | Field name to sorted the result list | Assume that there is no value presented for this field. |
| sortDirection (Optional) | string | ASC or DESC (default is DESC) | ASC |
| merchantID | string | Merchant Unique ID under a company | 20002 |
As per parameters table above, the concatenated values are: Value(merchantID) + Value(pageNo) + Value(pageSize) + Value(sortBy) + Value(sortDirection)
As ‘sortBy’ field contains no value, so, the value of this field can be skipped for checksum as per result of the concatenation below.
The result of the concatenation is: “20002125ASC”
Then, calculates the checksum of the concatenated values using SHA256 and example hash key: ‘ABCDEF’
Hence, the checksum of this message is: A9E13580617ED5B15B05AA076737DC22CE494FB45ED6A0F8ADB014F11D694F70
The checksum is then placed at the end of query string of each request as per example below.
Request example with checksum:
https://{DomainName}/QRGW/v2/terminals?pageNo=1&pageSize=25&sortBy=terminalID&sortDirection=ASC&merchantID=20002&checksum=A9E13580617ED5B15B05AA076737DC22CE494FB45ED6A0F8ADB014F11D694F70
Note:
- If parameter field is optional and not presented, then, the field can be ignored for the checksum.
- Value() returns a value of the parameter. If the value of the parameter is ‘null’, then, this value can also be skipped for the checksum.