RDP Direct API

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:

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

Field Name Status Value Type Description
request_mid Mandatory VARCHAR(20)

The merchant ID given by RDP when setting up an account; which is used to request payment (in case the merchant has multiple MIDs with RDP, the payment itself might be handled by different mid, according to the chosen payment mode by cardholder).

transaction_id Mandatory VARCHAR(32)

The transaction ID attached by RDP system in the redirect_url GET parameter, or for Direct API the one returned in response.

If the merchant is configured for enforce unique order id then it is the same with the request’s order-id.

signature Mandatory VARCHAR(128)

A SHA-512 signature to proof that this request is coming from the merchant.

Example of query request for redirection result in JSON format:

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

Query Result Response Parameter

Field Name Status Value Type Description
response_code Mandatory VARCHAR(10)

Flag which defines whether the transaction is accepted, or has an error in request, or rejected by Acquirer (e.g. Bank). Possible values:

  • 0 : success – accepted transaction
  • -1 : bank / acquirer rejection
  • -01 : pending
  • others : request-error

Please refer to ‘Appendix B‘ for complete list of response code.

response_msg Mandatory TEXT

Description of the response-code.

mid Conditional [No-Error] VARCHAR(20)

The merchant id generated by RDP for merchant, which is used to handle the transaction (can be different from mid used for requesting payment, especially when Merchant has multiple payment-mode with RDP gateway).

request_mid Conditional [No-Error] VARCHAR(20)

The merchant id generated by RDP for merchant, which is used when requesting the payment.

order_id Conditional [No-Error] VARCHAR(20)

An echo back to Merchant’s order-id for the transaction as the identifier of the transaction.

transaction_id Conditional [No-Error] VARCHAR(32)

The RDP generated unique transaction-id, which is used heavily for identifying the resulted transaction in RDP system.

request_amount Conditional [No-Error] NUMERIC

Echo back the amount as is sent in the request.

request_ccy Conditional [No-Error] In 3 digits ISO-4217 Alphabetical Currency Code format.

Echo back the currency requested.
Example: SGD, IDR, USD

request_timestamp Conditional [No-Error] YYYY-MM-DD hh:mm:ss

The date-time when the request is received or created. In a 24 hour format. Time zone is using (UTC+08:00) Kuala Lumpur, Singapore.
Example: 2015-11-14 12:33:27

authorized_amount Conditional [No-Error] Numeric

Amount after applying all of others RDP features.
Example: InstanPromo, Currency-Converter, etc.

authorized_ccy Conditional [No-Error] In 3 digits ISO-4217 Alphabetical

The final currency that is going to be communicated to Bank/Acquirer.
Example: due to Currency-Converter features.

transaction_type Conditional [No-Error] S, A

S : Sale transaction
A : Authorization transaction

created_timestamp Conditional [No-Error] YYYY-MM-DD hh:mm:ii

The datetime when the response is created. In a 24 hour format. Timezone is using (UTC+08:00) Kuala Lumpur, Singapore.
Example: 2015-11-14 12:33:27

acquirer_response_code Conditional [No-Error] TEXT

Response code from acquirer. Format is specific to each Acquirer

acquirer_response_msg Conditional [No-Error] TEXT

Description of the response code.

signature Conditional VARCHAR(128)

The response signature. For signature generation, validation and note please refer to sub chapter 4.3.2 (Transaction Response Signature).

acquirer_authorized_amount Conditional [on success only] Numeric

The amount authorized by acquirer
Example: can be different if Acquirer provides DCC feature.

acquirer_authorized_ccy Conditional [on success only] In 3 digits ISO-4217 Alphabetical Currency Code format.

The currency authorized by Acquirer.
Example: can be different if Acquirer provides DCC feature.

merchant_reference Conditional [no-error] VARCHAR(100)

The echo back of merchant_reference in the request.

acquirer_created_timestamp Optional [Acquirer Dependent] YYYY-MM-DD hh:mm:ii

The date-time when the response is created. In a 24 hour format. Timezone vary depends on Acquirer.
Example: 2015-11-14 12:33:27

acquirer_transaction_id Optional [Acquirer Dependent] TEXT

Transaction ID generated by Acquirer. Existence depends on availability of the fields from acquirer

acquirer_authorization_code Conditional [Acquirer Dependent] VARCHAR

Authorization code from the Bank. Only when it is available from the Bank response.

first_6 Optional [Acquirer Dependent] VARCHAR(6)

The first 6 digits of card_no

last_4 Optional [Acquirer Dependent] VARCHAR(4)

The last 4 digits of card_no

exp_date Optional [Acquirer Dependent] VARCHAR(6)

The expiry date of the card used for transaction.

payment_mode Conditional [no-error] NUMERIC

The payment mode or card type that customer used for the transaction. Please refer to Appendix C (Payment Mode List).

payer_id Conditional VARCHAR(100)

Merchant defined payer ID or customer ID. Used to identify a unique merchant’s customer.

payer_name Optional [Acquirer Dependent] VARCHAR(45)

The name of cardholder.

fds Conditional TEXT

This parameter is used for ‘Fraud Detection System (FDS)’ feature and will be only available for those merchants where this feature is enabled for them. The data is in JSON formatted text. Please refer to ‘Appendix D’ section for further info about ‘fds’ parameter in query response message.

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"}