API mPre-Auth

API mPre-Auth is based on the API communication model described in the Communication Model section. 

This message is used to perform a payment without the need of performing 3DS authentication for credit card payments. However, some payment methods rather than credit card require authentication. 

The merchant should handle the authentication if required if the returned ‘Response.StatusCode’ parameter is (20002).

Then, 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 mPre-Auth.

Request Parameters

Sample Request Code (Java)

//in the response, if the received status code was “20002” it needs Sadad authentication, 
//and after Authentication, you will send APIApprove Request to SmartRoute. 
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("16").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("&") 
.append("SecureHash").append("=").append(secureHash).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("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.  // if the Card was 3DS Enrolled, APIPayment Will be Divided into two requests. 
2.  //in the response, if the received status code was “20001” or “20002” this means 
3.  //that the Payment is 3DS supported, which means you need to authenticate with the 
4.  //Bank site, all needed parameters for 3DS in will be included in the response, 
5.  //and after Authentication, you will send APIApprove Request to SmartRoute. 
6.  //Note: The Difference between 3DS payment and none-3DS Payment, will start after 
7.  // getting the APIPayment response. 
8.          StringBuilder requestQuery = new StringBuilder(); 
9.          requestQuery 
10.          .Append("TransactionID").Append("=").Append(transactionId).Append("&") 
11.          .Append("MerchantID").Append("=").Append("ANBRedirectM").Append("&") 
12.          .Append("Amount").Append("=").Append("2000").Append("&") 
13.          .Append("CurrencyISOCode").Append("=").Append("840").Append("&") 
14.          .Append("MessageID").Append("=").Append("16").Append("&") 
15.          .Append("Quantity").Append("=").Append("1").Append("&") 
16.          .Append("Channel").Append("=").Append("0").Append("&") 
17.          .Append("PaymentMethod").Append("=").Append("1").Append("&") 
18.          .Append("ClientIPaddress").Append("=").Append("127.0.0.1").Append("&") 
19.          //for Card Payment (conditional.Append("&")paymentMethod=1) 
20.          .Append("CardNumber").Append("=").Append("4012001045873335").Append("&
") 
21.          .Append("ExpiryDateYear").Append("=").Append("01").Append("&") 
22.          .Append("ExpiryDateMonth").Append("=").Append("19").Append("&") 
23.          .Append("SecurityCode").Append("=").Append("123").Append("&") 
24.          .Append("CardHolderName").Append("=").Append("1").Append("&") 
25.          //for Sadad Payment (conditional.Append("&")paymentMethod=2) 
26.          //.Append("SadadOlpId").Append("=").Append("testSadad").Append("&") 
27.          //.Append("mfu","https://MerchantSite/RedirectPaymentRequestPage").Append("&") 
28.          //fill some optional parameters 
29.          .Append("Language").Append("=").Append("en").Append("&") 
30.          .Append("ThemeID").Append("=").Append("1000000001").Append("&") 
31.          .Append("Version").Append("=").Append("1.0") 
32.          .Append("SecureHash").Append("=").Append(secureHash); 
33.    
34.          //Send the request 
35.          string data = requestQuery.ToString().ToString(); 
36.          byte[] dataStream = Encoding.UTF8.GetBytes(data); 
37.          string urlPath = "https://SR_URL"; 
38.          string request = urlPath; 
39.          WebRequest webRequest = WebRequest.Create(request); 
40.          webRequest.Method = "POST"; 
41.          webRequest.ContentType = "application/x-www-form-urlencoded"; 
42.          webRequest.ContentLength = dataStream.Length; 
43.          Stream newStream = webRequest.GetRequestStream(); 
44.          // Send the data. 
45.          newStream.Write(dataStream, 0, dataStream.Length); 
46.          newStream.Close(); 

Sample Request Code (PHP)

1.  // if the Card was 3DS Enrolled, APIPayment Will be Divided into two requests. 
2.  //in the response, if the received status code was “20001” or “20002” this means 
3.  //that the Payment is 3DS supported, which means you need to authenticate with the 
4.  //Bank site, all needed parameters for 3DS in will be included in the response, 
5.  //and after Authentication, you will send APIApprove Request to SmartRoute. 
6.  //Note: The Difference between 3DS payment and none-3DS Payment, will start after getting the APIPayment response. 
7.    
8.  $queryStringArr = [ 
9.                "TransactionID" => $transactionId, 
10.          "MerchantID" => "ANBRedirectM", 
11.          "Amount" => "2000", 
12.          "CurrencyISOCode" => "840", 
13.          "MessageID" => "16", 
14.          "Quantity" => "1", 
15.          "Channel" => "0", 
16.          "PaymentMethod" => "1", 
17.          "ClientIPaddress" => "127.0.0.1", 
18.          //for Card Payment (conditional.append("&")paymentMethod=1) 
19.          "CardNumber" => "4012001045873335", 
20.          "ExpiryDateYear" => "01", 
21.          "ExpiryDateMonth" => "19", 
22.          "SecurityCode" => "123", 
23.          "CardHolderName" => "1", 
24.          //for Sadad Payment (conditional.append("&")paymentMethod=2) 
25.          "SadadOlpId" => "testSadad", 
26.          "mfu" => "https://MerchantSite/RedirectPaymentRequestPage", 
27.          //fill some optional parameters 
28.          "Language" => "en", 
29.          "ThemeID" => "1000000001", 
30.          "Version" => "1.0", 
31.          "SecureHash" => $secureHash, 
32.  ]; 
33.    
34.  //Send the request 
35.  $newRequestQuery = http_build_query($queryStringArr); 
36.    
37.  $url = "https://SR_URL"; 
38.  $ch = curl_init($url); 
39.  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); 
40.  //write parameters 
41.  curl_setopt($ch,CURLOPT_POST, true); 
42.  curl_setopt($ch,CURLOPT_POSTFIELDS, $newRequestQuery); 
43.    

Other Sample Response Code (.Net /PHP)

Sample Response Code (.Net)

47.          // Get the response 
48.          WebResponse webResponse = webRequest.GetResponse(); 
49.          String output = webResponse.ToString(); 
50.          //Output the response 
51.          Console.WriteLine(output); 
52.    
53.          // this string is formatted as a "Query String" - name=value&name2=value2....... 
54.          String outputString = output.ToString(); 
55.    
56.          // To read the output string you might want to split it 
57.          // on '&' to get pairs then on '=' to get name and value 
58.          // and for a better and ease on verifying secure hash you should put them in a SortedDictionary 
59.          SortedDictionary<string, string> result = new SortedDictionary<String, String>(StringComparer.Ordinal);   
60.          NameValueCollection qscoll = HttpUtility.ParseQueryString(output); 
61.          foreach (String kv in qscoll.AllKeys) 
62.          { 
63.              result.Add(kv, qscoll[kv]); 
64.          } 
65.   
66.          
67.          // Now that we have the SortedDictionary, order it to generate secure hash and compare it with the received one 
68.          StringBuilder responseOrderdString = new StringBuilder(); 
69.          responseOrderdString.Append(AUTHENTICATION_TOKEN); 
70.          foreach (KeyValuePair<string, string> kv in result) 
71.          { 
72.              if(!"Response.SecureHash".Equals(kv.Key)) 
73.     { 
74.       
75.      if("Response.StatusDescription".Equals(kv.Key) || "Response.GatewayStatusDescription".Equals(kv.Key))  
76.      { 
77.            responseOrderdString.Append(HttpUtility.UrlEncode(kv.Value, System.Text.Encoding.UTF8));     
78.          } 
79.        else 
80.        { 
81.            responseOrderdString.Append(kv.Value); 
82.        } 
83.     }         
84.        } 
85.    
86.          Console.WriteLine("Response Ordered String is " + responseOrderdString.ToString()); 
87.    
88.          // Generate SecureHash with SHA256 from responseOrderedString 
89.          bytes = Encoding.UTF8.GetBytes(responseOrderdString.ToString().ToString()); 
90.          sha256 = SHA256Managed.Create(); 
91.          hash = sha256.ComputeHash(bytes); 
92.          String generatedsecureHash = String.Empty; 
93.          foreach (byte x in hash) 
94.          { 
95.              generatedsecureHash += String.Format("{0:x2}", x); 
96.          } 
97.    
98.          // get the received secure hash from result dictionary 
99.          String receivedSecurehash = result["Response.SecureHash"]; 
100.    
101.          if (receivedSecurehash != generatedsecureHash.ToString()) 
102.          { 
103.              //IF they are not equal then the response shall not be accepted 
104.              Console.WriteLine("Received Secure Hash does not Equal generated Secure hash"); 
105.          } 
106.          else 
107.          { 
108.              // Complete the Action get other parameters from result dictionary and do your processes 
109.              // please refer to The Integration Manual to See the List of The Received Parameters 
110.              String status = result["Response.Status"]; 
111.              Console.WriteLine("Status is :" + status); 
112.              if ("20001" == status) 
113.              { 
114.                  // if the received status code was 20001 this means that this transaction needs 3DS 
115.                  //Authentication , the parameters you need are received with the response too.16 | P a g e 
116.                  // prepare parameters to send to ASP , to Send it to 3DS in A Post Request 
117.                  String bankUrl = (String)result["Response.AcsURL"]; 
118.                  String PaRequestMessage = (String)result["Response.PaRequestMessage"]; 
119.                  // 3DS Response page ( the url that you want 3DS Authentication to forword the request to) 
120.                  String Merchant3DSResponseURL = "http://yoursite/your3DSResponsepage"; 
121.                  
122.                  this.Context.Items.Add("ACSURL", bankUrl); 
123.                  this.Context.Items.Add("3DSPaMessage", PaRequestMessage); 
124.                  this.Context.Items.Add("TERMURL_PREFIX", Merchant3DSResponseURL); 
125.                  // Verification Enrollment Result Used for 3DS payment. 
126.                  String veResult = (String)result["Response.ResponseVeResult"]; 
127.                  /***********************************************************/ 
128.                  /***********************************************************/ 
129.                  /***********************************************************/ 
130.                  /*STORE veResult IN DATABASE OR ANY SAFE PLACE TO USE IT IN APPROVE REQUEST*/ 
131.                  /************************************************************/ 
132.                  /************************************************************/ 
133.                  /************************************************************/
                 
134.                  this.Server.Transfer("RedirectTo3DS.aspx", true); 
135.              } 
136.              // this means that the transaction needs Sadad Authentication 
137.              else if ("20002" == status) 
138.              { 
139.                  String responseEstn = result["Response.estn"]; 
140.                  String responseMfu = result["Response.mfu"]; 
141.                  String responseAuthenticationUrl = result["Response.AuthenticationURL"]; 
142.                  this.Context.Items.Add("responseEstn", responseEstn); 
143.                  this.Context.Items.Add("responseMfu", responseMfu); 
144.                  this.Context.Items.Add("responseAuthenticationUrl", responseAuthenticationUrl);                 
145.                  this.Server.Transfer("AuthenticateSadad.aspx", true); 
146.              } 
147.              else 
148.              { 
149.                  // then the card is not 3ds enrolled 
150.                  // this means your payment has been completed 
151.                  Console.WriteLine("Status is :" + status); 
152.              } 
153.          } 

Sample Response Code (PHP)

44.  // Get the response 
45.  $output = curl_exec($ch); 
46.  curl_close($ch); 
47.  //Output the response 
48.  echo $output; 
49.    
50.  // To read the output string you might want to split it 
51.  // on '&' to get pairs then on '=' to get name and value 
52.  // and for a better and ease on verifying secure hash you should put 
53.  $result = []; 
54.  parse_str($output, $result); 
55.  ksort($result); 
56.    
57.  // Now that we have the map, order it to generate secure hash and compare it with the received one 
58.  $responseOrderdString = $AUTHENTICATION_TOKEN; 
59.  foreach($result as $res_k=>$result_v){ 
60.      $responseOrderdString .= $result_v; 
61.  } 
62.    
63.  echo "-- Response Orderd String --".chr(10); 
64.  echo $responseOrderdString.chr(10); 
65.    
66.  // Generate SecureHash with SHA256 
67.  $generatedsecureHash = hash('sha256',$responseOrderdString); 
68.    
69.  // get the received secure hash from result map 
70.  $receivedSecurehash = $result['Response.SecureHash']; 
71.    
72.  if($receivedSecurehash == $generatedsecureHash){ 
73.      // IF they are not equal then the response shall not be accepted 
74.      echo "Received Secure Hash does not Equal generated Secure hash".chr(10); 
75.  }else{ 
76.    
77.      // Complete the Action get other parameters from result map and do 
78.      // your processes 
79.      // Please refer to The Integration Manual to See The List of The 
80.      // Received Parameters 
81.      $status = $result["Response.Status"]; 
82.      echo "Status is :" . $status.chr(10);     
83.          if ("20001" === $status) { 
84.                  // if the received status code was 20001 this means that this transaction needs 3DS 
85.                  //Authentication, the parameters you need are received with the response too. 
86.                  // prepare parameters to send to JSP , to Send it to 3DS in A Post Request 
87.                  $bankUrl = (String)$result["Response.AcsURL"]; 
88.                  $PaRequestMessage = (String)$result["Response.PaRequestMessage"]; 
89.                  // 3DS Response page ( the url that you want 3DS Authentication to forword the request to) 
90.                  $Merchant3DSResponseURL= "http://yoursite/your3DSResponsepage"; 
91.                  $_SESSION["ACSURL"] = $bankUrl; 
92.                  $_SESSION["3DSPaMessage"] = $PaRequestMessage; 
93.                  $_SESSION["TERMURL_PREFIX"] = $Merchant3DSResponseURL; 
94.                  
95.                  // Verification Enrollment Result Used for 3DS payment. 
96.                  $veResult= (String)$result["Response.ResponseVeResult"]; 
97.                  
98.                  /***********************************************************/ 
99.                  /***********************************************************/ 
100.                  /***********************************************************/ 
101.                  /*STORE veResult IN DATABASE OR ANY SAFE PLACE TO USE IT IN APPROVE REQUEST*/ 
102.                  /***********************************************************/ 
103.                  /***********************************************************/ 
104.                  /***********************************************************/ 
105.                  header("location: RedirectTo3DS.php"); 
106.                  exit(); 
107.          }else if("20002" === $status) { 
108.                  // this means that the transaction needs Sadad Authentication 
109.                  $responseEstn = $result["Response.estn"]; 
110.                  $responseMfu = $result["Response.mfu"]; 
111.                  $responseAuthenticationUrl = $result["Response.AuthenticationURL"]; 
112.                  $_SESSION["responseEstn"] = $responseEstn; 
113.                  $_SESSION["responseMfu"] = $responseMfu; 
114.                  $_SESSION["responseAuthenticationUrl"] = $responseAuthenticationUrl; 
115.                  
116.                  header("location: AuthenticateSadad.php"); 
117.                  exit();         
118.          }else { 
119.                  // then the card is not 3ds enrolled 
120.                  // this means your payment has been completed 
121.                  echo "Status is :". $status; 
122.          } 
123.  }