Why 3D?

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

How does it work?

This is not a RESTful API​. The flow of the new Get Token method consists of multiple web view. You can either have an HTML form that will send the required parameters OR you can send as query string parameters (GET). If you are implementing tokenization on mobile app, you need to implement in a web view/iframe. We are apologise that we are not providing any SDK at the moment. So, full web view it is.

Will senangPay charged card holder for card validation?

senangPay will make two transactions of RM1 on the card, to prove that the card is valid and can perform both 3D and 2D transaction. ​Both transactions will be reversed back to the card​. However, it may take several days for the bank to reverse back the money to the card.

Tokenization Return URL & Callback URL

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

While Tokenization Callback URL is the URL to your backend, where senangPay will send notification about the card validation status.

You need to provide the URLs at Your senangPay ​Dashboard > Settings > Profile > Shopping Cart Integration Link >​. Fill in the ​Tokenization Return URL​ and ​Tokenization Callback URL​ field.

Tokenisation callback url2

Integration Method

3D Get token (This is not REST)

 

Production URL Endpoint (GET/POST)

https://app.senangpay.my/tokenization/<your-merchant-id>

Sandbox URL Endpoint (GET/POST)

https://sandbox.senangpay.my/tokenization/<your-merchant-id>

Request Parameter (All Mandatory)


Item Details
order_id This is for your system to track the request response. It can be anything.
name Your customer name. Maximum length is 100.
Eg. Micheal Solomon
email Your customer email.
Eg. micheal@theboringcompany.com
phone Your customer’s phone number.
Eg. +60123456789
hash

This hash is for us to verify that you are a senangPay active merchant. This hash must be generated using HMAC SHA256. Use your senangPay’s secret key as the hash key.

What you need to hash? ​<your-merchant-id><order-id> Below is an example in PHP.

$merchant_id = ‘123456789’;
$secret_key = ‘34-9887’;
$order_id = ‘abc654321’; # the order id provided by you. $string_to_hash = $merchant_id . $order_id;

$final_hash = hash_hmac(‘SHA256’, $string_to_hash, $secret_key);

Respond Parameter


Item Details
status Token creation status.
* ​1​ if success.
* ​0​ if failed.
order_id

The order id provided earlier.

token

If card validation succeed, token will be generated. The token will be used for future payment on the card.

If card validation failed, token value will be ​0​.

cc_num

The last four digits of the card. You might want to display the card number on your app, so, you can use these four digits and display as XXXXXXXXXXXX1118​.

If card validation failed, cc_num value will be ​0000​.

cc_type

This is the card type. Basically either VISA or Mastercard. Visa is ​vs and Mastercard is ​mc​.

When failed, the value is ​xx​.

msg

Card validation status message. You will get various messages based on scenarios. If senangPay failed to validate the card, you will know the reason here. If succeed, you’ll get the message here too.

hash

This time around, the hash is generated for you. You need to verify the hash in order to make sure the response is coming from senangPay. Same hashing mechanism, HMAC SHA256 and your secret key as key hash key.

What you need to hash?

<your-merchant-id><order_id><status_id><token><cc_num><cc_ type><msg>

Below is an example in PHP.

$merchant_id = ‘123456789’;
$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;

$final_hash = hash_hmac(‘SHA256’, $string_to_hash, $secret_key);

Callback

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 merchant’s system and senangPay.

Callback process will send the same parameters as what is being sent to 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 done.

Sample Code

You can download our sample code, written in PHP here https://bit.ly/35JTynX

Leave a Reply