RDP Redirect API

First Phase – Constructing Payment URL

First Phase Description

The first phase request is meant to request RDP (Red Dot Payment) payment gateway in order to construct a payment URL for merchant’s customer. This is a server-to-server communication. Communication is using HTTP protocol POST request and in the message format of JSON. In the production (live) server everything is communicated under SSL Secured Channel.

First Phase Service End Points

The URL service end points for the redirect payment API are as follow:

 

First Phase Request Parameters

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

The merchant ID given by RDP when setting up an account.

api_mode Mandatory VARCHAR(20)

The mode which defines that we are requesting a Redirect Hosted API service
Possible values:

  • redirection_hosted for HOP mode.
  • redirection_sop for SOP mode.
payment_type Mandatory VARCHAR(1)

Defining the function to be served.
Possible values :

  • S : Sale Transaction
  • A : (Pre) Authorisation
  • I : Installment

Note:

  • ‘(Pre) Authorisation’ and ‘Installment’ payment type might only applicable for credit card payment, and might also depend on the capabilities of the bank and/or acquirer.
  • For any digital wallet payment service such as AliPay, DBS PayLah!, WeChat, etc; merchants should use sale payment type (payment_type = ‘S’).
  • If necessary, please contact RDP for further query or information on this parameter.
order_id Mandatory VARCHAR(20)

Merchant defined order ID for the transaction. Used for identifying the transaction request. Recommended to have a unique value.
Merchant could request an enforcement of unique order ID (‘order_id’) to RDP (where repeated ‘order_id’ will be rejected.)

Note:

  • By default RDP system will allow a non-unique order ID.
  • For ‘Alipay’ and ‘UnionPay’ payment mode, since they have the limitation on transaction ID length, the ‘enforce unique order id’ parameter setup in merchant profile should be enabled.
ccy Mandatory In 3 digits ISO-4217 Alphabetical Currency Code format.

Example: SGD, IDR, USD

amount Mandatory NUMERIC

The format of the amount field should follow:

  • Maximum of 10 digits in front of the decimal separator sign.
  • Maximum of 2 digits behind the decimal separator sign.
  • For those currencies with 0 decimal place or exponent, such as IDR (Indonesian Rupiah), it should be sent without decimal separator sign and those digits behind it.

 

Example:

  • 1200.07
  • 1200 (for IDR, etc)
payment_channel Optional VARCHAR(1)

The payment channel that used for the transaction. Used to identify which payment channel being used; and it will be useful when merchant have multiple payment channel.
Please refer to Appendix A (Payment Channel List).

Note:
By default RDP turn-off this feature.

multiple_method_page Optional INT(1)

1 : Use multiple mode page, where cardholder can choose the payment-page
0 : Directly request to acquiring partner page for those acquirer which host the payment-page (Example: eNETS, UPOP – Union Pay Online Payment).
By default it has the value of 1, which means using the multiple mode page for cardholder to see the payment-summary and choose their payment method (if Merchant use multiple payment method with RDP Gateway)

back_url Conditional URL

Merchant’s site URL where customer is to be redirected when they chose to press “back” button on RDP’s payment page.
This field is conditional, depends on the API mode (api_mode):

  • Mandatory for HOP mode.
  • Optional for SOP mode.
redirect_url Mandatory URL

Merchant’s site URL where RDP is going to redirect Customer once a final result has been received from bank / acquirer

notify_url Mandatory URL

Merchant’s site URL where a notification will be received once a final result of the payment transaction is acquired.

signature Mandatory VARCHAR(128)

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

payer_id Conditional VARCHAR(100)

Merchant’s customer or payer unique ID for tokenization transaction process, that can be defined by merchant (through ‘token_mod’ and ‘token_mod_id’ parameters below) or can be coming from the response message of RDP payment API or tokenization API.
Note:

  • This parameter is only applicable for merchant with ‘tokenization’ feature is turned ON.
  • Merchant must send this parameter, if they are intending to do payment transaction through tokenization.
  • Please also see or refer to the ‘token_mod’ and ‘token_mod_id’ parameters below.
  • This parameter value should be correctly tied to the valid and correct merchant ID (MID) and payment mode.
payer_email Conditional VARCHAR(45)

This field is conditional. Use this field to inform the email of customer. Quite useful for reviewing transactions in our InstanpanelTM Backend, or to contribute in transaction identification for Fraud Detection System (FDS).

merchant_reference Optional VARCHAR(100)

Any kind of extra information for merchant to relate with this transaction.
Example: Booking No for Hotels.

locale Optional VARCHAR(2)

The language setting. At this moment we only support five languages. We are looking forward to support more languages.
Possible values:

  • en : English
  • id : Bahasa
  • es: Español (Spanish)
  • fr: Français (French)
  • de: Deutsch (Germany)
bill_to_forename Conditional STRING(60)

It is mandatory when the acquirer chosen is CyberSource, where other than that this, it is optional; it is useful for Fraud Detection System (FDS).
This is the forename to whom the transaction is billed.

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 surname to whom the transaction is being billed.

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 city where the transaction is being billed.

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 first line of street address where the transaction is being billed.

bill_to_address_line2 Optional STRING(60)

The second line of street address where the transaction is being billed.

bill_to_address_country Conditional STRING(2)
Two-character of Country Code in ISO 3166-2

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 country where the transaction is being billed.
Example:
US (for USA / United States)

bill_to_address_state Conditional STRING(2)
Two-character of State and Province Code in ISO 3166-2

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 State/Province where the transaction is being billed (US and Canada only).
Example:
AL (for Alabama state in USA)

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 Postal Code where the transaction is being billed.

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 cardholder phone whose the transaction is being billed.

ship_to_forename Optional STRING(60)

This field is optional, it is useful for Fraud Detection System (FDS).
This is the forename to whom the item sold is being shipped.

ship_to_surname Optional STRING(60)

This field is optional, it is useful for Fraud Detection System (FDS).
This is the surname to whom the item sold is being shipped.

ship_to_address_city Optional STRING(50)

This field is optional, it is useful for Fraud Detection System (FDS).
This is the address city to where the item sold is being shipped.

ship_to_address_line1 Optional STRING(60)

This field is optional, where it is useful for Fraud Detection System (FDS).
This is the first line of street address to where the item sold is being shipped.

ship_to_address_line2 Optional STRING(60)

This field is optional, it is useful for Fraud Detection System (FDS).
This is the second line of street address to where the item sold is being shipped.

ship_to_address_country Optional STRING(2)
Two-character of Country Code in ISO 3166-2

This field is optional, it is useful for Fraud Detection System (FDS).
This is the country to where the item sold is being shipped.
Example:
US (for USA / United States)

ship_to_address_state Optional STRING(2)
Two-character of State and Province Code in ISO 3166-2

This field is optional, it is useful for Fraud Detection System (FDS).
This is the state to where the item sold is being shipped. (US and Canada only).
Example:
AL (for Alabama state in USA)

ship_to_address_postal_code Optional STRING(10)

This field is optional, it is useful for Fraud Detection System (FDS).
This is the postal code to where the item sold is being shipped.

ship_to_phone Optional STRING(15)

This field is optional, it is useful for Fraud Detection System (FDS).
This is the phone number to whom the item sold is being shipped.

installment_tenor_month Conditional NUMERIC

It is mandatory when the payment type is ‘I’ (Installment).
This field indicates the tenure of the installment payment.

store_code Conditional String(45)

The merchant’s defined store code or outlet ID. Used to identify which store or outlet is doing transaction; and it will be useful when merchant have multiple store or outlet.

Note:
By default RDP turn-off this feature.

card_no Conditional [for SOP] VARCHAR(19)

Card number to be passed through to the bank or acquirer. Mandatory for our SOP (Silent Order Page) feature (This feature are available only for certain service, please contact us for further query on this feature).

exp_date Conditional [for SOP] NUMERIC

Expiry date (in MMYYYY format) to be passed through to the bank or acquirer.
Mandatory for SOP (Silent Order) feature.

cvv2 Conditional [for SOP] NUMERIC

CVV2 to be passed through to the bank or acquirer. Mandatory for SOP (Silent Order Page) feature.

payer_name Conditional [for SOP] VARCHAR(45)

The name of cardholder

bin_filter_code Conditional VARCHAR(50)

The unique code for IIN / BIN filter feature on specific MID group. If this feature is turned ON for the merchant:

  • If the ‘bin_filter_code’ from merchant is valid and matched with the code in RDP system, RDP payment gateway will act according to the setup, which by default it will go through; else will be rejected.
  • If the ‘bin_filter_code’ from merchant is invalid or does not match with any codes, RDP payment gateway will reject the transaction.
  • If merchant never send this parameter, RDP payment gateway will consider as allowing all kind of cards to proceed with payment process (treated as normal payment transaction).

While if this feature is OFF, the payment gateway will not do any checking of IIN / BIN for incoming transaction from merchant.
Note:
By default RDP will turn off this feature.

token_mod Conditional VARCHAR(1)

This parameter is only applicable for merchant with ‘tokenization’ feature is turned ON.
Possible values are:

  • 0 : Disabled
  • 1 : Enabled

If the value = 1 (Enabled), after a successful transaction, RDP will return ‘payer_id’ parameter inside the response message (redirection query and push notification).

token_mod_id Optional VARCHAR(100)

Merchant might need to send this parameter if ‘token_mod’ = 1.
Note:
Similarly, this parameter is only applicable for merchant with ‘tokenization’ feature is turned ON.
For successful transaction, the value of this ‘token_mod_id’ parameter will be put inside the ‘payer_id’ parameter under the response message.
In the case where the ‘token_mod’ is 1, but there is no value under this parameter, RDP payment gateway will generate a random value for ‘payer_id’ in the response parameter.

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 D’ section for further info about ‘uatp’ parameter in request message.

merchant_data1 Conditional VARCHAR(32)

It is a mandatory parameter for the payment transaction through China PNR. It has these possible values:

  • Customer ID
    For China PNR “QuickPay” mode via RDP Redirect Payment API HOP mode. The maximum length for customer ID is 32 characters.
  • Bank code
    For China PNR “Direct method” mode via RDP Redirect Payment API SOP mode. This is the 3 character of bank code (case insensitive). For complete list of bank code, please refer to China PNR website.
    Example: CMB
merchant_private_data Conditional TEXT

It is a mandatory parameter for the payment transaction through China PNR for “Direct method” mode; and it should contain a national ID data in JSON format.
Example:
{“national_id”:”312345678912345678″}

First Phase Request JSON formatted example:

{
 "redirect_url":"http:\/\/localhost\/rdp\/service\/test-suite\/T_redirection_hosted_single\/redirect_url",
 "notify_url":"http:\/\/localhost\/rdp\/notif_server\/payment_api\/notif-url.php",
 "back_url":"http:\/\/localhost\/rdp\/service\/test-suite\/T_redirection_hosted_single\/back_url",
 "mid":"1000089029",
 "order_id":"TST102",
 "amount":"0.01",
 "ccy":"SGD",
 "api_mode":"redirection_hosted",
 "payment_type":"S",
 "merchant_reference":"the things to reference",
 "signature":"325cda0dc4a0dfa523afc542c245ae008ca73910779e670f96b3ed4bd241b966e752036afd1920ae9690ca475b82eda302a3b0a7ad9157a4d4cdb0cc38b36e52"
}

First Phase Response Parameters

Field Name Status Value Type Description
mid Conditional (Non Error) VARCHAR(20)

The merchant id given by RDP when setting up an account.

signature Conditional VARCHAR(128)

A SHA-512 signature to proof that the message is coming from the valid party.
For signature generation and validation, please refer to chapter 4. Please also see the note in chapter 4.3.

expired_timestamp Conditional (Success only) INT.
The unix timestamp

Indicates the time when the payment-page session is detroyed.
Example: 1454467459

created_timestamp Conditional (Success only) INT.
The unix timestamp

Indicates the time when the payment page is created.
Example: 1454467459

order_id Conditional (Success) VARCHAR(20)

Echo back the order-id sent in the request.

transaction_id Conditional (Success) VARCHAR(32)

The unique transaction-id generated by RDP.

payment_url Conditional (Success only) VARCHAR (URL)

The payment page URL where merchant’s system need to redirect to.

response_msg Conditional TEXT

A description on the response_code field.

response_code Mandatory VARCHAR(10)

Code that indicates the status of a payment.
Possible values:

  • 0: success
  • others : failed
response_status Conditional (Error only) TEXT

Indicates an error status based on the ‘response_code’ parameter and it is only applicable for error condition.

First phase response JSON formatted example:

For successful transaction:

{  
 "created_timestamp":1454382081,
 "expired_timestamp":1454468481,
 "mid":"1000089029",
 "order_id":"TST102",
 "transaction_id":"TST102_59772881953567319",
 "payment_url":"http:\/\/test.reddotpayment.com\/service\/secure-payment\/--REDSHOP--\/2608ed4b6363e80104effca44d2b1c4170f06d570fe78430ba0f7dd7016ea975710d78fd9f41dc3561ada259d8f95112f30d81ae1f5e9a0277cb64f9f449b427",
 "response_code":0,
 "signature":"58060d69ac7c7f60b8dc6a3ddd2485d9d0f744a8c604c347f50a06025d076ce367be5140690b095e17fa293b973a37ad073ab6c36ebe4d31eaae679a2de60bcc"
}

For failed or error transaction:

{  
   "response_status":"error",
   "response_code":"-1901",
   "response_msg":"redirect_url could not be found"
}

First Phase Response Handling Example

Below are the procedures for first phase response parameters handling:

  1. When the ‘response_code’ parameter indicates a successful payment (response_code is ‘0’), merchants should check the transaction signature (‘signature’ parameter) by using generic signature algorithm (please refer to chapter 4.2 about ‘Generic Section’).
    {  
     "created_timestamp":1454382081,
     "expired_timestamp":1454468481,
     "mid":"1000089029",
     "order_id":"TST102",
     "transaction_id":"TST102_59772881953567319",
     "payment_url":"http:\/\/test.reddotpayment.com\/service\/secure-payment\/--REDSHOP--\/2608ed4b6363e80104effca44d2b1c4170f06d570fe78430ba0f7dd7016ea975710d78fd9f41dc3561ada259d8f95112f30d81ae1f5e9a0277cb64f9f449b427",
     "response_code":0,
     "signature":"58060d69ac7c7f60b8dc6a3ddd2485d9d0f744a8c604c347f50a06025d076ce367be5140690b095e17fa293b973a37ad073ab6c36ebe4d31eaae679a2de60bcc"
    }
  2. After validating the transaction signature, merchants should get the payment URL parameter and redirect customers to that particular URL.
    Below is the sample code for first phase response parameter handling in PHP programming language.

    <?php
    function response_handling($mid, $secret_key, $json_response)
    {
        $array_response = json_decode($json_response,true);
        if ($array_response['response_code'] == 0)
        {
    	// Successfull transaction //
    
    	// Calculate signature using sign generic function //
    	$calculated_signature = sign_generic($secret_key,
                                  $array_response);
    
    	// Validate the received transaction signature //
    	if ($calculated_signature == $array_response['signature'])
    	{
    	    if (!empty($array_response['payment_url']))
    	    {
    		// Redirect customers to payment page //
    		header ('Location: ' . $array_response['payment_url']);
    		exit;
    	    }
    	    else
    	    {
    		// Empty payment URL in succesful txn (should not happen) //
    		throw new Exception('Invalid response, no payment_url');
    	    }
    	}
    	else
    	{
    	    // Invalid signature, the response might not come from RDP //
    	    throw new Exception('Invalid signature!');
    	}
        }
        else
        {
    	throw new Exception('Invalid request : '.
    				 $array_reponse['response_msg']);
        }
    };
    
    ?>