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.

Screen Shot 2015-04-09 at 1.17.01 PM

Query Order Status

 

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

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

Method: GET

Parameters:

  • merchant_id
  • order_id
  • hash

Return format: JSON

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

  • merchant_id
  • secret key
  • order_id

Then please use md5 to hash the string.

Screen Shot 2015-04-09 at 1.17.01 PM

Query Transaction Status

 

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

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

 

Method: GET

Parameters:

  • merchant_id
  • order_id
  • hash

Return format: JSON

 

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

  • merchant_id
  • secret key
  • order_id

Then please use md5 to hash the string.

Screen Shot 2015-04-09 at 1.17.01 PM

Get Transaction List

 

This is to retrieve transaction result for a specific transaction reference

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

Method: GET

Parameters:

  • merchant_id
  • timestamp_start
  • timestamp_end
  • hash

Return format: JSON

 

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

Then please use md5 to hash the string.

 

The value of timestamps must be more than 0 and the end timestamp must be more than start timestamp. Timestamps refer to UNIX timestamp.

Screen Shot 2015-04-09 at 1.17.01 PM

API Endpoint for MOTO Transcation

 

Creating MOTO Payment

ItemDetail
API Endpointhttp://app.senangpay.my/apiv1/pay_cc

Authorization header

TypeBasic
Username< your-merchant-id >
As listed in the profile settings page.
PasswordNone, leave empty.

Request Paramater (all is mandatory)

Parameter NameParameter value/description
order_idYour order id. Can be number or string. Other character is invalid.
Eg. 1234
nameYour customer name. Maximum length is 100.
Eg. Abu Bin Ali
phoneYour customer phone number.
Eg. 0109876543
emailYour customer email.
Eg. ahmad@google.com
detailYour order detail. Maximum length is 100.
Eg. Order for product id #4
amountYour order amount in integer format. Convert from decimals as necessary.
Eg. if the amount is RM 2.00, you need to send 200.
cc_numberYour customer credit card number.
cc_expYour customer credit card expiration date in MMYY format.
Eg. if the card expires on January 2017, you need to send 0117
cc_cvvYour 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

Response Parameter

Parameter NameParameter value / description
statusYour transaction status. 1 if success. 0 if failed.
transaction_idYour transaction ID number.
order_idYour original order ID.
amount_paidAmount transacted from the credit card in integer format.
Eg. if the amount transacted is RM 2.00, it will output 200.
msgTransaction 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

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.

ItemDetail
API endpointhttp://app.senangpay.my/apiv1/order/

Authorization Header

TypeBasic
Username< your-merchant-id >
As listed in the profile settings page.
PasswordNone, leave empty.

URL Parameter

Parameter NameParameter value/description
order_idYour order id. Can be number or string. Other character is invalid.
Eg. 1234

Response Parameter

Parameter NameParameter value / description
statusYour transaction status. 1 if success. 0 if failed.
msgQuery 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

 

 

 

 

 

 

 

 

 

 

 

 

Get MOTO Payment Details By Transaction Reference

ItemDetail
API endpointhttp://app.senangpay.my/apiv1/order/

Authorization header

TypeBasic
Username< your-merchant-id >
As listed in the profile settings page.
PasswordNone, leave empty.

URL Parameter

 

Parameter NameParameter value / description
transaction_referenceThe transaction reference number to check.

Response Parameter

Parameter NameParameter value/description
statusYour transaction status. 1 if success. 0 if failed.
msgQuery 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

MOTO Data Transaction Response

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

Response Parameter

KeyValue details / description
transaction_referenceThe 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

 

Example Request

curl https://app.senangpay.my/apiv1/pay_cc -u 123456789012345: \
 -d 'name= Abu Bin Ali' \
 -d email=abu@google.com \
 -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

Sample Response

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

Example Request

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

Sample Response

{
"status":1
"msg":"Query was successful",
"data":[{
  "transaction_reference": "14951839358320",
  "buyer_contact": {
  "name": "Abu Bin Ali ",
  "email": "abu@gmail.com",
  "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": "abu@gmail.com",
  "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"
 }

Example Request

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

Sample Response

{
"status":1
"msg":"Query was successful",
"data":{
  "transaction_reference": "14951839358320",
  "buyer_contact": {
  "name": "Abu Bin Ali ",
  "email": "abu@gmail.com",
  "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

Please be informed the 2D get token will be deprecated on 31st December 2019.

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

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

API list

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)

 

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

Authorization Header (Basic Auth)

 

TypeBasic
Username< your-merchant-id >
As listed in the profile settings page.
PasswordNone, leave empty.

Request Parameter (all is mandatory)

 

Parameter NameParameter value/description
nameYour customer name. Maximum length is 100.
Eg. Abu Bin Ali
emailYour customer email.
Eg. ahmad@google.com
phoneYour customer phone number.
Eg. 0109876543
cc_numberYour customer credit card number.
cc_expYour customer credit card expiration date in MMYY format.
Eg. if the card expires on January 2017, you need to send 0117
cc_cvvYour customer credit card CVV number.
Eg. 123

Response Parameter

 

Parameter NameParameter value / description
statusYour transaction status. 1 if success. 0 if failed.
tokenIf card validation succeed, token will be generated. The token will be used for future payment on the card.
msgCard 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.
 

Pay credit card using token

 

 

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

Authorization Header (Basic Auth)

 

 

TypeBasic
Username< your-merchant-id >
As listed in the profile settings page.
PasswordNone, leave empty.

Request Parameter (All Mandatory)

 

 

Parameter NameParameter value/description
nameYour customer name. Maximum length is 100.
Eg. Abu Bin Ali
emailYour customer email.
Eg. ahmad@google.com
detailYour order detail. Maximum length is 100. Eg. Order for product id #4
phoneYour customer phone number.
Eg. 0109876543
order idYour order id. Can be number or string. Other character is invalid. Eg. 123 
amountYour order amount in integer format. Convert from decimals as necessary.
Eg. if the amount is RM 2.00, you need to send 200.
tokenGenerated token from Get Token API 
hashA 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

Response Parameter

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

Enable/disable credit card

 

 

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

Authorization header (Basic Auth)

 

 

TypeBasic
Username< your-merchant-id >
As listed in the profile settings page.
PasswordNone, leave empty.

Request Parameter (All Mandatory)

 

 

 

Parameter NameParameter value / description
tokenGenerated token from Get Token API

Response Parameter

 

 

Parameter NameParameter value/description
msgMessage for the token is successfully disabled or enabled.
tokenGenerated token from Get Token API that has been disabled or enabled.

Validate payment token

 

 

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

Authorization header (Basic Auth)

 

 

TypeBasic
Username< your-merchant-id >
As listed in the profile settings page.
PasswordNone, leave empty.

Request Parameter (All Mandatory)

 

 

 

Parameter NameParameter value / description
tokenGenerated token from Get Token API

Response Parameter

 

 

Parameter NameParameter value/description
statusToken validation status. 1 if success. 0 if failed.
msgToken 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.
tokenGenerated 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.

Screen Shot 2015-04-09 at 1.17.01 PM

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)

 

ItemDetails
order_idThis is for your system to track the request response. It can be anything.
nameYour customer name. Maximum length is 100.
Eg. Micheal Solomon
emailYour customer email.
Eg. micheal@theboringcompany.com
phoneYour 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

 

 

 

ItemDetails
statusToken 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

Screen Shot 2015-04-09 at 1.17.01 PM

What is Merchant Hosted?

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.
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.
 
  •  
Go to Settings > Profile
  • Refer to Shopping Cart Integration Link section. Get your Merchant ID and Secret Key information.
 
  • 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. This is mandatory.
  • 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]
ItemDetail
detailThis 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.
amountThe amount to charge the buyer. The format must be in 2 decimal places.
Example: 25.50
order_idThis 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.
hashThis 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.
nameThis is the name of the customer that perform the payment
emailThis is the email of the customer that perform the payment. Transaction confirmation email will be sent to this email.
phoneThis is the phone number of the customer that perform the payment.
cc_nameThis is the credit card holder name
cc_numberthis is the credit card number.
cc_expiry_month 
cc_expiry_yearThis os the credit card expiry year
cc_ccvThis is the credit card ccv

3. How to send the parameters to senangPay

  • The parameters can be send either using GET or POST method.
  • The URL is https://app.senangpay.my/payment/merchant-hosted/ followed by your merchant idExample: 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.

 

 

ItemDetail
status_idThis is to indicate the status of the payment. It only has 2 values which is 1 for successful and 0 for failed.
order_idThis is the the order that was sent to senangPay. This is to identify the shopping cart transaction.
msgThis 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_idThis 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.
hashThis 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

  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

6. How to generate the secure Hash

  1. The secure hash is generated bu using md5 on a string consisting of (according to sequence):
    1. Secret Key
    2. Detail
    3. Amount
    4. Order ID
    5. Name
    6. Email
    7. Phone Number
    8. Credit Card Name
    9. Credit Card Number
    10. Credit Card Expiry Month
    11. Credit Card Expiry Year
    12. Credit Card CCV
  2. For example, if the values for the parameters are as below:

     

    ItemDetail
    secret key2-340
    detailShopping_cart_id_30
    amount25.50
    order_id56
    nameabu
    emailabu@gmail.com
    phone0123456789
    cc_nameabu
    cc_number5111111111111118
    cc_expiry_month05
    cc_expiry_year21
    cc_ccv101
    hash3084c95c47660e2066c40961ed333519
  3. So the string to be hash is 2-340Shopping_cart_id_3024.5056abuahmad@google.com0109876543abu51111111111111180521100 which will generate hash value as 3084c95c47660e2066c40961ed333519

7. 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:
    ItemDetail
    status_id1
    order_id56
    transaction_id14363538840
    msgPayment_was_successful
  3. So the string to be hash is 2-34015614363538840Payment_was_successful which will generate hash value as 49197d877cb4fa7bd770134506b7fb0a.
  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 data may have been tempered.

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)

 

ItemDetails
order_idThis is for your system to track the request response. It can be anything.
nameYour customer name. Maximum length is 100.
Eg. Micheal Solomon
emailYour customer email.
Eg. micheal@theboringcompany.com
phoneYour 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

 

 

 

ItemDetails
statusToken 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

Screen Shot 2015-04-09 at 1.17.01 PM

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.
137x22xspace.png.pagespeed.ic.IoAxAisfVW

Info required

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

1. Go to Settings > Profile

Settings

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

ShoppingCart

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.

4. Next, you need to fill the Recurring Callback URLRecurring 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

CallbackURL

137x22xspace.png.pagespeed.ic.IoAxAisfVW
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.

1. Go to Product > Create New

GetRecID

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

a. Instalment Product
b. Subscription Product

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.

RecType

137x22xspace.png.pagespeed.ic.IoAxAisfVW
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.

137x22xspace.png.pagespeed.ic.IoAxAisfVW
How to send the parameters to senangPay (Live)

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

2. The URL is https://api.senangpay.my/recurring/payment/ followed by your merchant ID.

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

How to send the parameters to senangPay (Sandbox)

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

2. The URL is https://api.sandbox.senangpay.my/recurring/payment/ followed by your merchant ID.

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

137x22xspace.png.pagespeed.ic.IoAxAisfVW
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.

137x22xspace.png.pagespeed.ic.IoAxAisfVW
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 Recurring Return URL. Refer to Info required section.

137x22xspace.png.pagespeed.ic.IoAxAisfVW
How to generate the secure hash

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

– Secret Key

– Recurring ID

– Order ID

2. For example if the values for the parameters are as below:

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

3. So the string to be hash is 53-78415524367365456 which will generate hash value as 50c1200b541147356be1c5095bfddb8cc8a222a9171005ad5bd3b2db28277a14

137x22xspace.png.pagespeed.ic.IoAxAisfVW
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
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 0ebfcaab4be7463a67d605aad312a03cd6b41df4e3560c2a192b84baab15d127

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.

137x22xspace.png.pagespeed.ic.IoAxAisfVW
Download sample code

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

Screen Shot 2015-04-09 at 1.17.01 PM

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.

137x22xspace.png.pagespeed.ic.IoAxAisfVW

Info required

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

1. Go to Settings > Profile

Settings

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

ShoppingCart

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.

4. Next, you need to fill the Recurring Callback URLRecurring 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

CallbackURL

137x22xspace.png.pagespeed.ic.IoAxAisfVW
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.

1. Go to Product > Create New

GetRecID

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

a. Instalment Product
b. Subscription Product

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

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.

RecType

137x22xspace.png.pagespeed.ic.IoAxAisfVW
What parameters to send to senangPay

Below are the details of the elements in the table:

 

ItemDetail
order_idThis 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_idThis is the id to be use to identify the which recurring product/item senangPay need to process.
hashThis 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.
amountThis 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.
nameThis 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.
emailThis 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.
phoneThis 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.

137x22xspace.png.pagespeed.ic.IoAxAisfVW
How to send the parameters to senangPay (Live)

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

2. The URL is https://api.senangpay.my/recurring/payment/ followed by your merchant ID.

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

How to send the parameters to senangPay (Sandbox)

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

2. The URL is https://api.sandbox.senangpay.my/recurring/payment/ followed by your merchant ID.

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

137x22xspace.png.pagespeed.ic.IoAxAisfVW
What Parameters does the shopping cart received from senangPay

Below are the details of the elements in the table:

 

ItemDetail
status_idThis is to indicate the status of the payment. It only has 2 values which is 1 for successful and 0 for failed.
order_idThis is the order that was sent to senangPay. This is to identify the transaction generated from your application.
msgThis 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_idThis 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
hashThis 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.

137x22xspace.png.pagespeed.ic.IoAxAisfVW
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 Recurring Return URL. Refer to Info required section.

137x22xspace.png.pagespeed.ic.IoAxAisfVW
How to generate the secure hash

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

  • Secret Key
  • Recurring ID
  • Order ID
  • Amount

2. For example if the values for the parameters are as below:

 

ItemDetail
Secret Key53-784
Recurring ID155243673654
Order ID56
Amount3.30

3. So the string to be hash is 53-78415524367365456 which will generate hash value as d411e0feeb11ae5de0df08518f5f8fe35a05ec107c9e7c26e899b21567d3764c

137x22xspace.png.pagespeed.ic.IoAxAisfVW
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:

 

ItemDetail
status_id1
order_id56
transaction_id14363538840
msgPayment_was_successful

3. So the string to be hash is 53-78415614363538840Payment_was_successful which will generate hash value as 0ebfcaab4be7463a67d605aad312a03cd6b41df4e3560c2a192b84baab15d127

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.

137x22xspace.png.pagespeed.ic.IoAxAisfVW
Download sample code

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

Screen Shot 2015-04-09 at 1.17.01 PM

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.

137x22xspace.png.pagespeed.ic.IoAxAisfVW

How to enable the feature

Login into your senangPay dashboard, go to Setting > Profile. Scroll down to the Shopping Cart Integration Link section. Under the Recurring Callback URL input field, you will se a checkbox to enable the advance callback setting. Tick the checkbox to allow senangPay to send the recurring callback data in JSON format. Untick to receive the standard callback data format.

137x22xspace.png.pagespeed.ic.IoAxAisfVW
The JSON structure

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

 

recurring_idThe ID of your recurring payment.
status_idThis is to indicate the status of the payment. It only has 2 values which is; 1 for successful and 0 for failed.
order_idThis is the order that was sent to senangPay. This is to identify the shopping cart transaction.
transaction_idThis is the transaction ID used by senangPay. You can use this ID to track the transaction in senangPay
msgThis 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.
hashThis is the data to ensure the data integrity passed from senangPay to the merchant’s shopping cart.
next_payment_dateNext payment date in UNIX timestamp.
payment_detailsJSON array of payment schedule for recurring instalment, and payment history for recurring subscription.

What if I have Return URL parameters set?

If you have custom return URL parameters, the JSON will follow the key and value set in your return URL parameters. 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]

 

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.

Screen Shot 2015-04-09 at 1.17.01 PM

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.

Info required

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

1.Go to Settings > Profile

Settings

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

IntegLink

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.

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. If you already had set the Callback URL for your manual integration API, then you can skip this step.

What parameters to send to senangPay

Below are the details of the elements in the table

 

ItemDetails
detailThis 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
amountThe amount to charge the buyer. The format must be in 2 decimal places. Example 25.50.
order_idThis 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.
hashThe 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.
nameThis 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.
emailThis 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.
phoneThis 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_settlementThis is a string containing the split settlement information. The string should follow below format.

Example
Total amount: RM10
Example

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

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/ followed by your merchant ID.

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

What Parameters does the shopping cart received from senangPay

 

ItemDetails
status_idThis is to indicate the status of the payment. It only has 2 values which is 1 for successful and 0 for failed.
order_idThis is the order that was sent to senangPay. This is to identify the shopping cart transaction.
msgThis 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_idThis 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
hashThis 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.

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.

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

2. For example if the values for the parameters are as below:

 

ItemDetails
Secret Key53-784
DetailShopping_cart_id_56
Amount10.00
Order ID56
Split Settlement1544436524:200|1677765432:300|1766653212:200

3. So the string to be hash is 53-784Shopping_cart_id_5610.00561544436524:200|1677765432:300|1766653212:200 which will generate hash value as 0284ce49406276a9e85dad1e820fb24c

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:

 

ItemDetails
status_id1
order_id56
transaction_id14363538840
msgPayment_was_successful

3. So the string to be hash is 53-78415614363538840Payment_was_successful which will generate hash value as 69686562c29ad3f7955b1843a5c275ca.
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.

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.

Download sample code

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

Screen Shot 2015-04-09 at 1.17.01 PM

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

Info required

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

1. Go to Settings > Profile

Screen Shot 2015-07-10 at 5.44.56 PM

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

Screen Shot 2015-10-06 at 6.51.15 PM

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. For more info on Callback URL, read here.

What parameters to send to senangPay

Below are the details of the elements in the table :

ItemDetail
detailThis 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.
amountThe amount to charge the buyer. The format must be in 2 decimal places. Example 25.50.
order_idThis 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.
hashThe 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.
nameThis 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.
emailThis 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.
phoneThis 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.

How to send the parameters to senangPay (Live)

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

2. The URL is https://app.senangpay.my/payment/ followed by your merchant ID.

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

How to send the parameters to senangPay (Sandbox)

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

2. The URL is https://sandbox.senangpay.my/payment/ followed by your merchant ID.

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

What Parameters does the shopping cart received from senangPay

Below are the details of the elements in the table :

ItemDetail
status_idThis is to indicate the status of the payment. It only has 2 values which is 1 for successful and 0 for failed.
order_idThis is the order that was sent to senangPay. This is to identify the shopping cart transaction.
msgThis 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_idThis 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
hashThis 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.

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.

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

2. For example if the values for the parameters are as below:

ItemDetail
Secret Key53-784
DetailShopping_cart_id_30
Amount24.50
Order ID56

3. So the string to be hash is 53-784Shopping_cart_id_3024.5056 which will generate hash value as 0bde51ff340f110ab7331a902aa969e7

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:

ItemDetail
status_id1
order_id56
transaction_id14363538840
msgPayment_was_successful

3. So the string to be hash is 53-78415614363538840Payment_was_successful which will generate hash value as 69686562c29ad3f7955b1843a5c275ca.

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.

Download sample code

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

Screen Shot 2015-04-09 at 1.17.01 PM

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

Info required

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

1. Go to Settings > Profile

Screen Shot 2015-07-10 at 5.44.56 PM

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

Screen Shot 2015-10-06 at 6.51.15 PM

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. For more info on Callback URL, read here.

What parameters to send to senangPay

Below are the details of the elements in the table :

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

ItemDetail
detailThis 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.
amountThe amount to charge the buyer. The format must be in 2 decimal places. Example 25.50.
order_idThis 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.
hashThe 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.
nameThis 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.
emailThis 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.
phoneThis 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.

How to send the parameters to senangPay (Live)

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

2. The URL is https://app.senangpay.my/payment/ followed by your merchant ID.

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

How to send the parameters to senangPay (Sandbox)

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

2. The URL is https://sandbox.senangpay.my/payment/ followed by your merchant ID.

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

What Parameters does the shopping cart received from senangPay

Below are the details of the elements in the table :

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

ItemDetail
status_idThis is to indicate the status of the payment. It only has 2 values which is 1 for successful and 0 for failed.
order_idThis is the order that was sent to senangPay. This is to identify the shopping cart transaction.
msgThis 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_idThis 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
hashThis 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.

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.

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

2. For example if the values for the parameters are as below:

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

ItemDetail
Secret Key53-784
DetailShopping_cart_id_30
Amount24.50
Order ID56

3. So the string to be hash is 53-784Shopping_cart_id_3024.5056 which will generate hash value as 0bde51ff340f110ab7331a902aa969e7

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:

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

ItemDetail
status_id1
order_id56
transaction_id14363538840
msgPayment_was_successful

3. So the string to be hash is 53-78415614363538840Payment_was_successful which will generate hash value as 69686562c29ad3f7955b1843a5c275ca.

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.

Download sample code

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

Screen Shot 2015-04-09 at 1.17.01 PM

Support

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

 

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.

 

Understanding breakdown in transaction flow

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

Screen Shot 2015-10-06 at 3.41.38 PM

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:

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

 

Solution when there is a breakdown in transaction flow

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.

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.

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.

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

 

Parameters

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.

 

Callback failure

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. Merchant must fix the issue and update their system with the correct status for the transaction. 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.

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

 

Method

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

 

Callback Frequency

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.

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

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.

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

 

Where to set Callback URL

Go to Menu > Settings > Profile. Scroll down the page and you will see the setting fields. For more information on how to set it, click here.

Screen Shot 2015-10-06 at 3.53.27 PM

 

Please take note that :

Please take note that you might receive multiple callback for the same transaction. The latest callback data is considered as the most up-to-date data for the transaction.

Screen Shot 2015-04-09 at 1.17.01 PM

Support

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. For the list of default parameters sent by senangPay please refer here. If your system is able to use the default parameters sent by senangPay then please leave the Return URL Parameters empty.

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

137x22xspace.png.pagespeed.ic.IoAxAisfVW

Purpose

Some system requires a fixed parameters sent to them in order to integrate. So in this case senangPay provide a way for merchant to specify the parameters that they would like to receive from senangPay. The return URL parameters are also applied to callback URL.

137x22xspace.png.pagespeed.ic.IoAxAisfVW

What parameters are available

Below are the list of parameters that senangPay supported

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

PlaceholderDetail
[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.

137x22xspace.png.pagespeed.ic.IoAxAisfVW

How to check the hashed value sent by senangPay

The hashed value is based on the return URL parameters string (appended with merchant secret key) with the value except for the hash. Each parameter values need to be urlencoded.

137x22xspace.png.pagespeed.ic.IoAxAisfVW

Example

For example if your system require parameters name as below:

1. email, example value “john@gmail.com”

2.  amount_paid, example value “10.50”

3. txn_status, example value “1”

4. txn_msg, example value “Payment was successful”

5. order_id, example value “A5463”

6. hashed_value

Your merchant secret key is 123-456.

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]

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.

Screen Shot 2015-04-09 at 1.17.01 PM

Have more questions? Submit a request by clicking the green help button right side, bottom

Screen Shot 2015-04-09 at 1.17.01 PM

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.
137x22xspace.png.pagespeed.ic.IoAxAisfVW

How can I get my Merchant ID & Secret Key

To get the Merchant ID & Secret Key, simply,

1. Login to you dashboard.

2. On the Menu > Settings > Profile

screen-shot-2016-10-25-at-8-52-54-pm

3. A page of profile will appears. Scroll down the page until you see a box with title “SHOPPING CART INTEGRATION LINK”. Refer to the field “Merchant ID” and “Secret Key”

screen-shot-2016-10-25-at-8-57-45-pm

Screen Shot 2015-04-09 at 1.17.01 PM
Have more questions? Submit a request by clicking the green help button right side, bottom

Screen Shot 2015-04-09 at 1.17.01 PM

Can senangPay be integrated with mobile apps?

Yes.
137x22xspace.png.pagespeed.ic.IoAxAisfVW

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.
137x22xspace.png.pagespeed.ic.IoAxAisfVW

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.
137x22xspace.png.pagespeed.ic.IoAxAisfVW

So then how can we integrate with mobile apps then?

You can use web view to deploy the payment part.
137x22xspace.png.pagespeed.ic.IoAxAisfVW

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.
137x22xspace.png.pagespeed.ic.IoAxAisfVW

Do senangPay plan to have the SDK in future

Yes we have that plan.
137x22xspace.png.pagespeed.ic.IoAxAisfVW

May I know when?

It’s complicated…….
137x22xspace.png.pagespeed.ic.IoAxAisfVW

Can I help senangPay to create the SDK?

May we have your number please?
137x22xspace.png.pagespeed.ic.IoAxAisfVW

Screen Shot 2015-04-09 at 1.17.01 PM
Have more questions? Submit a request by clicking the green help button right side, bottom

Screen Shot 2015-04-09 at 1.17.01 PM