RDP Hosted and Direct Tokenization API

Hosted Tokenization API – First Phase

First Phase Description

The first phase request is meant to request RDP (Red Dot Payment) payment gateway in order
to construct a tokenization page 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 or through a
SSL Secured Channel.

First Phase Service End Points

The URL service end points for the hosted tokenization 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.
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 hosted tokenization API, the value must be: ‘hosted_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 Optional VARCHAR(45)

The name of cardholder.
Note: Please send the full name with a space as the separator / delimiter for the first name and last name.
payer_email Optional STRING(60)

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

Example: SGD, IDR, USD
back_url Mandatory URL

Merchant’s site URL where customer is to be redirected when they chose to press “cancel” button on RDP’s tokenization page.
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 tokenization system.
notify_url Mandatory URL

Merchant’s site URL where a notification will receive once a final result of the tokenization process is done.
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(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_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.

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.
expired_timestamp Conditional: Success only INTEGER.
The UNIX timestamp

Indicates the time when the payment-page session is destroyed.
Example: 1454467459
created_timestamp Conditional: Success only INTEGER.
The UNIX timestamp

Indicates the time when the payment page is created.
Example: 1454467459
order_id Conditional: Success only VARCHAR(16)

Echo back the order-id sent in the request.
payment_url Conditional: Success only VARCHAR.
URL

The payment page URL where merchant’s system need to redirect to.
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.
response_msg Mandatory TEXT

A description on the response_code field.
response_code Mandatory VARCHAR(10)

Code that indicates the status of a payment.