RDP Hosted and Direct Tokenization API

Direct Tokenization API (DITAPI)

Service End Points

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

Request Parameters

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

The merchant ID given by RDP when setting up an account.
order_id Mandatory VARCHAR(16)

Merchant defined order-id for the transaction. Used for identifying the transaction request. Suggested to be of unique values. Merchant can request enforcement of unique order_id from RDP (where repeated order_id is to be rejected.)

Note:
By default RDP allowed non-unique order-id
api_mode Mandatory VARCHAR(20)

The mode or function that merchant is requesting for this API. For direct tokenization API, the value must be: ‘direct_token_api ‘.
transaction_type Mandatory STRING(1)

The type of tokenization process. Possible values:

  • C : Create
  • M : Modify
  • R : Remove

Note:
Token creation and modification (Type ‘C’ & ‘M’) are working for both API modes (direct & hosted). While token removal or deletion (Type ‘R’) must use direct mode.
type Conditional STRING(1)

The type of tokenization process. Possible values:

  • C :Create
  • M : Modify
  • R : Remove

Note:

  • This parameter is deprecated; instead of using this parameter, please use the ‘transaction_type’ parameter.
  • Token creation and modification (Type ‘C’ & ‘M’) are working for both API modes (direct & hosted). While token removal or deletion (Type ‘R’) must use direct mode.
payer_id Conditional VARCHAR(100)

Merchant defined payer ID or customer ID. Used to identify a unique merchant’s customer. This field is mandatory for token modification and removal (Type ‘M’ & ‘R’).
payer_name Conditional VARCHAR(45)

The name of cardholder.
This field is mandatory for token creation and modification (transaction type ‘C’ & ‘M’).
payer_email Mandatory STRING(60)

The email of customer or cardholder.
ccy Optional In 3 digits ISO-4217 Alphabetical Currency Code format.

Example: SGD, IDR, USD
card_no Conditional [card-mode] VARCHAR(19)

Card number to be passed through to the bank or acquirer.
Mandatory for token creation and modification.
exp_date Conditional [card-mode] NUMERIC

Expiry date (in MMYYYY format) to be passed through to the bank. Mandatory for token creation and modification.
cvv2 Conditional [card-mode] NUMERIC

CVV2 to be passed through to the bank. Optional for token creation and modification.
signature Mandatory VARCHAR(128)

A SHA-512 signature to proof that this request is coming from the merchant.
merchant_reference Optional VARCHAR(100)

Any kind of extra information for merchant to relate with this process.
Example: Booking number.
bill_to_forename Conditional STRING(60)

It is Mandatory when the acquirer chosen is Cybersource, other than that this field is optional, it is useful for Fraud Detection System (FDS).
This is the customer’s forename.
bill_to_surname Conditional STRING(60)

It is Mandatory when the acquirer chosen is Cybersource, other than that this field is optional, it is useful for Fraud Detection System (FDS).
This is the customer’s surname.
bill_to_address_city Conditional STRING(50)

It is Mandatory when the acquirer chosen is Cybersource, other than that this field is optional, it is useful for Fraud Detection System (FDS).
This is the customer’s city address.
bill_to_address_line1 Conditional STRING(60)

It is Mandatory when the acquirer chosen is Cybersource, other than that this field is optional, it is useful for Fraud Detection System (FDS).
This is the customer’s first line of street address.
bill_to_address_line2 Optional STRING(60)

This is the customer’s second line of street address.
bill_to_address_country Conditional STRING(2)
Two-character ISO Country Code

It is Mandatory when the acquirer chosen is Cybersource, other than that this field is optional, it is useful for Fraud Detection System (FDS).
This is the customer’s country.
bill_to_address_state Conditional STRING(2)
Two-character ISO State and Province Code

It is Mandatory when the acquirer chosen is Cybersource and the bill_to_address_country is USA or Canada, other than that this field is optional, it is useful for Fraud Detection System (FDS).
This is the customer’s State / Province (US and Canada only).
bill_to_address_postal_code Conditional STRING(10)

It is Mandatory when the acquirer chosen is Cybersource, other than that this field is optional, it is useful for Fraud Detection System (FDS).
This is the customer’s Postal code.
bill_to_phone Conditional STRING(15)

It is Mandatory when the acquirer chosen is Cybersource, other than that this field is optional, it is useful for Fraud Detection System (FDS).
This is the customer’s phone.
wallet_id Conditional [wallet-mode] STRING(100)

The wallet significant ID to be used for payment.
For DBS PayLah!, it is the customer’s mobile number.

Response Parameters

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(6)

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.

Code Samples

Below are those code samples in PHP language for token creation, modification and removal (deletion) in direct tokenization API.

Code Samples for Token Creation

function generate_signature($secret_key, $params) {
    unset($params['signature']);
    ksort($params);
    $data_to_sign = "";
    foreach ($params as $v) {
       $data_to_sign .= $v;
    } 
    $data_to_sign .= $secret_key;
    return hash('sha512', $data_to_sign);
}
function post($json_request,$url) {
    $curl = curl_init($url); 

    curl_setopt_array($curl, array(
        CURLOPT_RETURNTRANSFER => 1,
        CURLOPT_FOLLOWLOCATION => true,
        CURLOPT_POST => 1,
        CURLOPT_SSL_VERIFYPEER => false,
        CURLOPT_SSL_VERIFYHOST => false,
        CURLOPT_POSTFIELDS => $json_request,
        CURLOPT_HTTPHEADER => array('Content-Type: application/json')
        ));

    $response = curl_exec($curl);
    $curl_errno = curl_errno($curl);
    $curl_err = curl_error($curl);
    curl_close($curl);
    return $response;
}

$dtoken_parameter = array(
    'mid' => "1234567890",
    'order_id' => "ORD123",
    'api_mode' => "direct_token_api",
    'transaction_type' => "C", //Possible values: C(Create); R(Remove); M(Modify)
    'payer_email' => "abc@abc.com",
    'payer_name' => "Payer name",
    'card_no' => '4111111111111111',
    'exp_date' => '082019',
    'cvv2' => '123'
);

// Test Server //
$auth_url = "https://secure-dev.reddotpayment.com/service/token-api";
// Live Server //
//$auth_url = "https://secure.reddotpayment.com/service/token-api";

$secret_key = "RedDot";
$dtoken_parameter['signature'] = generate_signature($secret_key,$dtoken_parameter);
$json_request = json_encode($dtoken_parameter);
$response = post($json_request,$auth_url);
$response_array = json_decode($response, true);
echo "<pre>";
print_r($response_array);
exit;

Code Samples for Token Modification

function generate_signature($secret_key, $params) {
     unset($params['signature']);
     ksort($params); 
     $data_to_sign = ""; 
     foreach ($params as $v) {
         $data_to_sign .= $v;
     }
     $data_to_sign .= $secret_key;
     return hash('sha512', $data_to_sign);
}

function post($json_request,$url) {
   $curl = curl_init($url);
   curl_setopt_array($curl, array(
   CURLOPT_RETURNTRANSFER => 1,
   CURLOPT_FOLLOWLOCATION => true,
   CURLOPT_POST => 1,
   CURLOPT_SSL_VERIFYPEER => false,
   CURLOPT_SSL_VERIFYHOST => false,
   CURLOPT_POSTFIELDS => $json_request,
   CURLOPT_HTTPHEADER => array('Content-Type: application/json')
   ));

   $response = curl_exec($curl);
   $curl_errno = curl_errno($curl);
   $curl_err = curl_error($curl);
   curl_close($curl);
   return $response;
} 

$dtoken_parameter = array(
    'mid' => "1234567890",
    'order_id' => "ORD123",
    'api_mode' => "direct_token_api",
    'transaction_type' => "M",//Possible values: C(Create); R(Remove); M(Modify)
    'payer_email' => "abc@abc.com",
    'payer_name' => "Payer name",
    'payer_id' => "Payer001",
    'card_no' => '4111111111111111',
    'exp_date' => '082019',
    'cvv2' => '123'
); 

//Test Server //
$auth_url = "https://secure-dev.reddotpayment.com/service/token-api";

// Live Server //
//$auth_url = "https://secure.reddotpayment.com/service/token-api"; 

$secret_key = "RedDot";
$dtoken_parameter['signature'] = generate_signature($secret_key,$dtoken_parameter);
$json_request = json_encode($dtoken_parameter);
$response = post($json_request,$auth_url);
$response_array = json_decode($response, true);

echo "<pre>";
print_r($response_array);
exit;

Code Samples for Token Removal (Deletion)

function generate_signature($secret_key, $params) {
    unset($params['signature']);
    ksort($params);
    $data_to_sign = "";
    foreach ($params as $v) {
        $data_to_sign .= $v;
    }

    $data_to_sign .= $secret_key;
    return hash('sha512', $data_to_sign);
}

function post($json_request,$url) {
   $curl = curl_init($url);
   curl_setopt_array($curl, array(
       CURLOPT_RETURNTRANSFER => 1,
       CURLOPT_FOLLOWLOCATION => true,
       CURLOPT_POST => 1,
       CURLOPT_SSL_VERIFYPEER => false,
       CURLOPT_SSL_VERIFYHOST => false,
       CURLOPT_POSTFIELDS => $json_request,
       CURLOPT_HTTPHEADER => array('Content-Type: application/json')
       ));

   $response = curl_exec($curl);
   $curl_errno = curl_errno($curl);
   $curl_err = curl_error($curl);
   curl_close($curl);
   return $response;
} 

$dtoken_parameter = array(
    'mid' => "1234567890",
    'order_id' => "ORD123",
    'api_mode' => "direct_token_api",
    'transaction_type' => "R",
    'payer_email' => "abc@abc.com",
    'payer_name' => "Payer name",
    'payer_id' => "Payer001" );

// Test Server //
$auth_url = "https://secure-dev.reddotpayment.com/service/token-api";

// Live Server //
//$auth_url = "https://secure.reddotpayment.com/service/token-api";

$secret_key = "RedDot";
$dtoken_parameter['signature'] = generate_signature($secret_key,$dtoken_parameter);
$json_request = json_encode($dtoken_parameter);
$response = post($json_request,$auth_url);
$response_array = json_decode($response, true);

echo "<pre>"; 
print_r($response_array); 
exit;