RDP Merchant API

Message Data

Service End Points

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

Transaction Request Parameters

Field Name Status Value Type Description
response_type Mandatory VARCHAR(4)

Possible values: “json”.

action_type Mandatory VARCHAR(7)

Possible values:

  • refund
  • capture
  • void
  • requested_refund
order_number Mandatory VARCHAR(20)

For refund and capture transaction, this is the original unique order number to be refunded or captured – max 20 chars. Order number is in alphanumeric characters.

Example: DT13210

mid Mandatory VARCHAR(10)

RDP merchant ID – 10 characters (obtained from Red Dot Payment).

signature Mandatory VARCHAR(32)

A MD5 signature to proof that the request message is coming from the merchant. For signature generation, validation and note please refer to transaction signature section (4.4).

amount Conditional (mandatory for capture & refund) NUMERIC

Transaction amount and it must consist numbers or digits only.

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)
currency Conditional (mandatory for capture & refund) VARCHAR(3)

3 digits currency code based on ISO 4217 standard or format. This will be according to your merchant setup with RDP.

Example: SGD, USD, IDR, CNY, THB, VND, etc.

transaction_id Mandatory VARCHAR(32)

Unique transaction identification number that was returned by the bank or acquirer that belong to the original transaction.

Transaction Response Parameters

Field Name Status Value Type Description
result_status Mandatory VARCHAR(10)

Possible values:

  • accepted” : successful transaction.
  • failed” : failed transaction.
  • pending” : pending transaction (transaction is under process and awaiting approval).
reason_code Mandatory TEXT

Reason code response from the acquirer or bank.

order_number Mandatory VARCHAR(20)

Original transaction order number in alphanumeric characters.

amount Conditional (mandatory for capture & refund on accepted response) NUMERIC (with maximum 2 digits behind comma)

Transaction amount that consists numbers only.

currency Conditional (mandatory for capture & refund on accepted response) VARCHAR(3)

Transaction currency code based on ISO 4217 standard.

timestamp Conditional YYYY-MM-DD hh:mm:ss

The timestamp of the transaction, and only applicable for successful transaction. The format of the timestamp is: YYYY-MM-DD hh:mm:ss, where:

  • YYYY: 4 digit of the year
  • MM: 2 digit of the month with leading zeros (01 – 12)
  • DD: Day of the month, 2 digits with leading zeros (01 – 31)
  • hh: 24-hour format of an hour with leading zeros (00 – 23)
  • mm: Minutes with leading zeros (00 – 59)
  • ss: Seconds, with leading zeros (00 – 59).
description Optional TEXT

Any descriptions regards to the current specific transaction.

signature Conditional VARCHAR(32)

A MD5 signature to proof that this request is coming from RDP payment gateway. For signature generation, validation and note please refer to the next section about transaction signature.

Transaction Signature

An electronic hash signature is included as part of data integrity measurement for transaction request and response interface between merchant’s system and RDP payment gateway. By using the transaction signature field, both merchant and RDP payment gateway system can ensure and identify that the transaction request and/or response are really coming from a trusted and valid specific source.

The transaction signature field inside the merchant’s transaction request message is formed by hashing all of request fields sent in HTTP POST, but excluding the ‘signature’ field itself. Field names and values need to be separated with “=” character, and subsequently, all parameters have to be sorted ascending based on ASCII character table, before they are combined together by using “&” (ampersand character) between those parameters.

Finally please add ‘&secret_key=<merchant’s secret key>’ at the end of the result string, followed by hashing the entire string in order to get or create the transaction signature. The hashing method will be using MD5 method, and the ‘signature’ field would be included as one of the HTTP POST parameters in small caps.

Notes:

  1. The ‘secret_key‘ field and value are only used as part of ‘signature’ field calculation, and must NOT be sent to RDP Connect payment gateway.
    Example Checking Response Signature:

    • Sample information :
      • Merchant’s URL = http://www.merchantexample.com/trans-url
      • Merchant’s secret key = REDDOT
      • RDP Response Parameters:
    • result_status = accepted
    • reason_code = 00
    • order_number = 20151130001
    • amount = 1.00
    • currency = SGD
    • timestamp = 2015-11-30 12:34:56
    • signature = b6c61c27a2692ba1a467265d4188ba6f

    Below are those steps to prepare, calculate and compare the transaction signature that should be done by merchant system when they get a response message from RDP payment gateway.

    1. RDP payment gateway sent a GET request message to merchant’s system together with the calculated signature, where it will be corresponding URL.The sample is as follow (no white spaces between all characters):
      http://www.merchantexample.com/trans-url?result_status=accepted&reason_code=00&order_number=20151130001& amount=1.00&currency=SGD&timestamp=2015-11-30%2012:34:56&signature=9dd4202b429cf4953900ef4ae30e691b
    2. Now the merchant system needs to do some checks whether the received response message is really coming from RDP payment gateway.
      Merchant can get the response by accessing the GET parameters of the HTTP request. This might depend on each framework implementation.Sample code in PHP language:

      //The response is in an associative array retrieved from GET request 
      $rdp_response = $_GET;
    3. The transaction signature from RDP payment gateway will be inside the field “signature”.
      Sample code in PHP language, on how to retrieve the signature field:

      $rdp_signature = $_GET[“signature”];
    4. On the next step, merchant needs to get the list of key-value of the GET parameters, but without the ‘signature’ field.
      This parameter list will be required in order to calculate the signature.
      Sample code in PHP language:

      unset($rdp_response ['signature']);
    5. Continue with the process of calculating signature, merchant will need to sort all the parameters (except for ‘signature’ field) based on the key in ascending order.
      Sample code in PHP language:

      ksort($rdp_response);
    6. Construct a string based on the key and value of those parameters from step 5.
      Sample code in PHP language:

      $string_to_hash = “”;
      foreach ($rdp_response as $key=>$value) {
            $string_to_hash .= $ key . '=' . ($value) . '&';
      }
    7. Concatenate the string made in previous step with the ‘secret_key’ field
      Sample code in PHP language

      $secret_key = “D716A4188569B68AB1B6DFAC178E570114CDF0EA3A1CC0E31486C3E41241BC6A76424E8C37AB26F096FC85EF9886C8CB634187F4FDDFF645FB099F1FF54C6B8C”;
      $string_to_hash .= 'secret_key=' . $ secret_key;

      Note:
      The secret key information should only be known by Red Dot Payment and merchant, so please never give the information in a publicly accessible channel.

    8. Now please calculate the signature by doing MD5 hashing on the string created in step 7.
      Sample code in PHP language:

      $merchant_calculated_signature = md5($string_to_hash);
    9. Finally merchant needs to compare whether their calculated signature result (from step 8) is similar with the received signature field in their GET request (from step 3).
      Sample code in PHP language:

      $is_really_from_rdp = ($merchant_calculated_signature == $rdp_signature);
    10. The calculated signature result should be similar with the received signature field in their GET request.

     

  2. Please take note that the ‘signature’ field inside RDP response message will not always be available or exist; and might only be available or exist for these following response codes:
Response Code Description
0 OK or successful.
-1 Failed.
-01 Pending Refund (applicable to WeChat)