API integration
      Back to home
      1. Support Guide
      2. Developer Tools
      3. API integration

      Split settlement manual API integration

      This API allows you to split settlements for transactions to multiple merchants instead of only two when using the split settlement product.

      A. Information Required

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

      1. Go to Menu > Settings > Profile

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

      merchant-ID-13-1536x410 (1)

      3. Fill in the return URL. This is the URL where senangPay will redirect the buyer to after the payment has been processed. If you have already set the return URL for your manual integration API, you can skip this step.

      4.  Fill the Callback URL. This is used as an alternative notification to the merchant shopping cart in case there is a breakdown in the transaction flow. For more information on Callback URL, click here. If you have already set the Callback URL for your manual integration API, then you can skip this step.

      callback-url-13-1536x410

       

      B. Parameters to send to senangPay

      Below are the details of the elements in the table:

      Item Details
      detail The description that will be displayed when making the payment. The maximum length is 500 characters. Any underscores (_) will be converted to space. Only A to Z, a to z, 0 to 9, dot, comma, dash and underscores are allowed. Example: Shopping_cart_id_30.
      amount The amount to charge the buyer. The format must be in two (2) decimal places. Example: 25.50.
      order_id The id used to identify the shopping cart where senangPay redirects the buyer to after the payment is  made. The maximum length is 100 characters. Example: 3432D4. Only A to Z, a to z, 1 to 0 and dash are allowed.
      hash Data to ensure data integrity has passed from the merchant’s shopping cart to senangPay. Refer to ‘How to generate the secure hash’ section for more info.
      name Name to populate in the payment form so that customers do not have to key in their name. This is optional and does not have to be a part of the hash. Customer are able to overwrite the value in the payment form.
      email The e-mail to populate in the payment form so that customers do not have to key in their e-mail. 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 The phone number to populate in the payment form so that customers do not have to key in their phone. This is optional and does not have to be  a part of the hash. Customers are able to overwrite the value in payment form.
      split_settlement String containing the split settlement information. The string should follow the format below.

      1. Example
      Total amount: RM10
      Example

      • The split_amount should be the split amount multiplied by a hundred, but not in percentage.
      • Merchants can split the total amount to unlimited merchant accounts, as long as the amount in each merchant account (including the owners’) amount is RM2 or more.
      • The Merchant ID must be an active senangPay account.
      • No space or symbols are 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.

       

      C. How to send the parameters to senangPay

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

       

      D. Parameters received by the shopping cart from senangPay

      Item Details
      status_id To indicate the status of the payment. It has only two values: 1 for successful and 0 for failed.
      order_id The order sent to senangPay. This is to identify the shopping cart transaction.
      msg 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 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 The data to ensure 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.

       

      E. How  does senangPay send the parameters to merchant’s shopping cart?

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

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

       

      F. How to generate the secure hash

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

      2. So, the string to be hashed is:

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

      which will generate the hash value of:


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

      3. For your reference, please refer to this sample code.

       

      G. How to verify if the secure hash is correct

      1. Merchants will need to generate the secure hash and compare it to the secure hash that was received from senangPay.

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

      Item Details
      status_id 1
      order_id 56
      transaction_id 14363538840
      msg Payment_was_successful

      3. The string to be hashed is:

      53-78415614363538840Payment_was_successful 

      which will generate the hash value of:

      69686562c29ad3f7955b1843a5c275ca.

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

       

      H. Can I just add the Split Settlement parameter to 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.

       

      I. Sample code

      For your reference, please refer to this sample code which you can download here.