Architecture Explanation and Recommendations

Note

Following the recommendations will ensure the security and integrity of the data. You should always store the SALT key securely in your server.

The end user, firstly starts the payment from your app.

Your Android app’s code sets the payment parameters collected from the user and initiates the payment via the Payment Gateway SDK using the classes PaymentParams and PaymentGatewayPaymentInitializer respectively. This is explained in the “Code Explanation” session of this doc.

Payment Gateway SDK actually uses the Payment Gateway Server during the payment process.

Once the payment is completed, the Payment Gateway server sends the Payment Response to the Payment Gateway SDK as well as to your return URL/API.

Recommendations: Your return API/URL on receiving the payment response should perform the below functions:

a) Verify the data authenticity by verifying the HASH: Your webserver code for return API should verify the HASH value received in the payment response to ensure no tampering in the response data. The below shows the recommendations on how the response should be handled in your web server:

  • Once the payment response is received as the POST parameter to your return URL, you should extract and store the “Hash key” that is included in the Payment response.

  • Use the parameters to calculate the HASH once again in your server using SHA-512 algorithm as shown in the next step.

  • Now compare the newly calculated HASH with the HASH in the payment response. If the HASH matches, then store them in your DB server.

b) The below diagram represents how to calculate HASH from the payment response parameters:

The Hash Data String should look something like this:

<SALT>|<address_line_1>|<address_line_2>|<amount>|<cardmasked>|<city>|<country>|<currency>|<description>|<email>|<error_desc>|<name>|<order_id>|<payment_channel>|<payment_datetime>|<payment_mode>|<phone>|<response_code>|<response_message>|<state>|<transaction_id>|<udf1>|<udf2>|<udf3>|<udf4>|<udf5>|<zip_code>

The Hash Key should look something like this:

3E98057AB8600765F28A5085712FC652B4904D27E12D94E19FB13A7D64464D2F22ECECFA413ED874DE984B442B4755D144AAECEB2A6B87380C189213E8C51DD7

Sample Code in PHP to Calculate the HASH as an example:

  private function verifyHash($input, $salt)
	{
	        $responseHash = $input["hash"];
	        unset($input["hash"]);
		
		/*Sort the array before hashing*/
		ksort($input);

		/*Create a | (pipe) separated string of all the $input values which are available in $hash_columns*/
		$hash_data = $salt;
		foreach ($input as $inputParam) {
			if (isset($inputParam)) {
				if (strlen($inputParam) > 0) {
					$hash_data .= '|' . trim($inputParam) ;
				}
			}
		}
		/* Convert the $hash_data to Upper Case and then use SHA512 to generate hash key */
		$hash = null;
		if (strlen($hash_data) > 0) {
			$hash = strtoupper(hash("sha512", $hash_data));
		}
		
		if($hash==$responseHash) return true;

		return false;
	}

Once the response parameters are received from the POST parameters and HASH is extracted, we should recalculate the HASH with the SALT key stored securely in your server using SHA-512 algorithm.

  • Firsly, use trim on all the response parameters values.

  • Sort all response parameter keys by ascending order.

  • Concatenate all the response parameter values by pipe line character:"|" to get HASH data string.

  • Now, perform SHA-512 algortihm on them to get the HASH data string to get the HASH.

  • Finally, convert the HASH to uppercase before HASH comparison discussed in the above point.

The SDK receives the payment response and parses them into a JSON response. The Json response is passed on to the client’s code via onActivityResult() method.

Recommendations: You must verify if the amount and order_id from the payment response Json matches exactly with the amount and response stored in your server during step 4(explained in step 4 recommendations).

If the amount and order_id matches with the DB server, then display the response and other required details to the end user.