RDP Redirect API

Redirection Result

Redirection Description

This is another method for RDP System to tell the merchant’s system about the payment or transaction result. Redirection method will bring the payment process to merchant’s system or web page or website where at the same time it will also pass the ‘transaction_id‘ field to the merchant system.

RDP will redirect the customer or cardholder toward to the merchant’s URL that’s sent in the request as ‘redirect_url‘ parameter. The fact that we are bringing the customer or cardholder back to the merchant site is the reason why it has this name.

Later on, by using the ‘transaction_id‘ inside the GET parameters of the redirection, merchant system can use it to further request a query to retrieve a more complete explanation about the transaction status itself. This is done through query-redirection-result.

Redirection Result - Service End Points

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

 

Redirection Result - Process Flow

The redirection initiated by RDP (Red Dot Payment) system give Merchant’s system transaction_id which is to be used as a main component to send a query for a more detailed payment information. This section explains about the steps of procedure that a Merchant’s system has to do when RDP’s system redirect the Card Holder back to Merchant’s redirect_url (sent in the First Phase step section.)

The following is the step by step procedure:

  1. RDP’s redirect Card Holder to the Merchant’s redirect_url (sent with the First Phase Request see previous section) and attaches transaction_id at the GET parameters of the request.
    Example:
    Given the First Phase request has redirect_url :
    http://merchant.com/redirect_url
    The URL where cardholder will see is:
    http://merchant.com/redirect_url?transaction_id=1234567891
  2. Merchant shall retrieve the transaction_id from GET parameters.
    if ( isset($_GET['transaction_id']) ) {
        $transaction_id = $_GET['transaction_id'];
    } else {
        // it's not from RDP system
    }
  3. 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
    );
  4. 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);
  5. Encode the request parameters into JSON format
    $json_rp = json_encode($rp);
  6. 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);
  7. Decode the JSON response into your workable Object type.
    $response_array = json_decode($json_response, true);
  8. 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";
    }
  9. Now Merchant can be sure to safely store the complete payment result details.

Redirection Result - Query 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.

signature Mandatory VARCHAR(128)

A SHA-512 signature to proof that the message is coming from the valid party or merchant. For signature generation and validation, please refer to chapter 4.

Example of query request for redirection result in JSON format:

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

Redirection Result - Query 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
  • others : request-error
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 SHA-512 response’s signature. For signature generation and validation, please refer to chapter 4. Please also see the note in chapter 4.3.

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 B (Payment Mode List).

payer_id Conditional VARCHAR(100)

RDP payment gateway will return this field, with these following conditions:

    • Tokenization feature is turned on for the merchant.
    • Merchant send ‘token_mod’ parameter with value equal to 1 (enabled) in first phase request message.
    • The value will be similar to the value of ‘token_mod_id’ in first phase request parameter, if merchant previously sent a value under this parameter; else it will be a random generated value.
    • Successful transaction.

Note:
Please takes note that for merchant with multiple payment modes (multiple payment tabs inside the payment page), the returned ‘payer_id’ parameter value is tied to ‘mid’ parameter value, and it is not tied to the ‘request_mid’ parameter value).

payer_name Optional [Acquirer Dependent] VARCHAR(45)

The name of cardholder.

acquirer_mpi_eci Conditional [Acquirer Dependent] NUMERIC

The ECI (Electronic Commerce Indicator) value that’s returned by acquirer’s MPI and the existence of this field is subjected to the acquirer being chosen by merchant.
Please refer to ‘Appendix H‘ for possible ECI values.

uatp Conditional TEXT

This parameter is used for ‘Universal Air Travel Plan (UATP)’ 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 E‘ section for further info about ‘uatp’ parameter in response message.

merchant_data1 Conditional [Acquirer Dependent and No-Error] VARCHAR(32)

An echo message based on the same parameter name that’s sent in the request message; and will be only applicable for the payment transaction through China PNR.

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