Redirect Pre-Authorization
- 06 Jun 2024
- 15 Minutes to read
- Contributors
- Print
- DarkLight
- PDF
Redirect Pre-Authorization
- Updated on 06 Jun 2024
- 15 Minutes to read
- Contributors
- Print
- DarkLight
- PDF
Article summary
Did you find this summary helpful?
Thank you for your feedback
This message is used to perform a Pre-Authorization using SmartRoute interface. It is based on the Redirection Communication Model described in the Communication Model section.
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
| Parameter | Description | |
|---|---|---|
| MessageID required | An alphanumeric value that represents the action for defined unique numbers as mentioned below:
| |
TransactionID required | The merchant generates the Transaction ID. It represents a unique identifier for the transaction and is alphanumeric which must not include special characters or spaces.
| |
MerchantID required | An alphanumeric value that represents the unique Merchant ID at SmartRoute. The payment gateway operation team provides this value based on the merchant enrollment.
| |
| Amount required | A numeric value that contains the ISO Formatted item purchase invoice amount with no decimal point. For example, 100 for 1.00 USD.
| |
| CurrencyISOCode required | A numeric value that contains the ISO formatted code for the currency, not the character value. For example, 840 for USD.
| |
| SecureHash required | An alphanumeric value that represents the generated hex-encoded hash using hashing algorithm SHA-2 (256) by concatenating parameters as a single string starting with the merchant’s Merchant Authentication Token. Then all parameters (required parameters and optional parameters - if available) are ordered alphabetically. By parameter’s name should be part of the secure hash, with no separators and no terminating character. Appendix B: Secure Hash – Redirect Payment; for more information, see secure hash generation.
| |
| PaymentDescription optional | An alphanumeric string contains a narrative Payment Description of the invoice, which uses the language specified in the language parameter. This value should be UTF-8 encoded. It is entered into the secure hash generation process.
| |
| Language optional | An alphabetic value representing the interface's language is displayed to the customer and used for the payment description parameter. SmartLink will use this value during the payment process to display the interface. Thus, supporting the selected language to the customer. For example, Supported values are En, Ar.
| |
| ItemID optional | An alphanumeric value represents the custom item ID.
| |
| ThemeID optional | An alphanumeric value represents the custom theme ID.
| |
| Version optional | A numeric value with (.) separator represents the command's version to be used. If this value is not provided, SmartRoute will consider its default value which is 1.0 Possible version values: - 2.0 or higher: an additional response field will be returned from SmartRoute to merchant that represents the payment method used "Response.PaymentMethod" - 2.1 or higher: indicates that the merchant will provide the AgreementID and AgreementType fields.
| |
| ResponseBackURL optional | Merchant site response page URL that will receive the response from SmartRoute. It can help merchants have different response pages based on the requested service or other criteria.
| |
| Channel optional | The Channel to be used by SmartRoute System. It could be one of the following:
| |
| Quantity optional | A numeric value greater than ZERO represents the quantity of purchased Items.
| |
| GenerateToken optional | This flag indicates whether to generate a tokenfor the entered card information or not. It accepts the values “Yes” and “No”. Sending this field as “No” acts like when the field is not sent at all. This parameter is a part of the tokenization. For more information, see Tokenization.
| |
| Token optional | The token is used in this request; to represent previously used card information. This parameter is a part of the tokenization parameters. For more information, see Tokenization.
| |
| AgreementID optional | The agreement Id represents a unique identifier for the agreement between the merchant and the payer where the payer authorizes the merchant to perform subsequent transactions (i.e. recurring) without their active participation. The subsequent transactions shall share the same agreement Id provided in this first transaction. The value is generated by the merchant and should be unique per recurring series.
Note: The same value should be provided while performing a recurring payment across the recurring series for this payer. | |
| AgreementType optional | Alphabetical value represents the type of subsequent transactions, if any, that will be initiated based on this first transactions. Possible values are:
| |
| AllowedPaymentMethod optional | This parameter is a string value that signifies a list of permitted payment methods available for the transaction. Possible values:
| |
| FailedResponseBackURL optional | Merchant site Failed response page URL that will receive the failed response from SmartRoute. It can help merchants have different response pages based on the requested service or other criteria, if not set, the failed response will be sent to the URL set in (ResponseBackURL)
|
Sample Request Preparation Code (Java)
//Step 1: Generate Secure Hash
// ... check appendices/Secure Hash Generation
// Step 2: Prepare Payment Request and Send It to Redirect JSP Page (To Send a Post Request)
request.setAttribute("TransactionID", transactionId);
request.setAttribute("MerchantID", "ANBRedirectM");
request.setAttribute("Amount", "2000");
request.setAttribute("CurrencyISOCode", "840");
request.setAttribute("MessageID", "1");
request.setAttribute("Quantity", "1");
request.setAttribute("Channel", "0");
request.setAttribute("Language", "en");
request.setAttribute("ThemeID", "1000000001");
// if this url is configured for the merchant it's not required, else it is required
request.setAttribute("ResponseBackURL", "http://MerchantSite/RedirectPaymentResponsePage");
request.setAttribute("Version", "1.0");
request.setAttribute("RedirectURL","http://SmartrouteURL/SmartRoutePaymentWEB/SRPayMsgHandler");
// set secure hash in the request
request.setAttribute("SecureHash", secureHash);
request.getRequestDispatcher(response.encodeURL("SubmitRedirectPaymentRequest.jsp")).
forward(request, response); Sample Request Submitting Code (Java)
<!-- STEP 3: Create JSP Page send Request -->
<%
// read the parameters from request
String redirectURL = (String) request.getAttribute("RedirectURL");
String amount = (String) request.getAttribute("Amount");
String currencyCode = (String) request.getAttribute("CurrencyISOCode");
String transactionID = (String) request.getAttribute("TransactionID");
String merchantID = (String) request.getAttribute("MerchantID");
String language = (String) request.getAttribute("Language");
String messageID = (String) request.getAttribute("MessageID");
String secureHash = (String) request.getAttribute("SecureHash");
String themeID = (String) request.getAttribute("ThemeID");
String responseBackURL = (String) request.getAttribute("ResponseBackURL");
String channel = (String) request.getAttribute("Channel");
String quantity = (String) request.getAttribute("Quantity");
String version = (String) request.getAttribute("Version");
%>
<html>
<body onload="javascript:document.redirectForm.submit();">
<form action="<%=redirectURL%>" method="post" name="redirectForm">
<input name="MerchantID" type="hidden" value="<%=merchantID%>"/>
<input name="Amount" type="hidden" value="<%=amount%>"/>
<input name="CurrencyISOCode" type="hidden" value="<%=currencyCode%>"/>
<input name="Language" type="hidden" value="<%=language%>"/>
<input name="MessageID" type="hidden" value="<%=messageID%>"/>
<input name="TransactionID" type="hidden" value="<%=transactionID%>"/>
<input name="ThemeID" type="hidden" value="<%=themeID%>"/>
<input name="ResponseBackURL" type="hidden" value="<%=responseBackURL%>"/>
<input name="Quantity" type="hidden" value="<%=quantity%>"/>
<input name="Channel" type="hidden" value="<%=channel%>"/>
<input name="Version" type="hidden" value="<%=version%>"/>
<input name="SecureHash" type="hidden" value="<%=secureHash%>"/>
</form>
</body>
</html> Response Parameters
| Parameter | Description |
|---|---|
Response.StatusCode required | An alphanumeric value that represents the response code that covers errors generated by the SmartRoute. Appendix A: Redirect Payment Response Codes for descriptive details about Response Codes.
|
| Response.StatusDescription required | An alphanumeric value that represents a message describing the response status received from SmartRoute. This parameter is filled only after a complete execution process using the language specified in the request. This value should be UTF-8 encoded when it is entered into the secure hash generation process.
|
| Response.Amount required | A numeric value that contains the purchase amount of the item.
|
| Response.CurrencyISOCode required | The numeric value is in ISO format for the currency. The value should be neither character value nor decimal point. For example, 840 for US Dollar, 400 for JOD.
|
| Response.AuthorizedAmount conditional | A numeric value that contains the purchase Authorized Amount of the item. The value is in ISO format with no decimal point. For example, 100 for 1.00 USD.
Condition: This parameter will be provided back to the merchant if the MCP is enabled for this merchant. |
Response.AuthorizedCurrencyISOCode conditional | Authorized Currency uses the numeric ISO Code for the payment.
Condition: This parameter will be provided back to the merchant if the MCP is enabled for this merchant. |
| Response.MerchantID required | An alphanumeric value that represents the unique ID of the merchant at SmartRoute. The SmartRoute operation team provides this value upon merchant enrollment.
|
| Response.TransactionID required | The merchant generates the Transaction ID. It represents a unique identifier for the transaction and is alphanumeric which must not include special characters or spaces.
|
| Response.MessageID required | An alphanumeric value that represents the action for defined unique numbers as mentioned below:
|
| Response.SecureHash required | An alphanumeric value that represents the generated hex-encoded hash using hashing algorithm SHA-2 (256) by concatenating parameters as a single string starting with the merchant’s Merchant Authentication Token. Then all parameters (required parameters and optional parameters - if available) are ordered alphabetically. By parameter’s name should be part of the secure hash, with no separators and no terminating character. Appendix B: Secure Hash – Redirect Payment; for more information, see secure hash generation.
|
| Response.PaymentMethod Conditional | An Alphanumeric value indicates the payment method. Supported values depend on the requested version as follows: If Version is 1.0 :
Condition: The SmartRoute operation team, upon merchant enrollment, provides possible Card Names. |
| Response.CardExpiryDate optional | An alphanumeric value represents the expiry date of the card in MMYY format. For example, 1221 for 12th December.
|
Response.CardHolderName optional | An alphanumeric value represents the cardholder name.
|
| Response.CardNumber optional | An alphanumeric value represents the masked Card Number.
|
| Response.GatewayStatusCode optional | An alphanumeric value that represents the gateway response code. This code covers errors generated by the chosen gateway.
|
| Response.GatewayStatusDescription optional | An alphanumeric value that represents a message describing the response status received from the chosen gateway using the language specified in the request. After completing the execution process, this parameter is filled in. This value should be UTF-8 encoded when it is entered into the secure hash generation process.
|
| Response.GatewayName optional | This value represents the gateway name that processed the transaction. It can be alphanumeric with special characters like space, ‘@’ and ‘_’.
|
| Response.RRN optional | An alphanumeric value that represents a Receipt Reference Number for the current payment transaction. This value is returned if the value is provided from the gateway.
|
| Response.ApprovalCode optional | Approval Code received from Payment Processor such as Visa. The values are returned in the following cases:
|
| Response.Token optional | The token that is assigned to the entered card information; responds to a “GenerateToken” flag with the value “Yes”. This parameter is a part of the tokenization parameters; for more information, see Tokenization.
|
| Response.IssuerName Conditional | An Alphanumeric value indicates the Bank Issuer Name.
Condition: This parameter will be provided back to the merchant if the provided version in the request is 3.1. |
Sample Response Code (Java)
String AUTHENTICATION_TOKEN = " Y2FkMTdlOWZiMzJjMzY4ZGFkMzhkMWIz";// Use Yours, Please Store Your Authentication Token in safe Place (eg. database)
// get All Request Parameters
Enumeration<String> parameterNames = request.getParameterNames();
// store all response Parameters to generate Response Secure Hash
// and get Parameters to use it later in your Code
Map<String, String> responseParameters = new TreeMap<String, String>();
while (parameterNames.hasMoreElements()) {
String paramName = parameterNames.nextElement();
String paramvalue = request.getParameter(paramName);
responseParameters.put(paramName, paramvalue);
}
// 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 : responseParameters.keySet()) {
responseOrderdString.append(responseParameters.get(treeMapKey));
}
System.out.println("Response Ordered 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 = responseParameters.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 = responseParameters.get("Response.Status");
System.out.println("Status is: " + status);
} Other Sample Request Code (.Net /PHP)
Sample Request Preparation Code (.Net)
//Step 1: Generate Secure Hash
// ... check appendices/Secure Hash Generation
// Step 2: Prepare Payment Request and Send It to Redirect ASP Page (To Send a Post Request)
this.Context.Items.Add("TransactionID", transactionId);
this.Context.Items.Add("MerchantID", "ANBRedirectM");
this.Context.Items.Add("Amount", "2000");
this.Context.Items.Add("CurrencyISOCode", "840");
this.Context.Items.Add("MessageID", "1");
this.Context.Items.Add("Quantity", "1");
this.Context.Items.Add("Channel", "0");
this.Context.Items.Add("Language", "en");
this.Context.Items.Add("ThemeID", "1000000001");
// if this url is configured for the merchant it's not required, else it is required
this.Context.Items.Add("ResponseBackURL", "http://MerchantSite/RedirectPaymentResponsePage");
this.Context.Items.Add("Version", "1.0");
this.Context.Items.Add("RedirectURL", "http://SmartrouteURL/SmartRoutePaymentWEB/SRPayMsgHandler");
// set secure hash in the request
this.Context.Items.Add("SecureHash", secureHash);
Server.Transfer("SubmitRedirectPaymentRequest.aspx", true);
$attributesData["SecureHash"] = $secureHash;
$_SESSION['SmartRouteParams'] = $attributesData;
//redirect to "redirect.php";
header('location: redirect.php');
exit(); Sample Request Preparation Code (.PHP)
//Step 1: Generate Secure Hash
// ... check appendices/Secure Hash Generation
// Step 2: Prepare Payment Request and Send It to Redirect PHP Page (To Send a Post Request)
$attributesData = array();
$attributesData["TransactionID"] = $transaction_id;
$attributesData["MerchantID"] = "ANBRedirectM";
$attributesData["Amount"] = "2000";
$attributesData["CurrencyISOCode"] = "840";
$attributesData["MessageID"] = "1";
$attributesData["Quantity"] = "1";
$attributesData["Channel"] = "0";
$attributesData["Language"] = "en";
$attributesData["ThemeID"] = "1000000001";
// if this url is configured for the merchant it's not required, else it is required
$attributesData["ResponseBackURL"] = "http://MerchantSite/RedirectPaymentResponsePage";
$attributesData["Version"] = "1.0";
$attributesData["RedirectURL"] = "http://SmartrouteURL/SmartRoutePaymentWEB/SRPayMsgHandler";
// set secure hash in the request
$attributesData["SecureHash"] = $secureHash;
$_SESSION['SmartRouteParams'] = $attributesData;
//redirect to "redirect.php";
header('location: redirect.php');
exit();Sample Request Submitting Code (.Net)
1. <%@ Page
Language="C#" AutoEventWireup="true" CodeFile="SubmitRedirectPaymentRequest.aspx.c
s" Inherits="vs_WebSite2_SubmitRedirectPaymentRequest" %>
2.
3. <!DOCTYPE html>
4.
5. <html xmlns="http://www.w3.org/1999/xhtml">
6. <head runat="server">
7. <title></title>
8. </head>
9. <body onload="javascript:document.redirectForm.submit();">
10. <!-- STEP 3: Create ASP Page send Request -->
11. <%
12. // read the parameters from request
13. String redirectURL = (String) this.Context.Items["RedirectURL"];
14. String amount = (String) this.Context.Items["Amount"];
15. String currencyCode = (String) this.Context.Items["CurrencyISOCode"];
16. String transactionID = (String) this.Context.Items["TransactionID"];
17. String merchantID = (String) this.Context.Items["MerchantID"];
18. String language = (String) this.Context.Items["Language"];
19. String messageID = (String) this.Context.Items["MessageID"];
20. String secureHash = (String) this.Context.Items["SecureHash"];
21. String themeID = (String) this.Context.Items["ThemeID"];
22. String responseBackURL = (String) this.Context.Items["ResponseBackURL"];
23. String channel = (String) this.Context.Items["Channel"];
24. String quantity = (String) this.Context.Items["Quantity"];
25. String version = (String) this.Context.Items["Version"];
26. %>
27.
28. <form action="<%=redirectURL%>" method="post" name="redirectForm">
29. <input name="MerchantID" type="hidden" value="<%=merchantID%>"/>
30. <input name="Amount" type="hidden" value="<%=amount%>"/>
31. <input name="CurrencyISOCode" type="hidden" value="<%=currencyCode%>"/>
32. <input name="Language" type="hidden" value="<%=language%>"/>
33. <input name="MessageID" type="hidden" value="<%=messageID%>"/>
34. <input name="TransactionID" type="hidden" value="<%=transactionID%>"/>
35. <input name="ThemeID" type="hidden" value="<%=themeID%>"/>
36. <input name="ResponseBackURL" type="hidden" value="<%=responseBackURL%>"/>
37. <input name="Quantity" type="hidden" value="<%=quantity%>"/>
38. <input name="Channel" type="hidden" value="<%=channel%>"/>
39. <input name="Version" type="hidden" value="<%=version%>"/>
40. <input name="SecureHash" type="hidden" value="<%=secureHash%>"/>
41. </form>
42. </body>
43. </html>
44. Sample Request Submitting Code (PHP)
1. <?php
2. if(!session_id()){
3. session_start();
4. }
5. // read the paramters from session
6. $parameters = $_SESSION['SmartRouteParams'];
7. $redirectURL = $parameters["RedirectURL"];
8. $merchantID = $parameters['MerchantID'];
9. $amount = $parameters['Amount'];
10. $currencyCode = $parameters['CurrencyISOCode'];
11. $language = $parameters['Language'];
12. $messageID = $parameters['MessageID'];
13. $transactionID = $parameters['TransactionID'];
14. $themeID = $parameters['ThemeID'];
15. $responseBackURL= $parameters['ResponseBackURL'];
16. $quantity = $parameters['Quantity'];
17. $channel = $parameters['Channel'];
18. $secureHash = $parameters['SecureHash'];
19. $version = $parameters['Version'];
20. ?>
21. <html>
22.
23.
24. <body onload="javascript:document.redirectForm.submit();">
25. <form action="<?php echo $redirectURL?>" method="post" name="redirectForm">
26. <input name="MerchantID" type="hidden" value="<?php echo $merchantID?>"/>
27. <input name="Amount" type="hidden" value="<?php echo $amount?>"/>
28. <input name="CurrencyISOCode" type="hidden" value="<?php echo $currencyCode?>"/>
29. <input name="Language" type="hidden" value="<?php echo $language?>"/>
30. <input name="MessageID" type="hidden" value="<?php echo $messageID?>"/>
31. <input name="TransactionID" type="hidden" value="<?php echo $transactionID?>"/>
32. <input name="ThemeID" type="hidden" value="<?php echo $themeID?>"/>
33. <input name="ResponseBackURL" type="hidden" value="<?php echo $responseBackURL?>"/>
34. <input name="Quantity" type="hidden" value="<?php echo $quantity?>"/>
35. <input name="Channel" type="hidden" value="<?php echo $channel?>"/>
36. <input name="Version" type="hidden" value="<?php echo $version?>"/>
37. <input name="SecureHash" type="hidden" value="<?php echo $secureHash?>"/>
38. </form>
39. </body>
40.
41. </html> Other Sample Response Code (.Net /PHP)
Sample Response Code (.Net)
1. String AUTHENTICATION_TOKEN = " Y2FkMTdlOWZiMzJjMzY4ZGFkMzhkMWIz";// Use Yours, Please Store Your Authentication Token in safe Place (eg.database)
2. // store all response Parameters to generate Response Secure Hash
3. // and get Parameters to use it later in your Code
4. SortedDictionary<string, string> responseParameters = new SortedDictionary<String, String>(StringComparer.Ordinal);
5. // get All Request Parameters
6. foreach (string s in Request.Form.Keys)
7. {
8. if(!"Response.SecureHash".Equals(s.ToString()))
9. {
10. if("Response.StatusDescription".Equals(s.ToString()) || "Response.GatewayStatusDescription".Equals(s.ToString()))
11. {
12. responseParameters.Add(s.ToString(), HttpUtility.UrlEncode(Request.Form[s], System.Text.Encoding.UTF8));
13. }
14. else
15. {
16. responseParameters.Add(s.ToString(), Request.Form[s]);
17. }
18. }
19. }
20.
21. // Now that we have the dictionary, order it to generate secure hash and compare it with the received one
22. StringBuilder responseOrderdString = new StringBuilder();
23. responseOrderdString.Append(AUTHENTICATION_TOKEN);
24. foreach (KeyValuePair<string, string> kv in responseParameters)
25. {
26. responseOrderdString.Append(kv.Value);
27. }
28. Console.WriteLine("Response Ordered String is: " + responseOrderdString.ToString());
29.
30. // Generate SecureHash with SHA256
31. SHA256 sha256;
32. byte[] bytes, hash;
33. string generatedsecureHash = string.Empty;
34.
35. bytes = Encoding.UTF8.GetBytes(responseOrderdString.ToString().ToString());
36. sha256 = SHA256Managed.Create();
37. hash = sha256.ComputeHash(bytes);
38. foreach (byte x in hash)
39. {
40. generatedsecureHash += String.Format("{0:x2}", x);
41. }
42.
43.
44. // get the received secure hash from result dictionary
45. String receivedSecurehash =
46. Request.Form["Response.SecureHash"];
47. if (receivedSecurehash != generatedsecureHash.ToString())
48. {
49. // If they are not equal then the response shall not be accepted
50. Console.WriteLine("Received Secure Hash does not Equal generated Secure hash");
51. }
52. else
53. {
54. // Complete the Action get other parameters from result dictionary and do
55. // your processes
56. // Please refer to The Integration Manual to See The List of The
57. // Received Parameters
58. String status = Request.Form["Response.Status"];
59. Console.WriteLine("Status is: " + status);
60. } Sample Response Code (PHP)
1. <?php
2. $AUTHENTICATION_TOKEN = "Y2FkMTdlOWZiMzJjMzY4ZGFkMzhkMWIz"; // Use Yours, Please Store Your Authentication Token in safe Place(eg. database)
3.
4. // get All Request Parameters
5. $parameterNames = isset($_REQUEST)?array_keys($_REQUEST):[];
6.
7. // store all response Parameters to generate Response Secure Hash
8. // and get Parameters to use it later in your Code
9. $responseParameters = [];
10. foreach($parameterNames as $paramName){
11. $responseParameters[$paramName] = filter_input(INPUT_REQUEST,$paramName);
12. }
13.
14. //order parameters by key using ksort
15. ksort($responseParameters);
16. $orderedString = $AUTHENTICATION_TOKEN;
17. foreach($responseParameters as $k=>$param){
18. $orderedString .= $param;
19. }
20.
21. echo "--- Ordered String ---".chr(10);
22. echo $orderedString.chr(10);
23.
24. // Generate SecureHash with SHA256
25. $secureHash = hash('sha256', $orderedString, false);
26.
27. // get the received secure hash from result map
28. $receivedSecureHash = filter_input(INPUT_REQUEST,'Response.SecureHash');
29.
30. // Now that we have the map, order it to generate secure hash and compare it with the received one
31. if($receivedSecureHash !== $secureHash){
32. // IF they are not equal then the response shall not be accepted
33. echo "Received Secure Hash does not Equal generated Secure hash";
34. }else{
35. // Complete the Action get other parameters from result map and do
36. // your processes
37. // Please refer to The Integration Manual to see the List of The
38. // Received Parameters
39. echo "Status is: ".filter_input(INPUT_REQUEST,'Response.Status');
40. } Related Articles: