Skip to main content

SADAD Direct Payment (Advanced Integration)

👉 DOWNLOAD SAMPLE CODE ZIP

Direct Payment is designed for advanced merchants and developers who want to:

  • Customize the checkout UI
  • Collect card details on their own interface
  • Send payment data securely to SADAD

There are two integration methods:

A. Using JS SDK and Hosted Checkout Form​

Step 1: Add Script to Checkout Page​

<script>
  var sadadGetChecksum = function() {

    $.ajax({
      type: "POST",
      url: "checksumgenerate", // Replace with your server URL
      data: $('#orderForm').serialize(), // Do NOT send card data
      success: function (response) {
        afterChecksumSubmit(response);
      },
      error: function (err) {
        afterChecksumSubmit(err.statusText);
      }
    });

  };
</script>

<div 
  id="sadad_cc_container"
  data-i-color="#531232"
  data-cbfunc="sadadGetChecksum">
</div>

<script src="https://sadadqa.com/jslib/sadad1.js"></script>

Step 2:​

Replace checksumgenerate with your server side script url that will generate the checksumhash for the order data. Refer to the checksum_form.html file mentioned in the zip package on what the server side script should return as the result. The form id must be “sadadFinalForm”.

Step 3:​

Generate the checksumhash using sadad.php file as a reference. Replace the data with your merchant account and order specific values.

Step 4:​

If your server is not in the PHP, you can use the checksum APIs to generate the checksumhash. The document to follow is Checksum APIs_final.pdf

Customization options:

  • You can specify your own function instead of sadadGetChecksum as “data-cbfunc” attribute. Make sure it returns the form like checksum_form.html
  • You can enter any valid color code for data-i-color attribute. You can define your custom css to customize button style, radio buttons style, input styles fonts etc.
  • If you want to display Arabic labels and error messages you can use “data-sd-lang” attribute. Valid values for this attribute are “ARB” and “ENG”. Default is “ENG”

B. Using direct APIs​

Step 1:​

The merchant will design and develop his own interface and will collect the payment method and card details (in case of credit card) in his application UI.

Step 2:​

The merchant will generate the checksum with the form data he’s sending (without payment data like payment method, credit card details etc.). The card details should never be sent to merchant’s server and should not be stored anywhere within the merchant’s server/application.

Step 3:​

Merchant will append the payment data including payment method and credit card (if payment method is credit card) and call the API with following details:

URL: https://sadadqa.com/jslib/callapi.php 
Method: POST 
Content-Type: application/x-www-form-urlencoded4 
Data:  
merchant_id=1234567& 
ORDER_ID=9006& 
WEBSITE=sadad.qa& 
TXN_AMOUNT=50.00& 
[email protected]& 
[email protected]& 
MOBILE_NO=999999999& 
CALLBACK_URL=https://sadad.qa/callback.php& 
txnDate=2021-08-30+11:43:34& 
productdetail[0][order_id]=9006& 
productdetail[0][itemname]=Sample Product& 
productdetail[0][amount]=50& 
productdetail[0][quantity]=1& 
productdetail[0][type]=line_item& 
checksumhash=RsvMNLuSZd7AfgWKMd3egbOWaEPze1qE8diVKl05O3s/uuPIqXu
dDASXwtry3cUkYmW4EKNAaSQx9DWG5AWpchVd25onwDAf7a5s9xp8EnI=& 
card_details[payment_method]=2

Parameters that should not be included in the checksumhash generation:

ParameterDescriptionValues
card_details[payment_method]Credit or Debit1 = Credit, 2 = Debit
card_details[card-number]16-digit card numberNumeric only
card_details[card-holders-name]Cardholder nameAlphanumeric
card_details[expiry-month]Expiry month01–12
card_details[expiry-year]Last 2 digitse.g., 21, 22
card_details[cvc]CVV3 or 4 digits
card_details[cardType]Card schemeVisa, Mastercard, Amex, JCB, Discover
card_details[saveCard]Save card flag1
card_details[user_ipAddress]Customer IPValid IP required

Response:  
{ 
 “status” : “success”, 
 “msg” : “<html>Dynamic form to be submitted.</html>” 
}

Error Response: 
{ 
  “status” : “failed”, 
  “error_message” : “The error message.” 
}

Step 4:​

If the response status is success, the msg field will contain a form to be submitted. The form’s name property would be echoForm for the debit card payment method and it can be submitted via simple Javascript function like below:

document.echoForm.submit();

Change in the credit card processing for 3DS w.e.f. 5 Oct, 2021: If the payment method is credit card, the msg field will contain an iframe with script. The developer must place the full content in the webpage/webview and the rest of the part will be handled accordingly.
The developer should bind the iFrame load event and monitor the URL to close/hide the iframe when it hits the callback URL.

Step 5:​

If the response status is failed, there will be a field present “error_message” and the merchant can show that error to his customer.

Callback URL Processing:

After the payment is completed by the user (success/failed), Sadad system will hit the callback URL with the following data as HTTP POST.

'website_ref_no' =>"", 
'transaction_status' => "3", 
'transaction_number' => 'SD123456789322', 
'MID' => "1234567", 
'RESPCODE' => "1", 
'RESPMSG' => 'Txn Success', 
'ORDERID' => '123456', 
'STATUS' => 'TXN_SUCCESS', 
'TXNAMOUNT' => "5", 
'checksumhash' => 
'z1DxSMDM0KFdDNj8MFn6v3lNNbxdT9krll5FWPdIy7ZVrF06YuJmARUeD
i43uIIHOjZkwAf+MJhFmUDA+LANKb0uWjxhdpf7sgFg5g0WsjM='

The checksumhash must be verified using the checksumverify API to ensure the callback URL is called by Sadad system only.
The field description for callback URL fields is given on https://developer.sadad.qa under web checkout section.