3D Get Token

Why 3D?

3D authentication provides a more secure way of authenticating the ownership of the card holders. When requesting a payment token, the card holder will need to enter the OTP (one-time password) to prove that they are the owner of the card. This will block any use of unauthorised cards for senangPay's tokenisation.

How does it work?

This is not a RESTful API. The flow of the new Get Token method consists of multiple web views. You can either have an HTML form that will send the required parameters or you can send it as query string parameters (GET). If you are implementing tokenisation on a mobile app, you need to implement it in a web view or iframe. Unfortunately, at the moment, we do not provide any SDKs.

Will senangPay charge card holders for card validation?

senangPay may make two separate transactions of RM1 each on the card to prove that the card is valid and can perform both 3D and 2D transactions. Both transactions will be refunded back to the card upon completion. It may take several days for the bank to reverse the funds back to the card.

---

Tokenisation Return URL and Callback URL

Before anything else, you need to provide the Tokenisation Return URL and Callback URL. Tokenisation Return URL is the URL where senangPay will redirect the card holders to after the payment (card validation) has been processed. This will the the page where the user will see or land on after card validation.

Tokenisation Callback URL is the URL to your backend, where senangPay will send notifications about the card validation status.

You need to provide the URLs at Your senangPay Dashboard > Settings > Profile > Shopping Cart Integration Link

Fill in the Tokenisation Return URL and Tokenisation Callback URL field.

---

Integration Method

1. 3D Get Token (This is not a RESTful API)

Production URL Endpoint (GET/POST)	https://app.senangpay.my/tokenization/{merchant_id}
Sandbox URL Endpoint (GET/POST)	https://sandbox.senangpay.my/tokenization/{merchant_id}

2. Request Parameters (All Mandatory)

Item	Details
order_id	Used by your system to track the request and response. It can be any value.
name	Your customer’s name. Maximum length is 100 characters. Example : Micheal Solomon
email	Your customer’s e-mail. Example : [email protected]
phone	Your customer’s phone number. Example : [phone]
hash	This hash confirms you are an active senangPay merchant. Generate it using HMAC SHA256 with your senangPay secret key. Here’s a simple PHP example: $merchant_id = '123456789'; $secret_key = '34-9887'; $order_id = 'abc654321'; // Your order ID $string_to_hash = $merchant_id . $order_id; $final_hash = hash_hmac('SHA256', $string_to_hash, $secret_key); For example, hashing 54316046480557456 would produce: 151bf4a479ed166d6b211528d0a0b452625c8fe83

3. Respond Parameters

Item	Details
status	Token creation status. 1 if successful. 0 if failed.
order_id	The order ID provided earlier.
token	Generated if card validation succeeds, used for future payments. If validation fails, the token value is 0.
cc_num	Last four digits of the card, displayed as XXXXXXXXXXXX1118. If validation fails, the value is 0000.
cc_type	Indicates the card type, either vs for Visa or mc for Mastercard. If validation fails, the value is xx.
msg	Card validation status message. Provides different messages to detail success or failure reasons.
hash	Generated by senangPay to verify the response. Use HMAC SHA256 with your secret key to validate it. Here’s a PHP example: $secret_key = '34-9887'; $order_id = urldecode($_GET['order_id']); $status_id = urldecode($_GET['status_id']); $token = urldecode($_GET['token']); $cc_num = urldecode($_GET['cc_num']); $cc_type = urldecode($_GET['cc_type']); $msg = urldecode($_GET['msg']); $string_to_hash = $merchant_id . $order_id . $status_id . $token . $cc_num . $cc_type . $msg; $hash = hash_hmac('sha256', $string_to_hash, $secret_key); $hash = hash_hmac(‘sha256’,$string_to_hash,$secret_key); ?>

Get token API (3D Token)

get

https://sandbox.senangpay.myhttps://api.sandbox.senangpay.myhttps://app.senangpay.my

/tokenization/{merchantID}

Use this endpoint to send tokenization request.

Path parameters

merchantIDstringRequired

Retrievable in the senangPay Dashboard

Example: 14222653788472

Query parameters

order_idstringRequired

Merchant unique order ID for each tokenization request.

namestringRequired

Customer's name. Max length 100.

emailstringRequired

Customer's email address.

phonestringRequired

Customer's phone number.

hashstringRequired

Hash generated using HMAC SHA256. Construct the hash as follows hash_hmac(‘SHA256’, {merchant_id}{order_id}, {merchant_secret_key})

Responses

302

Redirects to senangPay's payment page.

get

/tokenization/{merchantID}

PHPJavaScriptJavacURLNode.js

<?php

  $url = "https://sandbox.senangpay.my/tokenization/{merchantID}";

  // Prepare the data as query parameters
  $data = [
      "order_id" => "ORD12345",
      "name" => "Amir",
      "email" => "[email protected]",
      "phone" => 123456789,
      "hash" => "a8167dd09f01ebed0b18e67b2cc2424a0d058ccc83d94803482ecdeed"
  ];

  // Initialize cURL session
  $ch = curl_init();

  // Set the URL with query parameters
  curl_setopt($ch, CURLOPT_URL, $url . '?' . http_build_query($data));
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

  // Execute the GET request
  $response = curl_exec($ch);

  // Close cURL session
  curl_close($ch);

  // Output the response (for debugging purposes)
  echo $response;
?>

302

Redirects to senangPay's payment page.

No content

*The "Test it" option is available when using Firefox or Safari to test the API.

4. Callback

The Callback URL is used as an alternative notification to merchant backend in case there is a breakdown in transaction flow. This is optional, so you can opt not to use this feature. However, this feature is recommended to ensure data integrity between a merchant’s system and senangPay.

The callback process will send the same parameters as what is being sent to the return URL. The callback URL must print out a simple ‘OK’ without any HTML tags. The OK response is needed in order for the callback function to know if it has successfully sent the callback data.

senangPay will fire the callback one minute after the validation is done.