RDP Hosted and Direct Tokenization API

Hosted Tokenization API – Redirection Result

Redirection Description

This is another method for RDP System to tell the merchant’s system about the tokenization 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.

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 process information. This section explains about the steps of procedure that a merchant’s system has to do when RDP’s system redirect the cardholder 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 cardholder 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.
    Sample code in PHP:

    if ( isset($_GET['transaction_id']) ) {
       $transaction_id = $_GET['transaction_id'];
    } else {
       // it's not from RDP system
    }
  3. Merchant system packs the necessary 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.
    Sample code in PHP:

    $rp = array(
       'request_mid' => '1000089029',
       'transaction_id' => $transaction_id
    );
  4. Merchant system shall sign the request using the the generic signature algorithm (see chapter 4 – ‘Signature’ section, especially for the sign_generic() function definition)
    Sample code in PHP:

    $secret_key = "D716A4188569B68AB1B6DFAC178E570114CDF0EA3A1CC0E31486C3E41241BC6A76424E8C37AB26F096FC85EF9886C8CB634187F4FDDFF645FB099F1FF54C6B8C";
    $rp['signature'] = sign_generic($secret_key, $rp);
  5. Encode the request parameters into JSON format
    Sample code in PHP:

    $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/HTTPS protocol.
    Sample code in PHP:

    // Below target is the RDP development server //
    $url = "https://secure-dev.reddotpayment.com/service/Merchant_processor/query_token_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')
    ));
    
    $json_response = curl_exec($curl); //This is the JSON response containing transaction information
    $curl_errno = curl_errno($curl);
    $curl_err = curl_error($curl);
    curl_close($curl);
  7. Decode the JSON response into your workable Object type.
    Sample code in PHP:

    $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).
    Sample code in PHP:

    if ( isset($resp_array['signature']) ) {
        $secret_key = "D716A4188569B68AB1B6DFAC178E570114CDF0EA3A1CC0E31486C3E41241BC6A76424E8C3AB26F096FC85EF9886C8CB634187F4FDDFF645FB099F1FF54C6B8C";
        $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 mid-s 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, in case of DITAPI it will be retrieved from response. (Direct Tokenization API)

In case Merchant is configured with enforce-unique-order-id then can fill this with the value of order-id sent during the request. (To configure this you can request to our support support@reddotpayment.com )

signature Mandatory VARCHAR(128)

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

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 bank or acquirer. Possible values:

  • 0 : success – accepted transaction.
  • -1 : bank / acquirer rejection.
  • -01 : Pending.
  • Others (minus) : request-error
response_msg Mandatory TEXT

Description on 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).

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.

created_timestamp Conditional [No-Error] DATE - TIME

The date-time when the response is created. In a 24 hour format. Using Kuala Lumpur,Singapore time zone (UTC+08:00).
Format: YYYY-MM-DD hh:mm:ss
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 signature to proof that the message is coming from RDP. For signature generation, validation and note please refer to chapter 4.

merchant_reference Conditional [no-error] VARCHAR(100)

The echo back of merchant_reference in the request

first_6 Conditional [Setup on MID] VARCHAR(6)

The first 6 digits of card number

last_4 Conditional [Setup on MID] VARCHAR(4)

The last 4 digits of card number

exp_date Conditional [Setup on MID] VARCHAR(6)

The expiry date of the card used for transaction

payer_id Mandatory VARCHAR(100)

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

payer_name Conditional [Setup on MID] VARCHAR(45)

The name of cardholder

payer_email Conditional [no-error & if available] STRING(60)

The email of customer or cardholder.

ccy Conditional [no-error & if available] In 3 digits ISO-4217 Alphabetical Currency Code format.

Example: SGD, IDR, USD

transaction_type Conditional [No-Error] STRING (1)

The type of tokenization process. Possible values:

  • C : Create
  • M : Modify
  • R : Remove
token_id Conditional [No-Error] NUMERIC(30)

The token ID that represent OR replace the card data.