Converting payment form link to QR code

API GUIDE

Introduction

Hi, welcome to senangPay API Guide! This API is to provide the functionality for merchant to retrieve information from senangPay without the need to log in to senangPay Dashboard. This is useful for merchant that is having their own system and do not wish to log in to both own system and senangPay to manage their business.

API

A. Query Order Status

This is to retrieve transactions result for order id as passed using Open API method.

1. URL: https://app.senangpay.my/apiv1/query_order_status

2 . Method: GET

3. Parameters:

merchant_id
order_id
hash

4. Return format: JSON

5. In order to generate the hash, create a single string consisting of (according to sequence)

merchant_id
secret key
order_id

6. Then please use md5 to hash the string. Sample code in PHP as shown below :

<?php

$merchant_id = '543160464805574';
$secret_key = '21245-957';
$order_id = '123';


$hash = md5($merchant_id.$secret_key.$order_id);


?>

So the string to be hash is 54316046480557421245-957123 which will generate hash values as:

368c7a62e622a553107dc5b30849a5f2

7. If you choose SHA256 , sample code in PHP as shown below :

<?php

$merchant_id = '543160464805574';
$secret_key = '21245-957';
$order_id = '123';


$hash = hash_hmac('sha256',$merchant_id.$secret_key.$order_id, $secret_key);


?>

So the string to be hash is 54316046480557421245-957123 which will generate hash values as:

b613679a0814d9ec772f95d778c35fc5ff1697c493715653c6c712144292c5ad

B. Query Transaction Status

This is to retrieve transaction result for a specific transaction reference

1. URL: https://app.senangpay.my/apiv1/query_transaction_status

2. Method: GET

3. Parameters:

merchant_id
transaction_reference
hash

4. Return format: JSON

5. In order to generate the hash, create a single string consisting of the value (according to sequence)

merchant_id
secret key
transaction_reference

6. Then please use md5 to hash the string. Sample code inPHP as shown below :

<?php

$merchant_id = '543160464805574';
$secret_key = '21245-957';
$transaction_reference = '160499101311679101';

$hash = md5($merchant_id.$secret_key.$transaction_reference);

?>

So the string to be hash is 54316046480557421245-957160499101311679101 which will generate hash values as:

640a0a2f9bbf2a1e78b64f8849bfbf71

7. If you choose SHA256, sample code in PHP as shown below :

<?php

$merchant_id = '543160464805574';
$secret_key = '21245-957';
$transaction_reference = '160499101311679101';

$hash = hash_hmac('sha256',$merchant_id.$secret_key.$transaction_reference, $secret_key);

?>

So the string to be hash is 54316046480557421245-957160499101311679101 which will generate hash values as:

5685bce1a5c462c4a3f9d40440cab606f02886fbe246ae094f16c492754a2f6b

C. Get Transaction List

This is to retrieve transaction result for a specific transaction reference

1. URL:

https://app.senangpay.my/apiv1/get_transaction_list

2. Method: GET

3. Parameters:

merchant_id
timestamp_start
timestamp_end
hash

4. Return format: JSON

5. In order to generate the hash, create a single string consisting of the value (according to sequence)

merchant_id
secret key
timestamp_start
timestamp_end

6. Then please use md5 to hash the string. Sample code in PHP as shown below :

<?php

$merchant_id = '543160464805574';
$secret_key = '21245-957';
$timestamp_start = '1577808000';//January 1, 2020 12:00:00 AM
$timestamp_end = '1577894399';// January 1, 2020 11:59:59 PM

this will generate 5606f217f05896ae0937c7f96437327b as hash

$hash = md5($merchant_id.$secret_key.$timestamp_start.$timestamp_end);

?>

7. If you choose SHA256, sample code in PHP as shown below :

<?php

$merchant_id = '543160464805574';
$secret_key = '21245-957';
$timestamp_start = '1577808000';//January 1, 2020 12:00:00 AM
$timestamp_end = '1577894399';// January 1, 2020 11:59:59 PM

this will generate 58e13aadcac0070a32c504949e2b2da6b0b4341828461eac5fbd101f5a481616 as hash

$hash = hash_hmac('sha256',$merchant_id.$secret_key.$timestamp_start.$timestamp_end, $secret_key);

?>

8. The value of timestamps must be more than 0 and the end timestamp must be more than start timestamp.

9.. Timestamps refer to UNIX timestamp.

D. API Endpoint for MOTO Transaction

1. Creating MOTO Payment

Item	Detail
API Endpoint	http://app.senangpay.my/apiv1/pay_cc

1.1 Authorization header

Type	Basic
Username	< your-merchant-id > As listed in the profile settings page.
Password	None, leave empty.

1.2 Request Paramater (all is mandatory)

Parameter Name	Parameter value/description
order_id	Your order id. Can be number or string. Other character is invalid. Eg. 1234
name	Your customer name. Maximum length is 100. Eg. Abu Bin Ali
phone	Your customer phone number. Eg. 0109876543
email	Your customer email. Eg. [email protected]
detail	Your order detail. Maximum length is 100. Eg. Order for product id #4
amount	Your order amount in integer format. Convert from decimals as necessary. Eg. if the amount is RM 2.00, you need to send 200.
cc_number	Your customer credit card number.
cc_exp	Your customer credit card expiration date in MMYY format. Eg. if the card expires on January 2017, you need to send 0117
cc_cvv	Your customer credit card CVV number. Eg. 123
hash	A string hashed with your secret key (from your profile setting page) in HMAC hashing algorithm with SHA256 in the following format: < your merchant id >< name >< email >< phone >< detail >< order_id >< amount > *without the < > character

1.3 Example Request

curl https://app.senangpay.my/apiv1/pay_cc -u 123456789012345: \
 -d 'name= Abu Bin Ali' \
 -d [email protected] \
 -d phone=0109876543 \
 -d order_id=1234 \
 -d 'detail=Order for product id #4' \
 -d amount=1000 \
 -d cc_number=5105105105105100 \
 -d cc_exp =0117 \ -d cc_cvv=123 \
 -d hash=89f98937fb86cc1fb6d4a12c82df0041738c2cdb99513567b76c61d1ea983f18

1.4 Response Parameter

Parameter Name	Parameter value / description
status	Your transaction status. 1 if success. 0 if failed.
transaction_id	Your transaction ID number.
order_id	Your original order ID.
amount_paid	Amount transacted from the credit card in integer format. Eg. if the amount transacted is RM 2.00, it will output 200.
msg	Transaction status message. If it was successful you will receive ‘Payment was successful’. If the transaction failed, you will receive the error message in this parameter for further checking.
hash	A string hashed with your secret key (from your profile setting page) in HMAC hashing algorithm with SHA256 in the following format: < your merchant id >< status_id >< order_id >< transaction_id >< amount_paid >< msg > *without the < > character

1.5 Sample Response

{
   "status":1,
   "transaction_id":"14951544812820",
   "order_id":"1234",
   "amount_paid":1000,
   "msg":"Payment was successful",
   "hash":"99b6e99bb0aa663101b1e4f6f8d69c2efb41ef81a5a7aa030bf76a098a03d233"
}

2. Get MOTO Payment Details By Order ID

This endpoint is helpful for determining order status before attempting another payment if the previous payment creation was failed return a server error.

Item	Detail
API endpoint	http://app.senangpay.my/apiv1/order/

2.1 Authorization Header

Type	Basic
Username	< your-merchant-id > As listed in the profile settings page.
Password	None, leave empty.

2.2 URL Parameter

Parameter Name	Parameter value/description
order_id	Your order id. Can be number or string. Other character is invalid. Eg. 1234

2.3 Example Request

curl https://app.senangpay.my/apiv1/order/1234 -u 123456789012345:

2.4 Response Parameter

Parameter Name	Parameter value / description
status	Your transaction status. 1 if success. 0 if failed.
msg	Query status message. If it was successful you will receive ‘Query was successful’. If the query failed in any way, you will receive the error message in this parameter for further checking.
data	An array of MOTO transactions that matches the given order ID, sorted by newest transaction first. Please refer to MOTO Data Transaction Response section for type of data returned.
hash	A string hashed with your secret key (from your profile setting page) in HMAC hashing algorithm with SHA256 for validity of data returned by us in the following format: < your merchant id >< order-id > *without the < > character

2.5 Sample Response

{
"status":1
"msg":"Query was successful",
"data":[{
  "transaction_reference": "14951839358320",
  "buyer_contact": {
  "name": "Abu Bin Ali ",
  "email": "[email protected]",
  "phone": "0109876543"
  },
  "order_detail": {
  "grand_total": 1000
  },
  "payment_info": {
  "transaction_date": "16:52 19 April 2017",
  "payment_mode": "Credit Card",
  "status": "paid"
  },
  "date_created": "16:52 19 April 2017"
},
{
  "transaction_reference": "14951839358319",
  "buyer_contact": {
  "name": "Abu Bin Ali ",
  "email": "[email protected]",
  "phone": "0109876543"
  },
  "order_detail": {
  "grand_total": 1000
  },
  "payment_info": {
  "transaction_date": "16:50 19 April 2017",
  "payment_mode": "Credit Card",
  "status": "failed"
  },
  "date_created": "16:50 19 April 2017"
 }],
 "hash":"cb13f0a935274af4bd74c25c4087b81c6b05b8637255502ce1011477d552d0d2"
 }

3. Get MOTO Payment Details By Transaction Reference

Item	Detail
API endpoint	http://app.senangpay.my/apiv1/order/

3.1 Authorization header

Type	Basic
Username	< your-merchant-id > As listed in the profile settings page.
Password	None, leave empty.

3.2 URL Parameter

Parameter Name	Parameter value / description
transaction_reference	The transaction reference number to check.

3.3 Example Request

curl https://app.senangpay.my/apiv1/transaction/1234 -u 123456789012345:

3.4 Response Parameter

Parameter Name	Parameter value/description
status	Your transaction status. 1 if success. 0 if failed.
msg	Query status message. If it was successful you will receive ‘Query was successful’. If the query failed in any way, you will receive the error message in this parameter for further checking.
data	A detail of the MOTO transaction that matches the given transaction reference. Please refer to MOTO Data Transaction Response section for type of data returned.
hash	A string hashed with your secret key (from your profile setting page) in HMAC hashing algorithm with SHA256 for validity of data returned by us in the following format: < your merchant id >< transaction reference > *without the < > character

3.5 Sample Response

{
"status":1
"msg":"Query was successful",
"data":{
  "transaction_reference": "14951839358320",
  "buyer_contact": {
  "name": "Abu Bin Ali ",
  "email": "[email protected]",
  "phone": "0109876543"
  },
  "order_detail": {
  "grand_total": 1000
  },
  "payment_info": {
  "transaction_date": "16:52 19 April 2017",
  "payment_mode": "Credit Card",
  "status": "paid"
  },
  "date_created": "16:52 19 April 2017"
 },
 "hash":"cb13f0a935274af4bd74c25c4087b81c6b05b8637255502ce1011477d552d0d2"
 }

4. MOTO Data Transaction Response

This is the MOTO transaction data, structured for response for any given endpoint querying for MOTO transaction details.

4.1 Response Parameter

Key	Value details / description
transaction_reference	The transaction reference number
buyer_contact	Buyer contact details object as sent when creating the original payment. Consist of the following key values: Key Value name Buyer’s name email Buyer’s email phone Buyer’s phone
order_detail	Transaction details object of the MOTO transaction. Consist of the following key values: Key Value grand_total Transaction amount paid/needs to be paid in integer format. ie. RM 2.00 will be returned as 200
payment_info	Payment info details object. Consist of the following key values: Key Value transaction_date Transaction date in hh:mm day month year ie. 08:07 19 May 2017 payment_mode Will return only ‘Credit Card’ for now status Payment status. Returned values will be one of: paid pending payment failed
date_created	Transaction date in hh:mm day month year ie. 08:07 19 May 2017

4.2 Sample Response

{
 "status":1
 "msg":"Query was successful",
 "data":{
   "transaction_reference": "14951839358320",
   "buyer_contact": {
   "name": "Abu Bin Ali ",
   "email": "[email protected]",
   "phone": "0109876543"
  },
   "order_detail": {
   "grand_total": 1000
  },
   "payment_info": {
   "transaction_date": "16:52 19 April 2017",
   "payment_mode": "Credit Card",
   "status": "paid"
   },
   "date_created": "16:52 19 April 2017"
 },
   "hash":"cb13f0a935274af4bd74c25c4087b81c6b05b8637255502ce1011477d552d0d2"
}

Get Token Integration Update

E. What is senangPay tokenization?

Tokenization allows merchant to charge customer’s credit card without the need to enter the credit card details (name, card number, expiry and cvv).

1. How does it works?

Merchant’s customers will enter their credit card details one time only. During this one time process, senangPay will validate the card to make sure the card is valid by charging an amount of RM1 to the card. Not to worry that this amount will be voided later. Meaning that the transaction will never appeared on the customer’s credit card statement.

If senangPay failed to charge the card, meaning that the card is not valid. Once validated, the card’s info will be stored in senangPay’s server (PCI-DSS certified).

2. API List

2.1 Get token

We have developed a new secure way of generating token for our tokenization payment. In this new feature, card holder is required to pass the OTP (3D secure) check before able to get the payment token. Also, there are few extra layers been added to ensure no non authorised card being used for this tokenization payment feature.

The old (current) way of getting the payment token will be discontinued and no more access will be granted.

Get token (3D Get Token) -Will be replacing the former 2D token*

Get token (Will be deprecated on 31st December 2019)

Item	Detail
URL endpoint (POST)	https://app.senangpay.my/apiv1/get_payment_token

2.2 Authorization Header (Basic Auth)

Type	Basic
Username	< your-merchant-id > As listed in the profile settings page.
Password	None, leave empty.

2.3 Request Parameter (all is mandatory)

Parameter Name	Parameter value/description
name	Your customer name. Maximum length is 100. Eg. Abu Bin Ali
email	Your customer email. Eg. [email protected]
phone	Your customer phone number. Eg. 0109876543
cc_number	Your customer credit card number.
cc_exp	Your customer credit card expiration date in MMYY format. Eg. if the card expires on January 2017, you need to send 0117
cc_cvv	Your customer credit card CVV number. Eg. 123

2.4 Response Parameter

Parameter Name	Parameter value / description
status	Your transaction status. 1 if success. 0 if failed.
token	If card validation succeed, token will be generated. The token will be used for future payment on the card.
msg	Card validation status message. If it was successful you will receive ‘Card successfully verified, the generated token can be used for future payment.’. If the validation failed, you will receive the error message in this parameter for further checking.

3. Pay credit card using token

Item	Detail
URL endpoint (POST)	https://app.senangpay.my/apiv1/pay_cc

3.1 Authorization Header (Basic Auth)

Type	Basic
Username	< your-merchant-id > As listed in the profile settings page.
Password	None, leave empty.

3.2 Request Parameter (All Mandatory)

Parameter Name	Parameter value/description
name	Your customer name. Maximum length is 100. Eg. Abu Bin Ali
email	Your customer email. Eg. [email protected]
detail	Your order detail. Maximum length is 100. Eg. Order for product id #4
phone	Your customer phone number. Eg. 0109876543
order id	Your order id. Can be number or string. Other character is invalid. Eg. 123
amount	Your order amount in integer format. Convert from decimals as necessary. Eg. if the amount is RM 2.00, you need to send 200.
token	Generated token from Get Token API
hash	A string hashed with your secret key (from your profile setting page) in HMAC hashing algorithm with SHA256 in the following format: < your merchant id >< name >< email >< phone >< detail >< order_id >< amount > *without the < > character

3.3 Response Parameter

The same response as our MOTO API https://guide.senangpay.my/senangpay-api-endpoint-for-moto-transaction-2/

4. Enable/disable credit card

Item	Detail
URL endpoint (POST)	https://app.senangpay.my/apiv1/update_token_status

4.1 Authorization header (Basic Auth)

Type	Basic
Username	< your-merchant-id > As listed in the profile settings page.
Password	None, leave empty.

4.2 Request Parameter (All Mandatory)

Parameter Name	Parameter value / description
token	Generated token from Get Token API

4.3 Response Parameter

Parameter Name	Parameter value/description
msg	Message for the token is successfully disabled or enabled.
token	Generated token from Get Token API that has been disabled or enabled.

5. Validate payment token

Item	Detail
URL endpoint (POST)	https://app.senangpay.my/apiv1/validate_token

5.1 Authorization header (Basic Auth)

Type	Basic
Username	< your-merchant-id > As listed in the profile settings page.
Password	None, leave empty.

5.2 Request Parameter (All Mandatory)

Parameter Name	Parameter value / description
token	Generated token from Get Token API

5.3 Response Parameter

Parameter Name	Parameter value/description
status	Token validation status. 1 if success. 0 if failed.
msg	Token validation status message. If it was successful you will receive ‘Card has been successfully verified.’. If the validation failed, you will receive the error message in this parameter for further checking.
token	Generated token from Get Token API that has been disabled or enabled. The token will still be the same, nothing changed. We just return the same token here.

F. 3D Get Token

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

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

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

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

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

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

4.3 Fill in the Tokenization Return URL and Tokenization Callback URL field.

5. Integration Method

5.1 3D Get token (This is not REST)

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

5.2 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. [email protected]
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? Below is an example in PHP :

<?php

    $merchant_id = '543160464805574';
    $order_id = '56';
    $secret_key = '53-784';

    $hash = hash_hmac('sha256',$merchant_id.$order_id,$secret_key);
?>

So the string to be hash is 54316046480557456 which will generate hash values as:

151bf4a479ed166d6b211528d0a0b452625c8fe83656489c82286fcb975889b5

5.3 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? Below is an example in PHP :

<?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;

  $hash = hash_hmac('sha256',$string_to_hash,$secret_key);
?>

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

7. Sample Code

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

G. What is Merchant Hosted ?

1. Merchant hosted is where merchant can capture card information and pass to senangPay to process the payment. Using this method, you will bypass senangPay’s payment form. This feature is only applicable to selected senangPay’s merchant.

2. If you require integration that require senangPay’s payment form, please refer to Open API documentation.

1. Basic Info

To start, we will need the information as below. These can be retrieve from senangPay dashboard.

1.1Go to Menu > Settings > Profile

1.2 Refer to Shopping Cart Integration Link section. Get your Merchant ID and Secret Key information.

1.3 Then you will need to fill in the return URL. This is the URL where senangPay will redirect the buyer after the payment has been processed.

1.4 Next, you need to fill the Callback URL. Callback URL is used as alternative notification to merchant shopping cart in case there is a breakdown in transaction flow.

2. What parameters to send to senangPay

Below are the details of the elements in the table . This is the credit card expiry month/row_column]

Item	Detail
detail	This is the description to be displayed when making the payment. The maximum length is 500 characters. Any underscore (_) characters will be converted to space. Example: Shopping_cart_id_30. Only A to Z, a to z, 1 to 0, comma, dash and underscore is allowed.
amount	The amount to charge the buyer. The format must be in 2 decimal places. Example: 25.50
order_id	This is the id used to identify the shopping cart when senangPay redirect back the buyer after the payment was made. The maximum length is 100 characters. Example: 3432D4. Only A to Z, a to z, 1 to 0 and dash is allowed.
hash	This is the data to ensure the data integrity passed from the merchant’s shopping cart to senangPay. Refer to How to generate the secure hash section for more info.
name	This is the name of the customer that perform the payment
email	This is the email of the customer that perform the payment. Transaction confirmation email will be sent to this email.
phone	This is the phone number of the customer that perform the payment.
cc_name	This is the credit card holder name
cc_number	this is the credit card number.
cc_expiry_month	This is credit card expiry month Eg : If the card expires on May , it will be 05
cc_expiry_year	This os the credit card expiry year Eg : If the card expires on 2021 , it will be 21
cc_ccv	This is the credit card ccv

3. How to send the parameters to senangPay

3.1 The parameters can be send either using GET or POST method.

3.2 The URL is: https://app.senangpay.my/payment/merchant-hosted/

followed by your merchant id

3.3 Example: https://app.senangpay.my/payment/merchant-hosted/14222653788472

4. What parameters will you receive from senangPay

Below are the details of the elements in the table.

Item	Detail
status_id	This is to indicate the status of the payment. It only has 2 values which is 1 for successful and 0 for failed.
order_id	This is the the order that was sent to senangPay. This is to identify the shopping cart transaction.
msg	This is the message to describe the payment status. The maximum length is 100 characters. Take note that the message mat contain underscore. You can replace the underscore as space when displaying the message to your customer. Example: Payment_was_successful.
transaction_id	This is the transaction ID used by senangPay. You can use this ID to track the transaction in senangPay. The maximum length is 100 characters. Example: 14363538840.
hash	This is the data to ensure the data integrity passed from senangPay to the merchant’s shopping cart. Refer to section How to verify it the secure has is correct for more info.

5. How senangPay send the parameters to merchant’s shopping cart

5.1 The parameters will be send using GET method.

5.2 The parameters are sent to URL as configured in the return URL Refer to Info required section

6. How to generate the secure Hash

6.1 The secure hash is generated bu using md5 on a string consisting of (according to sequence):

Secret Key
Detail
Amount
Order ID
Name
Email
Phone Number
Credit Card Name
Credit Card Number
Credit Card Expiry Month
Credit Card Expiry Year
Credit Card CCV

6.2 For example, if the values for the parameters are as below:

Item	Detail
secret key	2-340
detail	Shopping_cart_id_30
amount	25.50
order_id	56
name	abu
email	[email protected]
phone	0123456789
cc_name	abu
cc_number	5111111111111118
cc_expiry_month	05
cc_expiry_year	25
cc_ccv	100
hash	231c95adb35f409d7ff9601c0a4bfcd0

6.3 Request parameter for md5

<?php

$secret_key = '2-340';
$detail = 'Shopping_cart_id_30';
$amount = '25.50';
$order_id = '56';
$name = 'abu';
$email = '[email protected]';
$phone = '0123456789';
$cc_name = 'abu';
$cc_number = '5111111111111118';
$cc_expiry_month = '05';
$cc_expiry_year = '25';
$cc_ccv = '100';

$string_to_hash = $secret_key.$detail.$amount.$order_id.$name.$email.$phone.$cc_name.$cc_number.$cc_expiry_month.$cc_expiry_year.$cc_ccv;

    $hash = md5($string_to_hash);
?>

which will generate hash values as :

231c95adb35f409d7ff9601c0a4bfcd0

6.4 Request parameter if you using sha256 :

<?php

$secret_key = '2-340';
$detail = 'Shopping_cart_id_30';
$amount = '25.50';
$order_id = '56';
$name = 'abu';
$email = '[email protected]';
$phone = '0123456789';
$cc_name = 'abu';
$cc_number = '5111111111111118';
$cc_expiry_month = '05';
$cc_expiry_year = '25';
$cc_ccv = '100';

$string_to_hash = $secret_key.$detail.$amount.$order_id.$name.$email.$phone.$cc_name.$cc_number.$cc_expiry_month.$cc_expiry_year.$cc_ccv;

    $hash = hash_hmac('sha256',$string_to_hash,$secret_key);
?>

which will generate hash values as :

cb88536c5f91252bfdec4b524688e0ef3adb0b1faf02645e00e712f6545190e0

7. How to verify if the secure hash is correct

7.1 Merchant will need to generate the secure hash and compare the secure hash that was received from senangPay.

7.2 For example, if the parameters received from senangPay are as below:

Item	Detail
status_id	1
order_id	56
transaction_id	14363538840
msg	Payment_was_successful

7.3 Verify respond if you using md5 :

$status_id = '1';
$order_id = '56';
$transaction_id = '14363538840';
$msg = 'Payment_was_successful';

$string_to_hash = $secret_key.$status_id.$order_id.$transaction_id.$msg;

    $hash = md5($string_to_hash);
?>

which will generate hash value as :

49197d877cb4fa7bd770134506b7fb0a

7.4 Verify respond if you using sha256 :

$status_id = '1';
$order_id = '56';
$transaction_id = '14363538840';
$msg = 'Payment_was_successful';

$string_to_hash = $secret_key.$status_id.$order_id.$transaction_id.$msg;

    $hash = hash_hmac('sha256',$string_to_hash,$secret_key);
?>

which will generate hash value as :

5d1b62649fd73ece981e6b6236f3f3789322400f6c1844815fe5347051ce8ba1

5. Now you need to compare the hash value that you have generated with the hash value sent from senangPay. If the value does not match, then data may have been tempered.

INTEGRATION

A. Recurring API

1. API for Recurring Payment

If you have your own system and wish to integrate to senangPay for recurring payment you will need to first add your product into senangPay. The product need to be created first in order for auditing purposes.

Below are the details and steps required.

2. Info required

To start we will need the information as below. These can be retrieve in senangPay Dashboard.

2.1 Go to Menu > Settings > Profile

2.2 Refer to Shopping Cart Integration Link section. Get your Merchant ID and Secret Key information.

2.3 Then you will need to fill in the Recurring Return URL. This is the URL where senangPay will redirect the buyer after the payment has been processed.

2.4 Next, you need to fill the Recurring Callback URL. Recurring Callback URL is used as alternative notification to merchant shopping cart in case there is a breakdown in transaction flow. For more info on Callback URL, read here.

3. Get the Recurring ID

Recurring id is the unique id to identify your recurring product. To obtain the recurring id, you must first create a recurring product in senangPay dashboard.

3.1 Go to Menu >Product > Create New

3.2 Create a recurring product. You can learn more on how to create a recurring product here at these links:

3.3 Once the recurring product has been created, view the product details page, scroll down to Payment Frequency Setting section. The Recurring Id is located under Recurring Type.

4. What parameters to send to senangPay

Below are the details of the elements in the table:

Item	Detail
order_id	This is the id to be use to identify the shopping cart when senangPay redirect back the buyer after the payment was made. The maximum length is 100 characters. Example 3432D4. Only A to Z, a to z, 1 to 0 and dash allowed.
recurring_id	This is the id to be use to identify the which recurring product/item senangPay need to process.
hash	This is the data to ensure the data integrity passed from merchant’s shopping cart to senangPay. Refer to How to generate the secure hash section for more info.
name	This is the name to populate in the payment form so that customer do not have to key in their name. This is optional and not have to be part of the hash. Customer is able to overwrite the value in payment form.
email	This is the email to populate in the payment form so that customer do not have to key in their email. This is optional and not have to be part of the hash. Customer is able to overwrite the value in payment form.
phone	This is the phone to populate in the payment form so that customer do not have to key in their phone. This is optional and not have to be part of the hash. Customer is able to overwrite the value in payment form.

5. How to send the parameters to senangPay (Live)

5.1 The parameters can be send either using GET or POST method.

5.2 The URL is : https://api.senangpay.my/recurring/payment/

followed by your merchant ID.

5.3 Example : https://api.senangpay.my/recurring/payment/14222653788472

6. How to send the parameters to senangPay (Sandbox)

6.1 The parameters can be send either using GET or POST method.

6.2 The URL is: https://api.sandbox.senangpay.my/recurring/payment/

followed by your merchant ID.

6.3 Example: https://api.sandbox.senangpay.my/recurring/payment/14222653788472

7. What Parameters does the shopping cart received from senangPay

Below are the details of the elements in the table:

Item	Detail
status_id	This is to indicate the status of the payment. It only has 2 values which is 1 for successful and 0 for failed.
order_id	This is the order that was sent to senangPay. This is to identify the transaction generated from your application.
msg	This is the message to describe the payment status. The maximum length is 100 characters. Take note that the message may contain underscore. You can replace the underscore as space when displaying the message to your customer. Example Payment_was_successful.
transaction_id	This is the transaction ID used by senangPay. You can use this ID to track the transaction in senangPay. The maximum length is 100 characters. Example 14363538840
hash	This is the data to ensure the data integrity passed from senangPay to the merchant’s shopping cart. Refer to section How to verify if the secure hash is correct for more info.

8. How senangPay send the parameters to merchant’s shopping cart

8.1 The parameters will be send using GET method.

8.2 The parameters are sent to URL as configured in the Recurring Return URL. Refer to Info required section.

9. How to generate the secure hash

9.1 The secure hash is generated by using sha256 on a string consisting of (according to sequence):

Secret Key
Recurring ID
Order ID

9.2 For example if the values for the parameters are as in PHP shown below:

?php

$secret_key = '21245-957';
$recurring_id = '1234';
$order_id = '12';

$hash = hash('sha256',$secret_key.$recurring_id.$order_id);

?>

9.3 So the string to be hash is 21245-957123412 which will generate hash values as:

a8167dd09f01ebed0b18e67b2cc2424a0d058ccc83d94803482ecdeedff7728f

10. How to verify if the secure hash is correct

10.1 Merchant will need to generate the secure hash and compare the secure hash that was received from senangPay.

10.2 For example if the parameters received from senangPay are as in PHP shown below:

<?php

$secret_key = '21245-957';
$status_id = '1';
$order_id = '12';
$transaction_id = '14363538840';
$msg = 'Payment_was_successful';

$hash = hash('sha256',$secret_key.$status_id.$order_id.$transaction_id.$msg);

?>

10.3 So the string to be hash is 21245-95711214363538840Payment_was_successful which will generate hash values as:

24354422953c29bf4b822f6783bbaf64ef445623d6e8ea4ddc1582a29c03cda0

10.4 Now you need to compare the hash value that you have generated with the hash value sent from senangPay. If the value does not match then the data may have been tampered.

11. Download sample code

For your refference, please refer to this sample code. Kindly please download from here.

B. Recurring with Amount Overwrite

1. API for Recurring Payment with Amount Overwrite

Identical to the API for recurring payment, a little tweak may enable you to use this feature of the existing API. If you have your own system and wish to integrate to senangPay for recurring payment you will need to first add your product into senangPay.The product need to be created first in order for auditing purposes. However this feature only available for recurriing subscription only. To utilize this feature, you may need to check the ‘Customer Can Overwrite Product Price’.

In this feature, no prorate will be calculated. For example, Lets say the biiling day is set on 5th with the amount of RM 10.00. If the customer prefer to pay on 1st of the month, before the 5th of the same month, the customer will be charged with full amount and same goes with the billing day.

Below are the details and steps required.

2. Info required

To start we will need the information as below. These can be retrieve in senangPay Dashboard.

2.1 Go to Menu > Settings > Profile

2.2 Refer to Shopping Cart Integration Link section. Get your Merchant ID and Secret Key information.

2.3 Then you will need to fill in the Recurring Return URL. This is the URL where senangPay will redirect the buyer after the payment has been processed.

3. Get the Recurring ID

Recurring id is the unique id to identify your recurring product. To obtain the recurring id, you must first create a recurring product in senangPay dashboard.

3.1 Go to Menu >Product > Create New

3.2 Create a recurring product. You can learn more on how to create a recurring product here at these links.

3.3 In Payment Frequency Setting Section, please check the checkbox of ‘Customer Can Overwrite Product Price’

3.4 Once the recurring product has been created, view the product details page, scroll down to Payment Frequency Setting section. The Recurring Id is located under Recurring Type.

4. What parameters to send to senangPay

Below are the details of the elements in the table:

Item	Detail
order_id	This is the id to be use to identify the shopping cart when senangPay redirect back the buyer after the payment was made. The maximum length is 100 characters. Example 3432D4. Only A to Z, a to z, 1 to 0 and dash allowed.
recurring_id	This is the id to be use to identify the which recurring product/item senangPay need to process.
hash	This is the data to ensure the data integrity passed from merchant’s shopping cart to senangPay. Refer to How to generate the secure hash section for more info.
amount	This is the amount to be used as a recurring price overwritten for the recurring product. Merchant must enable first the feature of customer to overwrite the recurring price in product creation.
name	This is the name to populate in the payment form so that customer do not have to key in their name. This is optional and not have to be part of the hash. Customer is able to overwrite the value in payment form.
email	This is the email to populate in the payment form so that customer do not have to key in their email. This is optional and not have to be part of the hash. Customer is able to overwrite the value in payment form.
phone	This is the phone to populate in the payment form so that customer do not have to key in their phone. This is optional and not have to be part of the hash. Customer is able to overwrite the value in payment form.

5. How to send the parameters to senangPay (Live)

5.1 The parameters can be send either using GET or POST method.

5.2 The URL is : https://api.senangpay.my/recurring/payment/

followed by your merchant ID.

5.3 Example: https://api.senangpay.my/recurring/payment/14222653788472

6. How to send the parameters to senangPay (Sandbox)

6.1 The parameters can be send either using GET or POST method.

6.2 The URL is: https://api.sandbox.senangpay.my/recurring/payment/

followed by your merchant ID.

6.3 Example: https://api.sandbox.senangpay.my/recurring/payment/14222653788472

7. What Parameters does the shopping cart received from senangPay

Below are the details of the elements in the table:

Item	Detail
status_id	This is to indicate the status of the payment. It only has 2 values which is 1 for successful and 0 for failed.
order_id	This is the order that was sent to senangPay. This is to identify the transaction generated from your application.
msg	This is the message to describe the payment status. The maximum length is 100 characters. Take note that the message may contain underscore. You can replace the underscore as space when displaying the message to your customer. Example Payment_was_successful.
transaction_id	This is the transaction ID used by senangPay. You can use this ID to track the transaction in senangPay. The maximum length is 100 characters. Example 14363538840
hash	This is the data to ensure the data integrity passed from senangPay to the merchant’s shopping cart. Refer to section How to verify if the secure hash is correct for more info.

8. How senangPay send the parameters to merchant’s shopping cart

8.1 The parameters will be send using GET method.

8.2 The parameters are sent to URL as configured in the Recurring Return URL. Refer to Info required section.

9. How to generate the secure hash

9.1 The secure hash is generated by using sha256 on a string consisting of (according to sequence):

Secret Key
Recurring ID
Order ID
Amount

9.2 For example if the values for the parameters are as below:

Item	Detail
Secret Key	53-784
Recurring ID	155243673654
Order ID	56
Amount	3.30

9.3 Request parameter for md5 :

<?php

   $secret_key = '53-784';
   $recurring_id = '155243673654';
   $order_id = '56';
   $amount = '3.30';

    $hash = hash('sha256',$secret_key.$recurring_id.$order_id.$amount);

?>

10. How to verify if the secure hash is correct

10.1 Merchant will need to generate the secure hash and compare the secure hash that was received from senangPay.

10.2 For example if the parameters received from senangPay are as below:

Item	Detail
status_id	1
order_id	56
transaction_id	14363538840
msg	Payment_was_successful

10.3 Verify the hash:

<?php

   $secret_key = '53-784';
   $status_id = '1';
   $order_id = '56';
   $transaction_id = '14363538840';
   $msg = 'Payment_was_successful';

     $hash = hash('sha256',$secret_key.$status_id.$order_id.$transaction_id.$msg);

?>

10.3 Now you need to compare the hash value that you have generated with the hash value sent from senangPay. If the value does not match then the data may have been tampered.

11. Download sample code

For your reference, please refer to this sample code. Kindly please download from here.

C. Advance Recurring Callback

Advance Recurring Callback enables merchant to receive detailed recurring callback data in JSON format. The normal callback setup will send a standard HTTP POST data to merchant.

1. How to enable the feature

1.1 Login into your senangPay dashboard

1.2 Go to Menu > Setting > Profile

1.3 Scroll down to the Shopping Cart Integration Link section.

1.4 Under the Recurring Callback URL input field, you will se a checkbox to enable the advance callback setting.

1.5 Tick the checkbox to allow senangPay to send the recurring callback data in JSON format. Untick to receive the standard callback data format.

2. The JSON structure

Once you enabled the advance callback feature, all your recurring callback will be sent in JSON with below data.

recurring_id	The ID of your recurring payment.
status_id	This is to indicate the status of the payment. It only has 2 values which is; 1 for successful and 0 for failed.
order_id	This is the order that was sent to senangPay. This is to identify the shopping cart transaction.
transaction_id	This is the transaction ID used by senangPay. You can use this ID to track the transaction in senangPay
msg	This is the message to describe the payment status. The maximum length is 100 characters. Take note that the message may contain underscore. You can replace the underscore as space when displaying the message to your customer. Example: Payment_was_successful.
hash	This is the data to ensure the data integrity passed from senangPay to the merchant’s shopping cart.
next_payment_date	Next payment date in UNIX timestamp.
payment_details	JSON array of payment schedule for recurring instalment, and payment history for recurring subscription.

{
"recurring_id": "153352642441",
"status_id": 1,
"order_id": "1534310077",
"transaction_id": "15343102725546",
"msg": "Payment_was_successful",
"hash": "e2815159403f49a6c366f6fdc1552efdfdf5b377d7a8086fc44816c16a30a69b",
"next_payment_date": 1536854400,
"payment_details": [
    {
       "payment_date": "15\/08\/2018",
       "payment_date_timestamp": "1534262400",
       "payment_status": "paid",
       "payment_transaction_reference": "15343102725546"
    },
    {
       "payment_date": "14\/09\/2018",
       "payment_date_timestamp": "1536584400",
       "payment_status": "pending payment",
       "payment_transaction_reference": ""
    },
{
       "payment_date": "15\/10\/2018",
       "payment_date_timestamp": "1539532800",
       "payment_status": "pending payment",
       "payment_transaction_reference": ""
    },
{
       "payment_date": "14\/11\/2018",
       "payment_date_timestamp": "1542124800",
       "payment_status": "pending payment",
       "payment_transaction_reference": ""
    },
{
       "payment_date": "15\/12\/2018",
       "payment_date_timestamp": "1544803200",
       "payment_status": "pending payment",
       "payment_transaction_reference": ""
    },
{
       "payment_date": "15\/01\/2019": "154”7481600",
       "payment_status": "pending payment",
       "payment_transaction_reference": ""
    },
  ]
}

3. What if I have Return URL parameters set?

3.1 If you have custom return URL parameters, the JSON will follow the key and value set in your return URL parameters.

3.2 For example, if you have set the custom parameters as below, the JSON object will become as below:

Return URL Parameters:

?order_id=[ORDER_ID]&message=”[MSG]&status=”[TXN_STATUS]&amount=[AMOUNT]&ref_id=[TXN_REF]&signature=[HASH]

{
"order_id": "153352642441",
"message": "Your_payment_was_declined._Please_check_with_your_bank._Thank_you.",
"status": "0",
"amount": "2.00",
"ref_id": "153427543966023494",
"signature": "a90ac337e4785fc96f6e2ce623bc6274da46f1f158583e6fbc509e5f13e6bb274",
"recurring_id": "151997523298",
"next_payment_date": 0
"payment_details": {
     "payments": [

    {
       "payment_date": "15\/08\/2018",
       "payment_date_timestamp": "1534262400",
       "payment_status": "failed",
       "payment_transaction_reference": "153427543966023494"
    },
    {
       "payment_date": "14\/09\/2018",
       "payment_date_timestamp": "1536584400",
       "payment_status": "pending payment",
       "payment_transaction_reference": ""
    }
  ]
"next_payment_date": "1536854400"
  }
}

4. Parameters to send and generating the hash

Nothing is changed with the steps mentioned in our recurring API here. Enabled the advance recurring callback feature will only reflect the way senangPay send callback to your system.

D. Split Settlement Manual Integration

If you have develop your own shopping cart and need split settlement manual integration by yourself, here are the details.

The API allows you to split the settlement for the transaction to multiple merchant instead of only 2 when using split settlement product.

1. Info Required

To start we will need the information as below. These can be retrieve in senangPay Dashboard.

1.1 Go to Menu > Settings > Profile

1.2 Refer to Shopping Cart Integration Link section. Get your Merchant ID and Secret Key information.

1.3 Then you will need to fill in the return URL. This is the URL where senangPay will redirect the buyer after the payment has been processed. If you already had set the return URL for your manual integration API, then you can skip this step.

1.4 Next, you need to fill the Callback URL. Callback URL is used as alternative notification to merchant shopping cart in case there is a breakdown in transaction flow. For more info on Callback URL, read here.

1.5 If you already had set the Callback URL for your manual integration API, then you can skip this step.

2.What parameters to send to senangPay

Below are the details of the elements in the table :

Item	Details
detail	This is the description to be displayed when making the payment. The maximum length is 500 characters. Any underscore (_) characters will be converted to space. Example Shopping_cart_id_30. Only A to Z, a to z, 1 to 0, dot, comma, dash and underscore allowed
amount	The amount to charge the buyer. The format must be in 2 decimal places. Example 25.50.
order_id	This is the id to be use to identify the shopping cart when senangPay redirect back the buyer after the payment was made. The maximum length is 100 characters. Example 3432D4. Only A to Z, a to z, 1 to 0 and dash allowed.
hash	The is the data to ensure the data integrity passed from merchant’s shopping cart to senangPay. Refer to How to generate the secure hash section for more info.
name	This is the name to populate in the payment form so that customer do not have to key in their name. This is optional and not have to be part of the hash. Customer is able to overwrite the value in payment form.
email	This is the email to populate in the payment form so that customer do not have to key in their email. This is optional and not have to be part of the hash. Customer is able to overwrite the value in payment form.
phone	This is the phone to populate in the payment form so that customer do not have to key in their phone. This is optional and not have to be part of the hash. Customer is able to overwrite the value in payment form.
split_settlement	This is a string containing the split settlement information. The string should follow below format.

2.1 Example
Total amount: RM10

The split_amount should be the split amount multiply by hundred, not in percentage.
Merchant can split the total amount to unlimited merchant account, as long as each merchant account (including owner) amount is RM 2 or more.
Merchant ID must be ID of active senangPay account.
No space or symbol allowed.
In the example above:
- Merchant (transaction owner) will be allocated RM3 from the transaction.
- Merchant 1544436524 will be allocated RM2 from the transaction.
- Merchant 1677765432 will be allocated RM3 from the transaction.
- Merchant 1766653212 will be allocated RM2 from the transaction.

3. How to send the parameters to senangPay

3.1 The parameters can be send either using GET or POST method.

3.2 The URL is: https://app.senangpay.my/payment/

followed by your merchant ID.

3. Example: https://app.senangpay.my/payment/14222653788472

4. What Parameters does the shopping cart received from senangPay

Item	Details
status_id	This is to indicate the status of the payment. It only has 2 values which is 1 for successful and 0 for failed.
order_id	This is the order that was sent to senangPay. This is to identify the shopping cart transaction.
msg	This is the message to describe the payment status. The maximum length is 100 characters. Take note that the message may contain underscore. You can replace the underscore as space when displaying the message to your customer. Example Payment_was_successful.
transaction_id	This is the transaction ID used by senangPay. You can use this ID to track the transaction in senangPay. The maximum length is 100 characters. Example 14363538840
hash	This is the data to ensure the data integrity passed from senangPay to the merchant’s shopping cart. Refer to section How to verify if the secure hash is correct for more info.

5. How senangPay send the parameters to merchant’s shopping cart

5.1 The parameters will be send using GET method.

5.2 The parameters are sent to URL as configured in the return URL. Refer to Info required section.

6. How to generate the secure hash

6.1 The secure hash is generated by using HMAC hashing algorithm with SHA256 or md5 on a string consisting of (according to sequence):

6.2 So the string to be hash is

$str = 53-784Shopping_cart_id_5610.00561544436524:200|1677765432:300|1766653212:200

which will generate hash value as :

md5($str) => 0284ce49406276a9e85dad1e820fb24c
hash_hmac(‘SHA256′, $str, ’53-784’) => 6058877a0405e9fa94d89a5568566462840e64781d9518d75c21570caa156bc2

7.3 For your reference, please refer to this sample code

7. How to verify if the secure hash is correct

7.1 Merchant will need to generate the secure hash and compare the secure hash that was received from senangPay.

7.2 For example if the parameters received from senangPay are as below:

Item	Details
status_id	1
order_id	56
transaction_id	14363538840
msg	Payment_was_successful

3. So the string to be hash is

53-78415614363538840Payment_was_successful

which will generate hash value as :

69686562c29ad3f7955b1843a5c275ca.

7.4 Now you need to compare the hash value that you have generated with the hash value sent from senangPay. If the value does not match then the data may have been tampered.

8. Can I just add split settlement parameter in my existing manual integration API setup?

Yes. You can enable split settlement by adding the split_settlement parameter, and include the parameter in your hash.

9. Download sample code

For your reference, please refer to this sample code. Kindly please download from here.

E. Manual Integration API (Open API)

If you have develop your own shopping cart and need manual integration by yourself, here are the details.

1. Info required

To start we will need the information as below. These can be retrieve in senangPay Dashboard.

1.1 Go to Menu > Settings > Profile

1.2 Refer to Shopping Cart Integration Link section. Get your Merchant ID and Secret Key information.

1.3 Then you will need to fill in the return URL. This is the URL where senangPay will redirect the buyer after the payment has been processed.

1.4 Next, you need to fill the Callback URL. Callback URL is used as alternative notification to merchant shopping cart in case there is a breakdown in transaction flow. For more info on Callback URL, read here

2. What parameters to send to senangPay

Below are the details of the elements in the table :

Item	Detail
detail	This is the description to be displayed when making the payment. The maximum length is 500 characters. Any underscore (_) characters will be converted to space. Example Shopping_cart_id_30. Only A to Z, a to z, 1 to 0, dot, comma, dash and underscore allowed.
amount	The amount to charge the buyer. The format must be in 2 decimal places. Example 25.50.
order_id	This is the id to be use to identify the shopping cart when senangPay redirect back the buyer after the payment was made. The maximum length is 100 characters. Example 3432D4. Only A to Z, a to z, 1 to 0 and dash allowed.
hash	The is the data to ensure the data integrity passed from merchant’s shopping cart to senangPay. Refer to How to generate the secure hash section for more info.
name	This is the name to populate in the payment form so that customer do not have to key in their name. This is optional and not have to be part of the hash. Customer is able to overwrite the value in payment form.
email	This is the email to populate in the payment form so that customer do not have to key in their email. This is optional and not have to be part of the hash. Customer is able to overwrite the value in payment form.
phone	This is the phone to populate in the payment form so that customer do not have to key in their phone. This is optional and not have to be part of the hash. Customer is able to overwrite the value in payment form.

3. How to send the parameters to senangPay (Live)

3.1 The parameters can be send either using GET or POST method.

3.2 The URL is: https://app.senangpay.my/payment/

followed by your merchant ID.

3.3 Example: https://app.senangpay.my/payment/14222653788472

4. How to send the parameters to senangPay (Sandbox)

4.1 The parameters can be send either using GET or POST method.

4.2 The URL is: https://sandbox.senangpay.my/payment/

followed by your merchant ID.

4.3 Example: https://sandbox.senangpay.my/payment/14222653788472

5. What Parameters does the shopping cart received from senangPay

Below are the details of the elements in the table :

Item	Detail
status_id	This is to indicate the status of the payment. It only has 2 values which is 1 for successful and 0 for failed.
order_id	This is the order that was sent to senangPay. This is to identify the shopping cart transaction.
msg	This is the message to describe the payment status. The maximum length is 100 characters. Take note that the message may contain underscore. You can replace the underscore as space when displaying the message to your customer. Example Payment_was_successful.
transaction_id	This is the transaction ID used by senangPay. You can use this ID to track the transaction in senangPay. The maximum length is 100 characters. Example 14363538840
hash	This is the data to ensure the data integrity passed from senangPay to the merchant’s shopping cart. Refer to section How to verify if the secure hash is correct for more info.

6. How senangPay send the parameters to merchant’s shopping cart

6.1 The parameters will be send using GET method.

6.2 The parameters are sent to URL as configured in the return URL. Refer to Info required section.

7. How to generate the secure hash

7.1 The secure hash is generated by using HMAC hashing algorithm with SHA256 or md5 on a string consisting of (according to sequence):

Secret Key
Detail
Amount
Order ID

7.2 For example if the values for the parameters are as below:

Item	Detail
Secret Key	53-784
Detail	Shopping_cart_id_30
Amount	24.50
Order ID	56

7.3 So the string to be hash is

$str = 53-784Shopping_cart_id_3024.5056

which will generate hash value as :

md5($str) => 0bde51ff340f110ab7331a902aa969e7

hash_hmac(‘SHA256′, $str, ’53-784’) => 74422328b44d30bf150fffbae89bbb42b885f9ac0960e2a3ddccc0cf9aa48e39

8. How to verify if the secure hash is correct

8.1 Merchant will need to generate the secure hash and compare the secure hash that was received from senangPay.

8.2 For example if the parameters received from senangPay are as below:

Item	Detail
status_id	1
order_id	56
transaction_id	14363538840
msg	Payment_was_successful

8.3 So the string to be hash is

$str = 53-78415614363538840Payment_was_successful

which will generate hash value as :

md5($str) => 69686562c29ad3f7955b1843a5c275ca
hash_hmac(‘SHA256′, $str, ’53-784’) => 4ca7837c6c4ddb5f6ba573ea701235b2d04bc6400d32787539e07aaf319eb70f

8.4 Now you need to compare the hash value that you have generated with the hash value sent from senangPay. If the value does not match then the data may have been tampered.

9. Download sample code

For your refference, please refer to this sample code. Kindly please download from here.

F. Callback URL

1. Support

Please take note that the Callback function is only applicable to integration using shopping cart method. The Callback for WooCommerce and OpenCart is now available.

2. Purpose

Callback URL is used as alternative notification to merchant shopping cart in case there is a breakdown in transaction flow. This function is only applicable if merchant is using shopping cart method for integration with senangPay. This is optional so merchant can opt not to use this feature. However this feature is recommended for merchant that is using shopping cart method for integration to ensure data integrity between merchant’s system and senangPay.

3. Understanding breakdown in transaction flow

3.1 When a customer is doing a transaction using shopping cart, the customer will be redirected a few times to different system.

3.2 If the transaction has been approved by the bank but the customer encountered problem such as internet connection issue, there is a possibility that either:

senangPay is updated with the correct transaction status but merchant online store does not.
Both senangPay and merchant online store is not updated with the correct transaction status.

4. Solution when there is a breakdown in transaction flow

4.1 For every transaction, it will go through a verification process in senangPay. Every transactions will go through this process 30 minutes to 1 hour after the transaction is initiated. This buffer 30 minutes to 1 hour is to make sure that the transaction has been completed and the status is final in Visa/Mastercard/FPX.

4.2 In case of a transaction breakdown where senangPay and merchant online store is not updated with the latest status, once the verification process has done and senangPay has been updated with the latest status, senangPay will do a callback to merchant online store and send the latest status.

4.3 In case of a transaction breakdown where senangPay is updated with the latest status but merchant online store does not, senangPay will do a callback immediately once the transaction is completed in senangPay.

4.4 If there is no breakdown in transaction senangPay will still do a callback to merchant online store once the transaction is completed in senangPay.

5. Parameters

6. Callback failure

6.1 If merchant has configured the URL for callback but senangPay is unable to connect to the URL or the URL did not return ‘OK’, senangPay will send an email to merchant.

6.2 Merchant must fix the issue and update their system with the correct status for the transaction.

6.3 If you do not want any failure email notification please set callback response as ‘Ignore the response’. (refer to next section for location to set this). Take note that the callback URL must not be using session.

6.4 Please avoid using redirection for callback URL. This might lead to HTTP status 302.

7. Method

senangPay will send the data to callback URL using HTTP POST method.

8. Callback Frequency

8.1 The frequency varies depending on the situation. If the transaction is still pending, senangPay will start sending callback 5 minutes after the transaction started. senangPay will send the callback real time once it receive any status update from the banks.

8.2 The last callback will be 1 hour after the transaction started. This means you will receive multiple callbacks for the transactions.

8.3 It is also possible to receive a failed status followed by successful status. This is due to the transaction is still not complete when senangPay make the initial query (for the status) with the banks.

8.4 The last callback will carry the final status of the transaction.

9. Where to set Callback URL ?

9.1 Go to Menu > Settings > Profile

9.2 Scroll down the page and you will see the setting fields on Shopping Cart Integration Link section

G. Return URL Parameters

1. Support

1.1 Please take note that the return URL parameters only required if you are using a system that require a return parameters that is different compared to default parameters sent by senangPay.

1.2 For the list of default parameters sent by senangPay please refer here.

1.3 If your system is able to use the default parameters sent by senangPay then please leave the Return URL Parameters empty.

1.4 For users of senangPay WooCommerce and OpenCart plugin please leave the field empty.

2. Purpose

2.1 Some system requires a fixed parameters sent to them in order to integrate.

2.2 So in this case senangPay provide a way for merchant to specify the parameters that they would like to receive from senangPay.

2.3 The return URL parameters are also applied to callback URL.

3. What parameters are available

3.1 Below are the list of parameters that senangPay supported

Placeholder	Detail
[NAME]	This is the name of the payer as keyed in by the payer.
[EMAIL]	The email of the payer as keyed in by the payer.
[PHONE]	The phone number of the payer as keyed in by the payer.
[AMOUNT]	The paid amount.
[TXN_STATUS]	Transaction status, value 1 for successful and 0 for failed.
[ORDER_ID]	The order id as sent by third party system to identify the transaction.
[TXN_REF]	The transaction reference number as generated by senangPay to uniquely identify the transaction.
[MSG]	Message to describe the status of the transaction.
[HASH]	Hashed value of the parameters using MD5.
[TXN_TYPE]	The payment method either FPX or credit / debit card.

4. How to check the hashed value sent by senangPay

4.1 The hashed value is based on the return URL parameters string (appended with merchant secret key) with the value except for the hash.

4.2 Each parameter values need to be urlencoded.

5. Example

5.1 For example if your system require parameters name as below:

email, example value “[email protected]”
amount_paid, example value “10.50”
txn_status, example value “1”
txn_msg, example value “Payment was successful”
order_id, example value “A5463”
hashed_value

5.2 Your merchant secret key is 123-456.

5.3 So you can key in the string below in the return URL parameters field.

?email=[EMAIL]&amount_paid=[AMOUNT]&txn_status=[TXN_STATUS]&txn_msg=[MSG]&order_id=[ORDER_ID]&hashed_value=[HASH]

4. To calculate the hash to verify the data you will need to md5 the string as below :

md5(123-456?email=john%40gmail.com&amount_paid=10.50&txn_status=1&txn_msg=Payment+was+successful&order_id=A5463&hashed_value=[HASH]);

which will generate the hashed value 8e4d29818759e4069a635affdfc2572b.

Generate the hash using HMAC hashing algorithm with SHA256.

hash_hmac(‘SHA256’, ‘123-456?email=john%40gmail.com&amount_paid=10.50&txn_status=1&txn_msg=Payment+was+successful&order_id=A5463&hashed_value=[HASH]’, ‘123-456’);

which will generate the hashed value 64c54bb8c1f1955ef6f4a8fc3d9f810d1490239d7e5dda82f030c2da6b99f0f6 .

H. Merchant ID & Secret Key

Some integration from shopping cart or system require Merchant ID & Secret Key. This is to ensure a secured connection between two party and everybody knows to talk to everybody.

1. How can I get my Merchant ID & Secret Key ?

1.1 Login to you dashboard.

1.2 Go to Menu > Settings > Profile

1.3 A page of profile will appears. Scroll down a little bit until you see Shopping Integration Link .

1.4 Refer to the field “Merchant ID” and “Secret Key”

1.5 Secret key can be re-generated

I. Mobile Integration for app like iOS & Android App

1. Can senangPay be integrated with mobile apps?

Yes.

2. So can I have the SDK of iOS or Android to begin with

No, unfortunately we are sorry. Currently we don’t have the SDK yet.

3. What is web view?

A “webview” is a browser bundled inside of a mobile application producing what is called a hybrid app. Using a webview allows mobile apps to be built using Web technologies (HTML, JavaScript, CSS, etc.) but still package it as a native app and put it in the app store.

4. So then how can we integrate with mobile apps then?

You can use web view to deploy the payment part.

5. That would be not really seamless with my apps

Yes we agreed, but as for time being, this is how we need to live with.

6. Do senangPay plan to have the SDK in future

Yes we have that plan.

7. May I know when?

It’s complicated.

8. Can I help senangPay to create the SDK?

May we have your number please?