API Pre-Authorization

This message performs a payment and is based on the API Communication Model described in the Communication Model section. The merchant should handle the authentication process for credit cards after performing an API Pre-Authorization and the returned ‘Response.StatusCode’ parameter is (20001 or 20002).

If the cases mentioned above are valid, an API Approve message must follow to pass any authentication data to the payment gateway. Otherwise, there is no need for an API Approve following an API Payment. You can refer to the appendix for further details about the credit card. 

If you wish to use the Apple Pay payment method with API Payment or API Pre-Authorization, you need to send Apple Pay Merchant Validation Message before validating the merchant and requesting Apple Pay Session.

Merchant to be aware that all pre-authorized transactions should be completed via the Completion message during a predefined duration. You can refer to the support team for more information.

Request Parameters

Sample Request Code (Java)

// if the Card was 3DS Enrolled, APIPayment Will be Divided into two requests. 
//in the response, if the received status code was “20001” or “20002” this means 
//that the Payment is 3DS supported, which means you need to authenticate with the 
//Bank site, all needed parameters for 3DS in will be included in the response,  
//and after Authentication, you will send APIApprove Request to SmartRoute. 
//Note: The Difference between 3DS payment and none-3DS Payment, will start after getting the APIPayment response. 
 
StringBuffer requestQuery = new StringBuffer(); 
 
requestQuery        
.append("TransactionID").append("=").append(transactionId).append("&") 
.append("MerchantID").append("=").append("ANBRedirectM").append("&") 
.append("Amount").append("=").append("2000").append("&") 
.append("CurrencyISOCode").append("=").append("840").append("&") 
.append("MessageID").append("=").append("8").append("&") 
.append("Quantity").append("=").append("1").append("&") 
.append("Channel").append("=").append("0").append("&") 
.append("PaymentMethod").append("=").append("1").append("&") 
.append("ClientIPaddress").append("=").append("127.0.0.1").append("&") 
 
//for Card Payment (conditional.append("&")paymentMethod=1) 
.append("CardNumber").append("=").append("4012001045873335").append("&") 
.append("ExpiryDateYear").append("=").append("01").append("&") 
.append("ExpiryDateMonth").append("=").append("19").append("&") 
.append("SecurityCode").append("=").append("123").append("&") 
.append("CardHolderName").append("=").append("1").append("&") 
 
//for Sadad Payment (conditional.append("&")paymentMethod=2) 
//.append("SadadOlpId").append("=").append("testSadad").append("&") 
//.append("mfu","https://MerchantSite/RedirectPaymentRequestPage").append("&") 
 
 
//fill some optional parameters 
.append("Language").append("=").append("en").append("&") 
.append("ThemeID").append("=").append("1000000001").append("&") 
.append("Version").append("=").append("1.0") 
.append("SecureHash").append("=").append(secureHash); 
 
//Send the request 
URL url = new URL("https://SR_URL"); 
URLConnection conn = url.openConnection(); 
conn.setDoOutput(true); 
OutputStreamWriter writer = new OutputStreamWriter(conn.getOutputStream(), "UTF-8"); 
 
//write parameters 
writer.write(requestQuery.toString()); 
writer.flush(); 

Response Parameters

Sample Response Code (Java)

// Get the response 
StringBuffer output = new StringBuffer(); 
BufferedReader reader = new BufferedReader(new InputStreamReader(conn.getInputStream(), "UTF-8")); 
String line; 
while ((line = reader.readLine()) != null) { 
    output.append(line); 
} 
writer.close(); 
reader.close(); 
 //Output the response 
System.out.println(output.toString()); 
 
// this string is formatted as a "Query String" - name=value&name2=value2....... 
String outputString=output.toString(); 
 
 
// To read the output string you might want to split it  
// on '&' to get pairs then on '=' to get name and value 
// and for a better and ease on verifying secure hash you should put them in a TreeMap 
String [] pairs=outputString.split("&"); 
 
Map<String,String> result=new TreeMap<String,String>(); 
 
// now we have separated the pairs from each other {"name1=value1","name2=value2",....} 
for(String pair:pairs){ 
 
    // now we have separated the pair to {"name","value"}    
    String[] nameValue=pair.split("="); 
 
    String name=nameValue[0];//first element is the name 
    String value=nameValue[1];//second element is the value 
 
    // put the pair in the result map 
    result.put(name,value); 
} 
 
 
// Now that we have the map, order it to generate secure hash and compare it with the received one 
 
 
StringBuilder responseOrderdString = new StringBuilder(); 
responseOrderdString.append(AUTHENTICATION_TOKEN); 
for (String treeMapKey : result.keySet()) { 
    responseOrderdString.append(result.get(treeMapKey)); 
} 
 
System.out.println("Response Orderd String is  " + responseOrderdString.toString()); 
 
// Generate SecureHash with SHA256 
// Using DigestUtils from appache.commons.codes.jar Library 
String generatedsecureHash = new String(DigestUtils.sha256Hex(responseOrderdString.toString()).getBytes()); 
 
// get the received secure hash from result map 
String receivedSecurehash=result.get("Response.SecureHash"); 
 
 
if(!receivedSecurehash.equals(generatedsecureHash)){ 
 
    //IF they are not equal then the response shall not be accepted   
    System.out.println("Received Secure Hash does not Equal generated Secure hash"); 
} 
else{ 
    // Complete the Action get other parameters from result map and do your processes  
    // please refer to The Integration Manual to See the List of The Received Parameters 
    String status=result.get("Response.Status"); 
    System.out.println("Status is :"+ status); 
 
    if ("20001".equalsIgnoreCase(status)) { 
        // if the received status code was 20001 this means that this transaction needs 3DS    
        //Authentication , the parameters you need are received with the response too. 
// prepare parameters to send to JSP , to Send it to 3DS in A Post Request 
        String bankUrl= (String)result.get("Response.AcsURL"); 
        String PaRequestMessage= (String)result.get("Response.PaRequestMessage"); 
     
        // 3DS Response page ( the url that you want 3DS Authentication to forward the request to) 
        String Merchant3DSResponseURL= "http://yoursite/your3DSResponsepage";   
     
        request.setAttribute("ACSURL", bankUrl); 
        request.setAttribute("3DSPaMessage", PaRequestMessage); 
        request.setAttribute("TERMURL_PREFIX", Merchant3DSResponseURL); 
     
        // Verification Enrollment Result Used for 3DS payment. 
        String veResult= (String)result.get("Response.ResponseVeResult"); 
     
        /***************************************************************************/ 
        /***************************************************************************/ 
        /***************************************************************************/ 
        /*STORE veResult IN DATABASE OR ANY SAFE PLACE TO USE IT IN APPROVE REQUEST*/ 
        /***************************************************************************/ 
        /***************************************************************************/ 
        /***************************************************************************/ 
     
         request.getRequestDispatcher("RedirectTo3DS.jsp").forward(request, response); 
    } 
    // this means that the transaction needs Sadad Authentication 
    else if("20002".equalsIgnoreCase(status)) { 
        String responseEstn = result.get("Response.estn"); 
        String responseMfu = result.get("Response.mfu"); 
        String responseAuthenticationUrl = result.get("Response.AuthenticationURL"); 
         
        request.setAttribute("responseEstn", responseEstn); 
        request.setAttribute("responseMfu", responseMfu); 
        request.setAttribute("responseAuthenticationUrl", responseAuthenticationUrl); 
     
        request.getRequestDispatcher("AuthenticateSadad.jsp").forward(request, response); 
     
    } 
    else { 
        // then the card is not 3ds enrolled  
        // this means your payment has been completed 
        System.out.println("Status is :"+ status);       
        }       
    } } 

Other Sample Request Code (.Net /PHP)

Sample Request Code (.Net)

1.    //in the response, if the received status code was “20002” it needs Sadad authentication, 
2.  //and after Authentication, you will send APIApprove Request to SmartRoute. 
3.          StringBuilder requestQuery = new StringBuilder(); 
4.          requestQuery 
5.                .Append("TransactionID").Append("=").Append(transactionId).Append("&") 
6.                .Append("MerchantID").Append("=").Append("ANBRedirectM").Append("&") 
7.                .Append("Amount").Append("=").Append("2000").Append("&") 
8.                .Append("CurrencyISOCode").Append("=").Append("840").Append("&") 
9.                .Append("MessageID").Append("=").Append("9").Append("&") 
10.          .Append("Quantity").Append("=").Append("1").Append("&") 
11.          .Append("Channel").Append("=").Append("0").Append("&") 
12.          .Append("PaymentMethod").Append("=").Append("1").Append("&") 
13.          .Append("ClientIPaddress").Append("=").Append("127.0.0.1").Append("&") 
14.          //for Card Payment (conditional.Append("&")paymentMethod=1) 
15.          .Append("CardNumber").Append("=").Append("4012001045873335").Append("&") 
16.          .Append("ExpiryDateYear").Append("=").Append("01").Append("&") 
17.          .Append("ExpiryDateMonth").Append("=").Append("19").Append("&") 
18.          .Append("SecurityCode").Append("=").Append("123").Append("&") 
19.          .Append("CardHolderName").Append("=").Append("1").Append("&") 
20.          .Append("SecureHash").Append("=").Append(secureHash).Append("&") 
21.          //for Sadad Payment (conditional.Append("&")paymentMethod=2) 
22.          //.Append("SadadOlpId").Append("=").Append("testSadad").Append("&") 
23.          //.Append("mfu","https://MerchantSite/RedirectPaymentRequestPage").Append("&") 
24.          //fill some optional parameters 
25.          .Append("Language").Append("=").Append("en").Append("&") 
26.          .Append("ThemeID").Append("=").Append("1000000001").Append("&") 
27.          .Append("Version").Append("=").Append("1.0") 
28.          .Append("SecureHash").Append("=").Append(secureHash); 
29.    
30.          //Send the request 
31.          string data = requestQuery.ToString().ToString(); 
32.          byte[] dataStream = Encoding.UTF8.GetBytes(data); 
33.          string urlPath = "https://SR_URL"; 
34.          string request = urlPath; 
35.          WebRequest webRequest = WebRequest.Create(request); 
36.          webRequest.Method = "POST"; 
37.          webRequest.ContentType = "application/x-www-form-urlencoded"; 
38.          webRequest.ContentLength = dataStream.Length; 
39.          Stream newStream = webRequest.GetRequestStream(); 
40.          // Send the data. 
41.          newStream.Write(dataStream, 0, dataStream.Length); 
42.          newStream.Close(); 

Sample Request Code (PHP)

1.        //Step 1: Generate Secure Hash 
2.        $SECRET_KEY = "Y2FkMTdlOWZiMzJjMzY4ZGFkMzhkMWIz"; // Use Yours, Please Store Your Secret Key in safe Place(e.g. database) 
3.        // put the parameters in a array to have the parameters to have them sorted alphabetically via ksort. 
4.        $parameters = []; 
5.        $transactionId = (int)microtime(true)*1000; //output to be like: 1495004320389 
6.        // fill required parameters 
7.        $parameters["TransactionID"] = $transactionId; 
8.        $parameters["MerchantID"] = "ANBRedirectM"; 
9.        $parameters["Amount"] = "2000"; 
10.  $parameters["CurrencyISOCode"] = "840"; 
11.  $parameters["MessageID"] = "9"; 
12.  $parameters["Quantity"] = "1"; 
13.  $parameters["Channel"] = "0"; 
14.  $parameters["PaymentMethod"] = "1"; 
15.  $parameters["ClientIPaddress"] = "127.0.0.1"; 
16.  //for Card Payment (conditional;paymentMethod=1) 
17.  $parameters["CardNumber"] = "4012001045873335"; 
18.  $parameters["ExpiryDateYear"] = "01"; 
19.  $parameters["ExpiryDateMonth"] = "19"; 
20.  $parameters["SecurityCode"] = "123"; 
21.  $parameters["CardHolderName"] = "1"; 
22.  //for Sadad Payment (conditional;paymentMethod=2) 
23.  //$parameters["SadadOlpId"] = "testSadad"; 
24.  //$parameters["mfu"] = "https://MerchantSite/RedirectPaymentRequestPage"; 
25.    
26.  //fill some optional parameters 
27.  $parameters["Language"] = "en"; 
28.  $parameters["ThemeID"] = "1000000001"; 
29.  $parameters["Version"] = "1.0"; 
30.  //Create an Ordered String of The Parameters Map with Secret Key 
31.    
32.  ksort($parameters); 
33.  $orderedString = $SECRET_KEY; 
34.  foreach($parameters as $param){ 
35.          $orderedString .= $param; 
36.  } 
37.  echo ("orderdString ". $orderedString); 
38.  // Generate SecureHash with SHA256 
39.  // Using DigestUtils from appache.commons.codes.jar Library 
40.  $secureHash = hash('sha256', $orderedString, false); 
41.    

//  API Payment Request  
1.  //in the response, if the received status code was “20002” it needs Sadad authentication, 
2.  //and after Authentication, you will send APIApprove Request to SmartRoute. 
3.  $requestQueryArr = [ 
4.                "TransactionID" => $transactionId, 
5.                "MerchantID" => "ANBRedirectM", 
6.                "Amount" => "2000", 
7.                "CurrencyISOCode" => "840", 
8.                "MessageID" => "9", 
9.                "Quantity" => "1", 10.          "Channel" => "0", 
11.          "PaymentMethod" => "1", 
12.          "ClientIPaddress" => "127.0.0.1", 
13.          //for Card Payment (conditional.append("&")paymentMethod=1) 
14.          "CardNumber" => "4012001045873335", 
15.          "ExpiryDateYear" => "01", 
16.          "ExpiryDateMonth" => "19", 
17.          "SecurityCode" => "123", 
18.          "CardHolderName" => "1", 
19.          "SecureHash" => $secureHash, 
20.          
21.          //for Sadad Payment (conditional.append("&")paymentMethod=2) 
22.          "SadadOlpId" => "testSadad", 
23.          "mfu" => "https://MerchantSite/RedirectPaymentRequestPage", 
24.          
25.          //fill some optional parameters 
26.          "Language" => "en", 
27.          "ThemeID" => "1000000001", 
28.          "Version" => "1.0", 
29.          "SecureHash" => $secureHash, 
30.  ]; 
31.  //configure query string 
32.  $newRequestQuery = http_build_query($requestQueryArr); 
33.    
34.  //Send the request 
35.  $ch = curl_init("https://SR_URL"); 
36.  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); 
37.  curl_setopt($ch,CURLOPT_POST, true); 
38.  curl_setopt($ch,CURLOPT_POSTFIELDS, $newRequestQuery); 
39.    

Other Sample Response Code (.Net /PHP)

Sample Response Code (.Net)

43.          // Get the response 
44.          WebResponse webResponse = webRequest.GetResponse(); 
45.          String output = webResponse.ToString(); 
46.          //Output the response 
47.          Console.WriteLine(output); 
48.    
49.          // this string is formatted as a "Query String" - name=value&name2=value2....... 
50.          String outputString = output.ToString(); 
51.    
52.          // To read the output string you might want to split it 
53.          // on '&' to get pairs then on '=' to get name and value 
54.          // and for a better and ease on verifying secure hash you should put them in a SortedDictionary 
55.          SortedDictionary<string, string> result = new SortedDictionary<String, String>(StringComparer.Ordinal); 
56.          NameValueCollection qscoll = HttpUtility.ParseQueryString(output); 
57.          foreach (String kv in qscoll.AllKeys ) 
58.            { 
59.                result.Add(kv, qscoll[kv]); 
60.            } 
61.    
62.          // Now that we have the SortedDictionary, order it to generate secure hash and compare it with the received one 
63.          StringBuilder responseOrderdString = new StringBuilder(); 
64.          responseOrderdString.Append(AUTHENTICATION_TOKEN); 
65.          foreach (KeyValuePair<string, string> kv in result) 
66.          { 
67.  if(!"Response.SecureHash".Equals(kv.Key)) 
68.     { 
69.       
70.      if("Response.StatusDescription".Equals(kv.Key) || "Response.GatewayStatusDescription".Equals(kv.Key))  
71.      { 
72.            responseOrderdString.Append(HttpUtility.UrlEncode(kv.Value, System.Text.Encoding.UTF8));     
73.          } 
74.        else 
75.        { 
76.            responseOrderdString.Append(kv.Value); 
77.        } 
78.     } 
79.          } 
80.          
81.          Console.WriteLine("Response Orderd String is " + responseOrderdString.ToString()); 
82.          // Generate SecureHash with SHA256 
83.    
84.          // Generate SecureHash with SHA256 from responseOrderedString 
85.          bytes = Encoding.UTF8.GetBytes(responseOrderdString.ToString().ToString()); 
86.          sha256 = SHA256Managed.Create(); 
87.          hash = sha256.ComputeHash(bytes); 
88.          String generatedsecureHash = String.Empty; 
89.          foreach (byte x in hash) 
90.          { 
91.              generatedsecureHash += String.Format("{0:x2}", x); 
92.          } 
93.    
94.          // get the received secure hash from result dictionary 
95.          String receivedSecurehash = result["Response.SecureHash"]; 
96.          if (receivedSecurehash != generatedsecureHash.ToString()) 
97.          { 
98.              //IF they are not equal then the response shall not be accepted 
99.              Console.WriteLine("Received Secure Hash does not Equal generated Secure hash"); 
100.          } 
101.          else 
102.          { 
103.              // complete the Action get other parameters from result dictionary and do your processes 

Sample Response Code (PHP)

40.  // Get the response 
41.  $output = curl_exec($ch); 
42.  curl_close($ch); 
43.    
44.  //Output the response 
45.  echo ($output); 
46.  // this string is formatted as a "Query String" - name=value&name2=value2....... 
47.    
48.  // To read the output string you might want to split it 
49.  // on '&' to get pairs then on '=' to get name and value using parse_str then order it using ksort 
50.  $result = []; 
51.  parse_str($output, $result); 
52.  ksort($result); 
53.    
54.  // Now that we have the map, order it to generate secure hash and compare it  with the received one 
55.  $responseOrderdString = $AUTHENTICATION_TOKEN; 
56.  foreach($result as $resParam) { 
57.          $responseOrderdString .= $resParam; 
58.  } 
59.  echo "Response Orderd String is " . $responseOrderdString; 
60.    
61.  // Generate SecureHash with SHA256 
62.  $generatedsecureHash = hash('sha256',$responseOrderdString); 
63.    
64.  // get the received secure hash from result map 
65.  $receivedSecurehash = $result['Response.SecureHash']; 
66.    
67.  if($receivedSecurehash !== $generatedsecureHash){ 
68.          //IF they are not equal then the response shall not be accepted 
69.          echo ("Received Secure Hash does not Equal generated Secure hash"); 
70.  }else{ 
71.          // complete the Action get other parameters from result map and do your processes 
72.          // please refer to The Integration Manual to See The List of The Received Parameters 
73.          $status= $result["Response.Status"]; 
74.          echo ("Status is :". $status); 
75.          if("20002" == $status) { 
76.                  $responseEstn = $result["Response.estn"]; 
77.                  $responseMfu = $result["Response.mfu"]; 
78.                  $responseAuthenticationUrl = $result["Response.AuthenticationURL"]; 
79.                  $_SESSION["responseEstn"] = $responseEstn; 
80.                  $_SESSION["responseMfu"] = $responseMfu; 
81.                  $_SESSION["responseAuthenticationUrl"] = $responseAuthenticationUrl; 
82.                  header("location: AuthenticateSadad.php"); 
83.                  exit(); 
84.          }else { 
85.                  // then the card is not 3ds enrolled 
86.                  // this means your payment has been completed 
87.                  echo ("Status is :". $status); 
88.          } 
89.  } 
90.    

Additional Conditional Request Parameters:

Tabby Payment Method Parameters:

EMKAN Payment Method Parameters:

STCPay, URPay Payment Method Parameters:

SADAD Billing Payment Method Parameters: