API for recurring payment with amount overwrite

Learn how to use the Recurring Payment API with an amount overwrite.

A. Info required

To start, we will need the information below that can be retrieved from the senangPay Dashboard.

1. Go to Menu > Settings > Profile

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

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

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

B. Getting the Recurring ID

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

1. Go to Menu >Product > Create New

2. Create a recurring product. You can learn how to create a recurring product below:

• Recurring Instalment
• Recurring Subscription

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

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

 

C. What parameters to send to senangPay

Below are the details of the elements in the table:

Item	Detail
order_id	This is the id used to identify the shopping cart when senangPay redirects the buyer to 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 used to identify the recurring product/item which senangPay needs to process.
hash	This is the data to ensure the data integrity has passed from the merchant’s shopping cart to senangPay. Refer to the "How to generate the secure hash" section below for more info.
amount	This is the amount that will be used as a recurring price overwritten for the recurring product. Merchants must first enable the feature for customers to overwrite the recurring price in the product creation.
name	This is the name to populate the payment form so that customer do not have to key in their names. This is optional and does not have to be a part of the hash. Customers are able to overwrite the value in the payment form.
email	This is the e-mail to populate the payment form so that customers do not have to key in their e-mails. This is optional and does not have to be a part of the hash. Customers are able to overwrite the value in the payment form.
phone	This is the phone number to populate the payment form so that customers do not have to key in their phone numbers. This is optional and does not have to be a part of the hash. Customers are able to overwrite the value in the payment form.

 

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

1. The parameters can be sent by either using the 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

 

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

1. The parameters can be sent by either using the 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

 

F. What Parameters does the shopping cart 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 two values: 1 for successful and 0 for failed.
order_id	This is the order that is 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 underscores. You can replace the underscore as space when displaying the message to your customers. 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 that the data integrity has passed from senangPay to the merchant’s shopping cart. Refer to the section 'How to verify if the secure hash is correct' for more info.

 

G. How senangPay sends the parameters to the merchant’s shopping cart

1. The parameters will be sent using the GET method.

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

 

H. 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:

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

3. Request parameter for md5 :

   $recurring_id = '155243673654';
   $order_id = '56';
   $amount = '3.30';

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

?>

 

I. How to verify if the secure hash is correct

1. Merchants will need to generate the secure hash and compared it to 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. Verify the hash :

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

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

?>

4. Now you need to compare the hash value that you have generated with the hash value sent by senangPay. If the values do not match, the data may have been tampered with.

J. Download sample code

For your reference, please download this sample code here.