senangPay Api Guide – API Guide for senangPay

API

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.

INTEGRATION

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.

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

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.

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.

API Endpoint for MOTO Transcation

Creating MOTO Payment

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

Authorization header

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

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

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

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/

Authorization Header

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

URL Parameter

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

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

Get MOTO Payment Details By Transaction Reference

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

Authorization header

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

URL Parameter

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

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

MOTO Data Transaction Response

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

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

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

Example Request

{
   "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": "[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"
 }

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": "[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"
 }

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

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)

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

Authorization Header (Basic Auth)

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

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

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.

Pay credit card using token

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

Authorization Header (Basic Auth)

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

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

Response Parameter

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

Enable/disable credit card

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

Authorization header (Basic Auth)

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

Request Parameter (All Mandatory)

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

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.

Validate payment token

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

Authorization header (Basic Auth)

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

Request Parameter (All Mandatory)

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

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.

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.

Integration Method

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/

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. $merchant_id = ‘123456789’; $secret_key = ‘34-9887’; $order_id = ‘abc654321’; # the order id provided by you. $string_to_hash = $merchant_id . $order_id; $final_hash = hash_hmac(‘SHA256’, $string_to_hash, $secret_key);

Respond Parameter

Item	Details
status	Token creation status. * 1 if success. * 0 if failed.
order_id	The order id provided earlier.
token	If card validation succeed, token will be generated. The token will be used for future payment on the card. If card validation failed, token value will be 0.
cc_num	The last four digits of the card. You might want to display the card number on your app, so, you can use these four digits and display as XXXXXXXXXXXX1118. If card validation failed, cc_num value will be 0000.
cc_type	This is the card type. Basically either VISA or Mastercard. Visa is vs and Mastercard is mc. When failed, the value is xx.
msg	Card validation status message. You will get various messages based on scenarios. If senangPay failed to validate the card, you will know the reason here. If succeed, you’ll get the message here too.
hash	This time around, the hash is generated for you. You need to verify the hash in order to make sure the response is coming from senangPay. Same hashing mechanism, HMAC SHA256 and your secret key as key hash key. What you need to hash? 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

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]

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
cc_expiry_year	This os the credit card expiry year
cc_ccv	This 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.

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

The parameters will be send using GET method.
The parameters are sent to URL as configured in the return URL Refer to Info required section

6. How to generate the secure Hash

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

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	21
cc_ccv	101
hash	3084c95c47660e2066c40961ed333519

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

Merchant will need to generate the secure hash and compare the secure hash that was received from senangPay.
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
So the string to be hash is 2-34015614363538840Payment_was_successful which will generate hash value as 49197d877cb4fa7bd770134506b7fb0a.
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.