RDP Direct API

Payment Process

Service End Points

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

 

Transaction Request

The transaction request from merchant system should be formatted in JSON, and send through the BODY of the HTTP Request to RDP service end-point.

Transaction Request Mode

There are three types of transaction request mode within RDP Direct API as follow:

  1. Card Mode
    This is where merchant used cardholder’s card detail such as card number (card_no), card’s expiry date (exp_date), and cardholder’s name (payer_name) as the main fields of the request.
    Required conditional fields: card_no, exp_date, payer_name
  2. Wallet Mode
    This is where merchant used Payer’s wallet details as the main fields for request. For example in DBS PayLah! It means to send the Payer’s Mobile Number.
    Required conditional field : wallet_id
  3. Tokenization Mode
    This is where merchant is using token generated from RDP payment gateway system (such as through or from ‘Connect API’ and ‘Tokenization API’) as a replacement of the cardholder’s card detail or data in previous ‘Card-Mode’ section.
    Required conditional field: token_id OR payer_id

Transaction Request Parameters

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

The merchant ID generated by RDP system for merchant.

order_id Mandatory VARCHAR(20)

Merchant’s order-id for the transaction as the identifier of the transaction. Recommended to be unique for each case of transaction. This field can be restricted to unique value on request of merchant account setup changes.

payment_type Mandatory VARCHAR(1)
Possible values : [S, A, I]
S : Sale Transaction
A : (Pre) Authorisation
I : Installment

S : sale transaction, where the amount is charged to cardholder.

A : (pre) authorization transaction, where the amount is blocked in cardholder, and can be charged afterwards through a capture transaction.

I : installment transaction.

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.
ccy Mandatory VARCHAR(3)
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)
payer_id Conditional [tokenization-mode] VARCHAR(100)

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

Note: This parameter is compulsory for tokenization mode and should be included in signature calculation.

payer_email Mandatory VARCHAR(45)

The Cardholder’s email address

api_mode Mandatory direct_n3d

Possible value: ‘direct_n3d’

signature Mandatory VARCHAR(128)

A SHA-512 of request essentials data. Please refer to the next section on transaction request signature.

card_no Conditional [card-mode] NUMERIC(19)

The cardholder’s card number. Should not be sent if transaction is using tokenization mode.

exp_date Conditional [card-mode] 6 digits In 'MMYYYY' format

Example: 122015 (for December 2015)

Should not be sent if transaction is using tokenization mode.

payer_name Conditional [card-mode] VARCHAR(45)

The cardholder’s name. Should not be sent if transaction is using tokenization mode.

cvv2 Conditional [According to merchant account setup and Acquirer] [card-mode] / [tokenization-mode] VARCHAR(4)

3 – 4 digits of security code on the back of the physical credit card.

token_id Conditional. [tokenization-mode] NUMERIC(19)

Token generated from or through RDP System. Should not be sent if using card-mode, where card_no, exp_date, and payer_name are being used for transaction.

Note: This parameter is deprecated; and instead of using this parameter, please use the ‘payer_id’ parameter.

merchant_reference Optional VARCHAR(100)

Merchant concise description on the transaction, or could be used as a multipurpose data field

client_ip_address Optional VARCHAR(100)

Merchant’s client IP address. Important for Fraud Detection System.

client_user_agent Optional VARCHAR(100)

Merchant’s client device information. Important for Fraud Detection System

tenor_month Conditional NUMERIC (INT)

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

wallet_id Conditional [wallet-mode] VARCHAR(100)

The wallet significant ID to be used for payment.

DBS PayLah! : Mobile Number

notify_url Optional URL

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

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 Optional [card-mode] VARCHAR(1)

Possible value:

  • 0 : Disabled
  • 1 : Enabled

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

token_mod_id Conditional [card-mode] VARCHAR(100)

Merchant will need to send this parameter if ‘token_mod’ = 1.

Note: For successful transaction, the value of this ‘token_mod_id’ parameter will be put inside the ‘payer_id’ parameter under the response message.

bill_to_forename Conditional STRING(60)

It is mandatory when the chosen acquirer is CyberSource, while it is optional for others. 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 chosen acquirer is CyberSource, while it is optional for others. 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 chosen acquirer is CyberSource, while it is optional for others. 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 chosen acquirer is CyberSource, while it is optional for others. 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 ISO Country Code

It is mandatory when the chosen acquirer is CyberSource, while it is optional for others. It is useful for Fraud Detection System (FDS). This is the country where the transaction is being billed.

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

It is Mandatory when the chosen acquirer is CyberSource and the bill_to_address_country is USA or Canada, while it is optional for others. It is useful for Fraud Detection System (FDS). This is the State/Province where the transaction is being billed (US and Canada only).

bill_to_address_postal_code Conditional STRING(10)

It is mandatory when the chosen acquirer is CyberSource, while it is optional for others. 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 chosen acquirer is CyberSource, while it is optional for others. It is useful for Fraud Detection System (FDS). This is the cardholder phone whose the transaction is being billed.

Transaction Request Signature

Below are those steps for creating or generating the transaction signature inside the request message:

  1. Create a base-string from the concatenation of the following fields:
    mid, order_id, payment_type, amount, ccy
  2. Concatenate the string from step (1) with :
    • For Card-mode
      • card_no
        Concatenation of the first-6-digits and last-4-digits of the card_no. Example: 4026000002 (from 4026000000000002)
      • exp_date (in ‘MMYYYY’ format)
      • cvv2
        The last digit of cvv2.
        Example: 3 (from 123)
    • For Wallet-Mode
      • wallet_id
    • For Tokenization-mode
      • token_id
        The first-6 and last-4 of the token_id.
        Example: 4026120002 (from 4026123456780002)OR payer_id The whole string of the payer_id.
        Example: 4026123456780002
      • cvv2
        The last digit of cvv2.
        Example: 3 (from 123)
  3. Now please concatenate the string from step (2) with the secret-key given by RDP.
  4. Finally, the signature is the Hash the string from step (3) using SHA-512 algorithm (the signature is to be sent in lowercase form).

Transaction Request JSON Sample

For Card-Mode

For secret-key:

D716A4188569B68AB1B6DFAC178E570114CDF0EA3A1CC0E31486C3E41241BC6A76424E8C37AB26F096FC85EF9886C8CB634187F4FDDFF645FB099F1FF54C6B8C

Concatenated string for signature:

1000089029TST101S1.02SGD41111111111120173D716A4188569B68AB1B6DFAC178E570114CDF0EA3A1CC0E31486C3E41241BC6A76424E8C37AB26F096FC85EF9886C8CB634187F4FDDFF645FB099F1FF54C6B8C

Example:

{
 "merchant_reference": "testing",
 "payer_name": "abc",
 "card_no": "4111111111111111",
 "exp_date": "112017",
 "cvv2": "123",
 "mid": "1000089029",
 "order_id": "TST101",
 "amount": "1.02",
 "ccy": "SGD",
 "api_mode": "direct_n3d",
 "payment_type": "S",
 "payer_email": "merchant@merchant.com",
 "signature": "ec67c7ed4cf9e2acfca7d0e53750f1a1696a10636fbb9d5781d6fa5e8fae53a5e476c4cb3a5268aa5a0398f118f763e7f0eb77b8fed742f5c0dc192593cb1cf5"
}

 

For Tokenization-Mode

For secret-key :

D716A4188569B68AB1B6DFAC178E570114CDF0EA3A1CC0E31486C3E41241BC6A76424E8C37AB26F096FC85EF9886C8CB634187F4FDDFF645FB099F1FF54C6B8C

Concatenated string for signature:

1000089227TST101A1.02SGD1981401925D716A4188569B68AB1B6DFAC178E570114CDF0EA3A1CC0E31486C3E41241BC6A76424E8C37AB26F096FC85EF9886C8CB634187F4FDDFF645FB099F1FF54C6B8C

Example:

{
 "payer_name": "abc",
 "payer_id": "1981401247381925",
 "mid": "1000089227",
 "order_id": "TST101",
 "amount": "1.02",
 "ccy": "SGD",
 "api_mode": "direct_n3d",
 "payment_type": "A",
 "payer_email": "merchant@merchant.com",
 "signature": "09b942bf5778e160d3d83653127466a59e6073dfe85e81ec5c368089d91ff564c4c556e37bc6fd84bc82601819762a843158e8dfc0e8f17bc6afb565ae7b9959"
}

Transaction Response

Transaction 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.

  • 0 : success – accepted transaction.
  • -1 : bank/acquirer rejection.
  • -01 : Pending, Merchant has to continue with either Polling Query API or waiting for Notification (if send notify_url at request phase)
  • Others (minus) : request-error

Please refer to ‘Appendix B’ for complete list of response code.

response_msg Mandatory TEXT

Description on the response code.

response_status Conditional [on error only] TEXT

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

mid Conditional [No-Error] VARCHAR(20)

The merchant ID generated by RDP for merchant.

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. For Pending (response_code =”-01″), this data will be used heavily for Querying the result.

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, I

Possible values:

S : Sale transaction

A : (pre) Authorization transaction

I : Installment transaction

created_timestamp Conditional [No-Error] YYYY-MM-DD hh:mm:ss

The date-time when the response is created. In a 24 hour format. Time zone 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 response signature. For signature generation, validation and note please refer to the next section.

acquirer_authorized_amount Conditional [on success only] Numeric

The amount authorized by acquirer
Note: 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:ss

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.

payment_mode Conditional [no-error] NUMERIC

The payment mode or card type that customer used for the transaction. Please refer to Appendix C (Payment Mode List).

payer_id Conditional VARCHAR(100)

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

payer_name Optional [Acquirer Dependent] VARCHAR(45)

The cardholder’s name.

exp_date Optional [Acquirer Dependent] VARCHAR(6)

The expiry date of the card used for transaction.

Transaction response result example:

{"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"}

Transaction Response Signature

The following is a step by step procedure to calculate the signature response. This is required in order to verify that the response is coming from RDP system.

  1. Extract out the signature field of the response (in terms of implementation it might be more practical to decode the JSON into your native language more process able format.)
  2. Sort the response field – value maps by its fields alphabetically.
  3. Generate a string which is a concatenation of the value of each map in the sorted order from step 2.
  4. Concatenate the string from step 3 with the secret-key given by RDP (secret-key is a special identifier that is meant to be known only by merchant and RDP).
  5. Calculate the signature by doing SHA-512 hashing method on the string from step 4.
  6. Compare the calculated signature from step 5 with the one received in the original response from RDP.

Note:
Please take note that the ‘signature’ field will not always be available or exist inside RDP response message; and might only be available or exist for these following response codes:

Response Code Description
0 OK or successful.
-1 Bank or acquirer rejection.
-01 The transaction is on pending status. Merchant need to continue with either polling query API or waiting for push notification (if there is 'notify_url' parameter at request phase).

Transaction Response JSON Sample

{
 "mid": "1000089227",
 "transaction_id": "TST101_1497589026754509762",
 "order_id": "TST101",
 "acquirer_transaction_id": "1450067604",
 "request_amount": "1.02",
 "request_ccy": "SGD",
 "authorized_amount": "1.02",
 "authorized_ccy": "SGD",
 "response_code": "-1",
 "response_msg": "bank reject",
 "acquirer_response_code": "9967",
 "acquirer_response_msg": "issuer bank reject",
 "acquirer_authorization_code": "1450067604",
 "created_timestamp": "2015-12-14 12:33:24",
 "acquirer_created_timestamp": "2015-12-14 12:33:24",
 "first_6": "520000",
 "last_4": "7102",
 "payer_name": "abc",
 "exp_date": "112017",
 "request_timestamp": "2015-12-14 12:33:21",
 "merchant_reference": "",
 "transaction_type": "A",
 "signature": "28b2a637e0ce35949b6120d9ad4ef577a93c4e86c788e4575e430b4136bb8b0a3dd3f2490e76a0885918b40ae73a580bc08faeb0a048ecac9691bc4e9e780b30"
}