RDP Direct APIs

Query Result Handling

Query Result Description

This is another method for RDP System to tell the merchant’s system about the payment or transaction result. Using the ‘transaction_id’ our Merchant can query the result of a payment requested. If the Merchant account is configured to be enforcing unique order-id then they can use the order-id to query the result. (Configuration is by requesting during the setup process / by contacting our support at support@reddotpayment.com)

Query Result - Service End Points

The URL service end points for the query redirection result are as follow:

• Test (Sandbox) Environment
  This environment is used by merchants to do their integration or testings.
  https://secure-dev.reddotpayment.com/service/Merchant_processor/query_redirection
• Production (Live) Environment
  This is where merchant should point their production application in order to make or send tokenization process.
  https://secure.reddotpayment.com/service/Merchant_processor/query_redirection

Query Result - Process Flow

Parameter ‘transaction_id‘ is to be used as a main component to send a query for more detailed payment information. This section explains about the steps of procedure that a merchant’s system should do in order to poll for the payment or transaction result.

The following is the step by step procedure:

1. Merchant shall use the transaction_id returned in response (especially when it is a pending transaction)
   Note : If the Merchant account is configured to be enforcing unique order-id then they can use the order-id to query the result. (Configuration is by requesting during the setup process / by contacting our support at support@reddotpayment.com)
2. Merchant system packs the needed parameters to query the complete transaction details. It just needs another component which is mid, the merchant ID given by RDP to Merchant when we are setting up their account.

   $rp = array( 
      'request_mid' => '1000089029', 
      'transaction_id' => $transaction_id 
   );

3. Merchant system shall sign the request using the Generic Signature algorithm (see Generic Signature section, especially for the sign_generic() function definition)

   $secret_key =
   "D716A4188569B68AB1B6DFAC178E570114CDF0EA3A1CC0E31486C3E41241BC6A76424E8C37AB26F096FC85EF9886C8CB634187F4FDDFF645FB099F1FF54C6B8C";
   $rp['signature'] = sign_generic($secret_key, $rp);
   
   function sign_generic($secret_key, $params)
   {
       // a copy-passing, so it's not altering the original $params
       unset($params['signature']); 
    
       $data_to_sign = "";
       recursive_generic_array_sign($params, $data_to_sign);
    
       $data_to_sign .= $secret_key;
   
       return hash('sha512', $data_to_sign);
    }
   
   function recursive_generic_array_sign(&$params, &$data_to_sign)
   {
       // sort the parameters based on its key
       ksort($params);
   
       // Traverse through each component
       // And generate the concatenated string to sign
       foreach ($params as $v) {
          if (is_array($v)) {
             // in case of array traverse inside
             // and build further the string to sign
             recursive_sign_payment_response($v, $data_to_sign);
          }
          else {
             // Not an array means this is a key=>value map,
             // Concatenate the value to data to sign
             $data_to_sign .= $v;
          }
       }
   }

4. Encode the request parameters into JSON format

   $json_rp = json_encode($rp);

5. Post the request to Query-Redirection Service End Point (see previous section for URL, choose between development/live server). This is a direct server-to-server communication between RDP and Merchant System through HTTP protocol.

   // target RDP development server
   $url = https://secure-dev.reddotpayment.com/service/Merchant_processor/query_redirection;
   $curl = curl_init($url);
    
   curl_setopt_array($curl, array(
       CURLOPT_RETURNTRANSFER => 1,
       CURLOPT_FOLLOWLOCATION => true,
       CURLOPT_POST => 1, // using POST method
       CURLOPT_SSL_VERIFYPEER => false,
       CURLOPT_SSL_VERIFYHOST => false,
   
       // JSON Request Parameters is put in the BODY of request
       CURLOPT_POSTFIELDS => $json_rp,
       CURLOPT_HTTPHEADER => array('Content-Type: application/json')
    ));
   
   //This is the JSON response containing transaction information //
   $json_response = curl_exec($curl);
   $curl_errno = curl_errno($curl);
   $curl_err = curl_error($curl);
   curl_close($curl);

6. Decode the JSON response into your workable Object type.

   $response_array = json_decode($json_response, true);

7. When the query is a success (response_code field of the response has the value of 0 – zero) authenticate the signature of the response to make sure that it really is from RDP (Red Dot Payment).

   // (See Generic Signature section,
   // Especially for the sign_generic() function definition)
   if ( isset($resp_array['signature']) ) {
      $secret_key = "D716A4188569B68AB1B6DFAC178E570114CDF0EA3A1CC0E31486C3E41241BC6A76424E8C37AB26F096FC85EF9886C8CB634187F4FDDFF645FB099F1FF54C6B8C";
      $calculated_signature = sign_generic($secret_key, $resp_array);
      if ($calculated_signature != $resp_array['signature']) {
         throw new Exception('signature wrong! invalid response!');
      }
   
      echo "signature is fine, continue processing the request";
   }
   else {
      // zero response_code means a successful transaction, and definitely has signature
      if ($resp_array['response_code'] == 0) 
         throw new Exception('signature not found! invalid response!');
   
      // error / reject transactions might not have any signature in it
      echo "signature not found! Must be an error/invalid request";
   }

8. Now merchant can be sure to safely store the complete payment result details.
9. When the query is a pending, then merchant is advised to poll for another query, where the recommendation for the interval is dependent on which Wallet channel does the merchant is using, e.g. DBS PayLah! recommends 30s intervals.

Query Result Request Parameters

Example of query request for redirection result in JSON format:

{"request_mid":"1000089029","transaction_id":"TST102_17532783321610430349","signature":"6b8c652f4da86955b6d65487ca63232d49acd1ffd7a4adc36c356286aee89182421c814bb3ebc083e0d70772dcd9080a771349c10eef09f5265ea45f13a1ab9a"}

Query Result Response Parameter

Example of query request for redirection result in JSON format:

{"mid":"1000089029","transaction_id":"pruefer_9is_9901523031657784985","order_id":"pruefer_9is","acquirer_transaction_id":"311815","request_amount":"0.01","request_ccy":"SGD","authorized_amount":"0.01","authorized_ccy":"SGD","acquirer_authorized_amount":"0.01","acquirer_authorized_ccy":"SGD","response_code":"0","response_msg":"successful","acquirer_response_code":"0","acquirer_response_msg":"APPROVED OR COMPLETED","acquirer_authorization_code":"657300","created_timestamp":"2017-05-05 09:49:24","acquirer_created_timestamp":"2017-05-05 09:49:15","first_6":"411111","last_4":"1111","request_timestamp":"2017-05-05 09:49:08","request_mid":"1000089029","transaction_type":"S","payment_mode":"1","signature":"cf966933ef6b23ab45b95e9a0d8d4d51bd024f9ed3aaa0b0ff66132e317f8b0fa077dcd5b50dd2dcc6808d8b00b90b4cc53a9cfa04278118f8a848f86782eb2a"}