RDP Merchant API

Message Data

Service End Points

The URL service end points for the merchant API are as follow:

Transaction Request Parameters

Transaction Response Parameters

Transaction Signature

An electronic hash signature is included as part of data integrity measurement for transaction request and response interface between merchant’s system and RDP payment gateway. By using the transaction signature field, both merchant and RDP payment gateway system can ensure and identify that the transaction request and/or response are really coming from a trusted and valid specific source.

The transaction signature field inside the merchant’s transaction request message is formed by hashing all of request fields sent in HTTP POST, but excluding the ‘signature’ field itself. Field names and values need to be separated with “=” character, and subsequently, all parameters have to be sorted ascending based on ASCII character table, before they are combined together by using “&” (ampersand character) between those parameters.

Finally please add ‘&secret_key=<merchant’s secret key>’ at the end of the result string, followed by hashing the entire string in order to get or create the transaction signature. The hashing method will be using MD5 method, and the ‘signature’ field would be included as one of the HTTP POST parameters in small caps.

Notes:

  1. The ‘secret_key‘ field and value are only used as part of ‘signature’ field calculation, and must NOT be sent to RDP Connect payment gateway.
    Example Checking Response Signature:
    • Sample information :
      • Merchant’s URL = http://www.merchantexample.com/trans-url
      • Merchant’s secret key = REDDOT
      • RDP Response Parameters:
    • result_status = accepted
    • reason_code = 00
    • order_number = 20151130001
    • amount = 1.00
    • currency = SGD
    • timestamp = 2015-11-30 12:34:56
    • signature = b6c61c27a2692ba1a467265d4188ba6fBelow are those steps to prepare, calculate and compare the transaction signature that should be done by merchant system when they get a response message from RDP payment gateway.

  1. RDP payment gateway sent a GET request message to merchant’s system together with the calculated signature, where it will be corresponding URL.The sample is as follow (no white spaces between all characters):
http://www.merchantexample.com/trans-url?result_status=accepted&reason_code=00&order_number=20151130001& amount=1.00&currency=SGD&timestamp=2015-11-30%2012:34:56&signature=9dd4202b429cf4953900ef4ae30e691b

2. Now the merchant system needs to do some checks whether the received response message is really coming from RDP payment gateway.Merchant can get the response by accessing the GET parameters of the HTTP request. This might depend on each framework implementation. Sample code in PHP language:

//The response is in an associative array retrieved from GET request 
$rdp_response = $_GET;

3. The transaction signature from RDP payment gateway will be inside the field “signature”. Sample code in PHP language, on how to retrieve the signature field:

$rdp_signature = $_GET[“signature”];

4. On the next step, merchant needs to get the list of key-value of the GET parameters, but without the ‘signature’ field. This parameter list will be required in order to calculate the signature. Sample code in PHP language:

unset($rdp_response ['signature']);

5. Continue with the process of calculating signature, merchant will need to sort all the parameters (except for ‘signature’ field) based on the key in ascending order. Sample code in PHP language:

ksort($rdp_response);

6. Construct a string based on the key and value of those parameters from step 5. Sample code in PHP language:

$string_to_hash = “”; foreach ($rdp_response as $key=>$value) { $string_to_hash .= $ key . '=' . ($value) . '&'; }

7. Concatenate the string made in previous step with the ‘secret_key’ field. Sample code in PHP language:

$secret_key = “D716A4188569B68AB1B6DFAC178E570114CDF0EA3A1CC0E31486C3E41241BC6A76424E8C37AB26F096FC85EF9886C8CB634187F4FDDFF645FB099F1FF54C6B8C”; $string_to_hash .= 'secret_key=' . $ secret_key;

Note:

The secret key information should only be known by Red Dot Payment and merchant, so please never give the information in a publicly accessible channel.

8. Now please calculate the signature by doing MD5 hashing on the string created in step Sample code in PHP language:

$merchant_calculated_signature = md5($string_to_hash);

9. Finally merchant needs to compare whether their calculated signature result (from step 8) is similar with the received signature field in their GET request (from step 3). Sample code in PHP language:

$is_really_from_rdp = ($merchant_calculated_signature == $rdp_signature);

The calculated signature result should be similar with the received signature field in their GET request.

Please take note that the ‘signature’ field inside RDP response message will not always be available or exist; and might only be available or exist for these following response codes: