Setup and Integration
Merchant Hosted
A. 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.
B. Basic Info
To start, we will need the information as below. These can be retrieve from senangPay dashboard.
1. Go to Menu > Settings > Profile
2. Refer to Shopping Cart Integration Link section. Get your Merchant ID and Secret Key information.
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.
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.
C. 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 |
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 the credit card expiry month |
cc_expiry_year | This is the credit card expiry year |
cc_ccv | This is the credit card ccv |
D. How to send the parameters to senangPay
1. The parameters can be send either using GET or POST method.
2. The URL is:
https://app.senangpay.my/payment/merchant-hosted/
followed by your merchant id
3. Example:
https://app.senangpay.my/payment/merchant-hosted/14222653788472
E. 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. |
F. How senangPay send the parameters to merchant’s shopping cart
1. The parameters will be send using GET method.
2. The parameters are sent to URL as configured in the return URL Refer to Info required section
G. How to generate the secure Hash
1. The secure hash is generated by using md5 on a string consisting of (according to sequence):
- Secret Key
- Detail
- Amount
- Order ID
- Name
- Phone Number
- Credit Card Name
- Credit Card Number
- Credit Card Expiry Month
- Credit Card Expiry Year
- Credit Card CCV
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 |
abu@gmail.com | |
phone | 0123456789 |
cc_name | abu |
cc_number | 5111111111111118 |
cc_expiry_month | 05 |
cc_expiry_year | 21 |
cc_ccv | 101 |
hash | 3084c95c47660e2066c40961ed333519 |
<?php
$secret_key = '2-340';
$detail = 'Shopping_cart_id_30';
$amount = '25.50';
$order_id = '56';
$name = 'abu';
$email = 'abu@gmail.com';
$phone = '0123456789';
$cc_name = 'abu';
$cc_number = '5111111111111118';
$cc_expiry_month = '05';
$cc_expiry_year = '21';
$cc_ccv = '101';
$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 :
- 33c02a4e7f281d1ec16aff599e307040
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 = 'abu@gmail.com';
$phone = '0123456789';
$cc_name = 'abu';
$cc_number = '5111111111111118';
$cc_expiry_month = '05';
$cc_expiry_year = '21';
$cc_ccv = '101';
$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 :
- 052caf0f548d8cf654d1436bb9f98375d424b0a044ea36f20d5fc1e4f98abeff
H. How to verify if the secure hash is correct
1. Merchant will need to generate the secure hash and compare the secure hash that was received from senangPay.
2. For example, if the parameters received from senangPay are as below:
Item | Detail |
---|---|
secret_key | 2-340 |
status_id | 1 |
order_id | 56 |
transaction_id | 14363538840 |
msg | Payment_was_successful |
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
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.