Direct Post Pre-Authorization
- 30 Jan 2024
- 20 Minutes to read
- Contributors
- Print
- DarkLight
- PDF
Direct Post Pre-Authorization
- Updated on 30 Jan 2024
- 20 Minutes to read
- Contributors
- Print
- DarkLight
- PDF
Article Summary
Share feedback
Thanks for sharing your feedback!
This message is used to perform a Pre-Authorization using SmartRoute interface and it is based on the Direct Post Communication Model as 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 contains the ISO Formatted item purchase invoice amount with no decimal point. For example, 100 for 1.00 USD.
|
| CurrencyISOCode required | A numeric value contains the ISO formatted code for the currency, not the character value. For example, 840 for USD.
|
| PaymentMethod required | An Alphanumeric value indicates the payment method. Supported values depend on the requested version as follows:
|
| 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) except (CardNumber, SecurityCode, CardHolderName, ExpiryDateYear, ExpiryDateMonth since those parameters are entered by the customer (cardholder) on the screen and are submitted directly to SmartRoute’s URL, so they cannot be captured and entered in the secure hash parameters.) Ordered alphabetically by parameter’s name should be part of the secure hash, with no separators and no terminating character Appendix B: Secure Hash – Direct Post Payment; for more information, see secure hash generation.
|
| CardNumber Conditional | The customer’s card number is used in the payment. If they sent PaymentMethod parameter is 1 (Card), this parameter is required.
Note: It should not be included in the Secure Hash. |
| ExpiryDateYear Conditional | The customer’s card expiry date (year)digits isused in the payment. The format of this parameter should be in the form (YY). If the PaymentMethod parameter is 1 (Card) is sent, this parameter is required. Text
Note: It should not be included in the Secure Hash. |
| ExpiryDateMonth Conditional | The customer’s card expiry date (month) digits are used in the payment. The format of this parameter should be in the form (MM). If the PaymentMethod parameter is 1 (Card) is sent, this parameter is required.
Note: It should not be included in the Secure Hash. |
| SecurityCode Conditional | The customer’s card Security Code (e.g. CVV or CVC) depends on the Card Type used in the payment. If the PaymentMethod parameter is 1 (Card) is sent, this parameter is required.
Note: It should not be included in the Secure Hash. |
| CardHolderName optional | The customer’s card holder name is used in the payment. If the PaymentMethod parameter is 1 (Card) is sent, this parameter is required.
Note: It should not be included in the Secure Hash. Spaces are allowed in the card holder name. |
| PaymentDescription optional | An alphanumeric string that 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 that represents 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 that represents the custom item 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.
|
| 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.
|
| 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.
|
| GenerateToken optional | This flag indicates whether to generate a token for 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 a 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:
|
| 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("PaymentMethod", "1");
//for Card Payment (conditional;paymentMethod=1)
request.setAttribute("CardNumber", "4012001045873335");
request.setAttribute("ExpiryDateYear", "01");
request.setAttribute("ExpiryDateMonth", "19");
request.setAttribute("SecurityCode", "123");
request.setAttribute("CardHolderName", "1");
//for Sadad Payment (conditional;paymentMethod=2)
//request.setAttribute("SadadOlpId", "testSadad");
request.setAttribute("Language", "en");
request.setAttribute("ThemeID", "1000000001");
request.setAttribute("ResponseBackURL", "https://MerchantSite/RedirectPaymentResponsePage");// if this url is configured for the merchant it's not required
request.setAttribute("Version", "1.0");
request.setAttribute("RedirectURL", "http://localhost:9080/SmartRoutePaymentWEB/SRPayMsgHandler");
// set secure hash in the requrest
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");
String paymentMethod = (String) request.getAttribute("PaymentMethod");
String cardNumber = (String) request.getAttribute("CardNumber");
String cardHolderName = (String) request.getAttribute("CardHolderName");
String securityCode = (String) request.getAttribute("SecurityCode");
String expiryDateYear = (String) request.getAttribute("ExpiryDateYear");
String expiryDateMonth = (String) request.getAttribute("ExpiryDateMonth");
String expiryDateMonth = (String) request.getAttribute("ExpiryDateMonth");
String sadadOlpId = (String) request.getAttribute("SadadOlpId");
%>
<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="PaymentMethod" type="hidden" value="<%=paymentMethod%>"/>
<input name="CardNumber" type="hidden" value="<%=cardNumber%>"/>
<input name="CardHolderName" type="hidden" value="<%=cardHolderName%>"/>
<input name="SecurityCode" type="hidden" value="<%=securityCode%>"/>
<input name="SadadOlpId" type="hidden" value="<%=sadadOlpId%>"/>
<input name="ExpiryDateYear" type="hidden" value="<%=expiryDateYear%>"/>
<input name="ExpiryDateMonth" type="hidden" value="<%=expiryDateMonth%>"/>
<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: Direct Post 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.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 that value represents the expiry date of the card in MMYY format. For example, 1221 for 12th December.
|
| Response.CardHolderName optional | An alphanumeric value that represents the cardholder name.
|
| Response.CardNumber optional | An alphanumeric value that represents the masked Card Number.
|
| Response.GatewayStatusCode optional | The alphanumeric value 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.
|
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 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 = 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)
1. this.Context.Items.Add("TransactionID", transactionId);
2. this.Context.Items.Add("MerchantID", "ANBRedirectM");
3. this.Context.Items.Add("Amount", "2000");
4. this.Context.Items.Add("CurrencyISOCode", "840");
5. this.Context.Items.Add("MessageID", "1");
6. this.Context.Items.Add("Quantity", "1");
7. this.Context.Items.Add("Channel", "0");
8. this.Context.Items.Add("PaymentMethod", "1");
9. this.Context.Items.Add("Language", "en");
10. this.Context.Items.Add("ThemeID", "1000000001");
11. this.Context.Items.Add("ResponseBackURL",
12. "https://MerchantSite/RedirectPaymentResponsePage");// if this url is configured for the merchant it's not required
13. this.Context.Items.Add("Version", "1.0");
14. this.Context.Items.Add("RedirectURL", "http://localhost:9080/SmartRoutePaymentWEB/SRPayMsgHandler");
15. // set secure hash in the requrest
16. this.Context.Items.Add("SecureHash", secureHash);
17. this.Server.Transfer("SubmitRedirectPaymentRequest.aspx", true); 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 Page (To Send a Post Request)
$paymentParameters = [];
$paymentParameters["TransactionID"] = $transactionId;
$paymentParameters["MerchantID"] = "ANBRedirectM";
$paymentParameters["Amount"] = "2000";
$paymentParameters["CurrencyISOCode"] = "840";
$paymentParameters["MessageID"] = "1";
$paymentParameters["Quantity"] = "1";
$paymentParameters["Channel"] = "0";
$paymentParameters["PaymentMethod"] = "1";
//$paymentParameters["SadadOlpId"] = "testSadad";
$paymentParameters["Language"] = "en";
$paymentParameters["ThemeID"] = "1000000001";
$paymentParameters["ResponseBackURL"] = "https://MerchantSite/RedirectPaymentResponsePage";// if this url is configured for the merchant it's not required
$paymentParameters["Version"] = "1.0";
$paymentParameters["RedirectURL"] = "http://localhost:9080/SmartRoutePaymentWEB/SRPayMsgHandler";
// set secure hash in the requrest
$paymentParameters["SecureHash"] = $secureHash;
$_SESSION['PaymentParams'] = $paymentParameters;
header('location: submitRedirectPayment.php'); 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>
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. <label>Card Number</label>
42. <input name="CardNumber" type="text" value=""/>
43. <br/>
44. <label>Card Holder Name</label>
45. <input name="CardHolderName" type="text" value=""/>
46. <br/>
47. <label>Security Code</label>
48. <input name="SecurityCode" type="text" value=""/>
49. <br/>
50. <label>Year Expiry Date</label>
51. <input name="ExpiryDateYear" type="text" value=""/>
52. <br/>
53. <label>Month Expiry Date</label>
54. <input name="ExpiryDateMonth" type="text" value=""/>
55. <br/>
56. <input type="submit" value="Proceed" />
57. </form>
58. </body>
59. </html> Sample Request Submitting Code (PHP)
1. <?php
2. if(!session_id()){
3. session_start();
4. }
5. ?>
6. <!-- STEP 3: Create PHP Page send Request -->
7. <?php
8. // read the parameters from request
9. $paymentParameters = $_SESSION["PaymentParams"];
10. $redirectURL = (String) $paymentParameters["RedirectURL"];
11. $amount = (String) $paymentParameters["Amount"];
12. $currencyCode = (String) $paymentParameters["CurrencyISOCode"];
13. $transactionID = (String) $paymentParameters["TransactionID"];
14. $merchantID = (String) $paymentParameters["MerchantID"];
15. $language = (String) $paymentParameters["Language"];
16. $messageID = (String) $paymentParameters["MessageID"];
17. $secureHash = (String) $paymentParameters["SecureHash"];
18. $themeID = (String) $paymentParameters["ThemeID"];
19. $responseBackURL = (String) $paymentParameters["ResponseBackURL"];
20. $channel = (String) $paymentParameters["Channel"];
21. $quantity = (String) $paymentParameters["Quantity"];
22. $version = (String) $paymentParameters["Version"];
23.
24. $paymentMethod = (String) $paymentParameters["PaymentMethod"];
25. //optional for sadad
26. $sadadOlpId = (String)$paymentParameters['SadadOlpId'];
27. ?>
28.
29. <html>
30. <body>
31. <form action="<?php echo $redirectURL?>" method="post" name="redirectForm">
32. <input name="MerchantID" type="hidden" value="<?php echo $merchantID?>"/>
33. <input name="Amount" type="hidden" value="<?php echo $amount?>"/>
34. <input name="CurrencyISOCode" type="hidden" value="<?php echo $currencyCode?>"/>
35. <input name="Language" type="hidden" value="<?php echo $language?>"/>
36. <input name="MessageID" type="hidden" value="<?php echo $messageID?>"/>
37. <input name="TransactionID" type="hidden" value="<?php echo $transactionID?>"/>
38. <input name="ThemeID" type="hidden" value="<?php echo $themeID?>"/>
39. <input name="ResponseBackURL" type="hidden" value="<?php echo $responseBackURL?>"/>
40. <input name="Quantity" type="hidden" value="<?php echo $quantity?>"/>
41. <input name="Channel" type="hidden" value="<?php echo $channel?>"/>
42. <input name="Version" type="hidden" value="<?php echo $version?>"/>
43. <input name="PaymentMethod" type="hidden" value="<?php echo $paymentMethod?>"/>
44. <input name="SadadOlpId" type="hidden" value="<?php echo $sadadOlpId ?>"/>
45. <label>Card Number</label>
46. <input name="CardNumber" type="text" value=""/>
47. <br/>
48. <label>Card Holder Name</label>
49. <input name="CardHolderName" type="text" value=""/>
50. <br/>
51. <label>Security Code</label>
52. <input name="SecurityCode" type="text" value=""/>
53. <br/>
54. <label>Year Expiry Date</label>
55. <input name="ExpiryDateYear" type="text" value=""/>
56. <br/>
57. <label>Month Expiry Date</label>
58. <input name="ExpiryDateMonth" type="text" value=""/>
59. <br/>
60. <input name="SecureHash" type="hidden" value="<?php echo $secureHash ?>"/>
61. <input type="submit" value="Proceed" />
62. </form>
63. </body>
64. </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.
6. // get All Request Parameters
7. foreach (string s in Request.Form.Keys)
8. {
9. if(!"Response.SecureHash".Equals(s.ToString()))
10. {
11. if("Response.StatusDescription".Equals(s.ToString()) || "Response.GatewayStatusDescription".Equals(s.ToString()))
12. {
13. responseParameters.Add(s.ToString(), HttpUtility.UrlEncode(Request.Form[s], System.Text.Encoding.UTF8));
14. }
15. else
16. {
17. responseParameters.Add(s.ToString(), Request.Form[s]);
18. }
19. }
20. }
21.
22. // Now that we have the dictionary, order it to generate secure hash and compare it with the received one
23. StringBuilder responseOrderdString = new StringBuilder();
24. responseOrderdString.Append(AUTHENTICATION_TOKEN);
25. foreach (KeyValuePair<string, string> kv in responseParameters)
26. {
27. responseOrderdString.Append(kv.Value);
28. }
29. Console.WriteLine("Response Ordered String is: " + responseOrderdString.ToString());
30.
31. // Generate SecureHash with SHA256
32. SHA256 sha256;
33. byte[] bytes, hash;
34. string generatedsecureHash = string.Empty;
35.
36. bytes = Encoding.UTF8.GetBytes(responseOrderdString.ToString().ToString());
37. sha256 = SHA256Managed.Create();
38. hash = sha256.ComputeHash(bytes);
39. foreach (byte x in hash)
40. {
41. generatedsecureHash += String.Format("{0:x2}", x);
42. }
43.
44.
45. // get the received secure hash from result dictionary
46. String receivedSecurehash = 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. //4.4 Direct Post Payment Response
3.
4. $AUTHENTICATION_TOKEN = "Y2FkMTdlOWZiMzJjMzY4ZGFkMzhkMWIz";// Use Yours, Please Store Your Authentication Token in safe Place (eg. database)
5. // get All Request Parameters
6. $parameters = $_REQUEST;
7. // store all response Parameters to generate Response Secure Hash, sort them
8. // and get Parameters to use it later in your Code
9. ksort($parameters);
10. // Now that we have the map, order it to generate secure hash and compare it with the received one
11. $responseOrderdString = "";
12. $responseOrderdString .= $AUTHENTICATION_TOKEN;
13. $responseOrderdString .= implode('', $parameters);
14.
15. echo ("Response Orderd String is: " . $responseOrderdString).chr(10);
16.
17. // Generate SecureHash with SHA256
18. $generatedsecureHash = hash('sha256', $responseOrderdString, false);
19. // get the received secure hash from result map
20. $receivedSecurehash = $parameters["Response.SecureHash"];
21. if ($receivedSecurehash !== $generatedsecureHash) {
22. // IF they are not equal then the response shall not be accepted
23. echo "Received Secure Hash does not Equal generated Secure hash";
24. } else {
25. // Complete the Action get other parameters from result map and do
26. // your processes
27. // Please refer to The Integration Manual to See The List of The
28. // Received Parameters
29. $status = $parameters["Response.Status"];
30. echo "Status is: " . $status;
31. } Additional Conditional Request Parameters:
Tabby Payment Method Parameters:
Parameter | Description |
email optional | This parameter is required if the sent PaymentMethod parameter is 8 (Tabby), and should be UTF-8 encoded when it is entered into the secure hash generation process.
|
phoneNumber optional | This parameter is required if the sent PaymentMethod parameter is 8 (Tabby), and should be UTF-8 encoded when it is entered into the secure hash generation process.
|
EMKAN Payment Method Parameters:
Parameter | Description |
EmkanCustomerId conditional | The customer’s National number or Iqama, this parameter is required if the sent PaymentMethod parameter is 7 (Emkan) and should be UTF-8 encoded when it is entered into the secure hash generation process.
|
voucherCode conditional | A code generated by Emkan for the customer, This parameter is required if the sent PaymentMethod parameter is 7 (Emkan), and should be UTF-8 encoded when it is entered into the secure hash generation process.
|
applicationId conditional | The number of the application generated by Emkan for the customer, This parameter is required if the sent PaymentMethod parameter is 7 (Emkan), and should be UTF-8 encoded when it is entered into the secure hash generation process.
|
STCPay Payment Method Parameters:
Parameter | Description |
Mobile optional | The customer’s mobile number, used to reference the customer’s eWallet. This parameter is required if the sent PaymentMethod parameter is 5 (STCPay), and should be UTF-8 encoded when it is entered into the secure hash generation process.
|
SADAD Billing Payment Method Parameters:
Parameter | Description |
userType conditional | If they sent the PaymentMethod parameter is 6 (Sadad Billing), this parameter is required. User type is a DDL field with two options Individual and Enterprise, and based on the selected option certain fields will be displayed.
|
NationalID conditional | Customer National Number. If they sent the PaymentMethod parameter is 6 (Sadad Billing) and selected "userType" is Individual, this parameter is required.
|
FirstNameAr conditional | First name in Arabic If they sent the PaymentMethod parameter is 6 (Sadad Billing) and selected "userType" is Individual, this parameter is required.
|
FatherNameAr conditional | Father's name in Arabic If they sent the PaymentMethod parameter is 6 (Sadad Billing) and selected "userType" is Individual, this parameter is required.
|
GrandFatherNameAr conditional | Grandfather's name in Arabic If they sent the PaymentMethod parameter is 6 (Sadad Billing) and selected "userType" is Individual, this parameter is required.
|
LastNameAr conditional | Last name in Arabic If they sent the PaymentMethod parameter is 6 (Sadad Billing) and selected "userType" is Individual, this parameter is required.
|
Email conditional | Customer Email. If they sent the PaymentMethod parameter is 6 (Sadad Billing) and selected "userType" is Individual, this parameter is required.
|
MobileNo conditional | Customer mobile number. If they sent the PaymentMethod parameter is 6 (Sadad Billing) and selected "userType" is Individual, this parameter is required.
|
DateofBirth conditional | Client date of birth yyyy-MM-DD If they sent the PaymentMethod parameter is 6 (Sadad Billing) and selected "userType" is Individual, this parameter is required.
|
RegistrationNo conditional | Company registration number If they sent the PaymentMethod parameter is 6 (Sadad Billing) and selected "userType" is Enterprise, this parameter is required.
|
NameAr conditional | Company name in Arabic. If they sent the PaymentMethod parameter is 6 (Sadad Billing) and selected "userType" is Enterprise, this parameter is required.
|
NameEn conditional | Company name in English. If they sent the PaymentMethod parameter is 6 (Sadad Billing) and selected "userType" is Enterprise, this parameter is required.
|
CommissionerNationalID conditional | Commissioner National Number. If they sent the PaymentMethod parameter is 6 (Sadad Billing) and selected "userType" is Enterprise, this parameter is required.
|
CommissionerName conditional | Commissioner name in English. If they sent the PaymentMethod parameter is 6 (Sadad Billing) and selected "userType" is Enterprise, this parameter is required.
|
CommissionerEmail conditional | Commissioner Email If they sent the PaymentMethod parameter is 6 (Sadad Billing) and selected "userType" is Individual, this parameter is required.
|
CommissionerMobileNo conditional | Customer mobile number If they sent the PaymentMethod parameter is 6 (Sadad Billing) and selected "userType" is Individual, this parameter is required.
|
Related Articles: