In today’s digital economy, integrating robust payment solutions into your applications is crucial for enhancing user experience and driving business growth. OutSystems, a leading low-code development platform, empowers organizations to rapidly build and deploy applications. When combined with Amazon PayFort, a trusted payment gateway in the Middle East and North Africa (MENA) region, you can create secure, seamless payment experiences for your customers. Let’s explore how integrating Amazon PayFort with OutSystems can benefit your business.

Why Choose Amazon PayFort?

Amazon PayFort stands out as a reliable payment gateway for businesses looking to process online payments securely. Here are some key reasons why businesses opt for Amazon PayFort:

• Security and Compliance: Amazon PayFort adheres to stringent security standards and compliance regulations, ensuring that sensitive payment information is protected.
• Regional Expertise: It caters specifically to the MENA region, supporting local currencies and payment methods tailored to the preferences of regional customers.
• Flexible Integration: Amazon PayFort offers easy-to-integrate APIs and plugins for various platforms, making it straightforward to incorporate into your OutSystems applications.

Benefits of Integrating with OutSystems

OutSystems provides a powerful platform for building applications quickly and efficiently, making it an ideal choice for integrating payment gateways like Amazon PayFort. Here’s how your business can benefit:

• Accelerated Development: OutSystems’ low-code environment allows developers to drag and drop components, reducing the time and effort required to build and deploy payment functionalities.
• Scalability: As your business grows, OutSystems ensures that your applications can scale seamlessly. Integration with Amazon PayFort supports this scalability by handling increased transaction volumes efficiently.
• User Experience: By integrating Amazon PayFort, you enhance the checkout experience for your customers. They can make payments using their preferred methods, fostering trust and satisfaction.

Steps to Integrate Amazon PayFort with OutSystems

Integrating Amazon PayFort with OutSystems can be simplified into the following steps:

1. Register and Configure Amazon PayFort: Sign up for an Amazon PayFort account and configure your merchant settings to receive API credentials.
2. Develop the Integration: Utilize OutSystems’ visual development tools to create screens and workflows for payment processing. Use the Amazon PayFort API documentation to integrate payment features into your application.
3. Test and Deploy: Thoroughly test the integration in a staging environment to ensure smooth functionality and security. Once validated, deploy the integrated solution to production.
4. Monitor and Optimize: Continuously monitor transaction performance and user feedback. Optimize the payment flow based on analytics to improve conversion rates and user satisfaction.

Payment Integration Process Setup Prerequisites

• Admin should have merchant account credentials/keys required to interface with the payment gateway. Credentials like access_code, merchant_identifier, request_phrase, and response_phrase will need to be configured.
• The admin should have installed OutSystems Integration Studio to create .NET extensions.
• Admin should have installed Visual Studio 2019/2022. Developers need to write .NET code to generate the signature for payment.
• The admin should have permission to publish the extension code in Integration Studio.
• The admin requires deployment permission to deploy the extension from the developer to another environment.

Let’s dive further into the implementation:

1. Create a payment service application in OutSystems.
2. Create a .NET connector to generate signatures.
3. Use the signatures to call the Payment API, which will redirect to the Amazon PayFort payment portal.
4. Use the response signature to validate the response after payment processing.
5. Store the whole response received from the payment gateway in the central payment service module and the relevant subset of parameters in the consumer module.

Creating a SHA Request & Response Passphrase

Redirection to the Amazon PayFort payment gateway involves creating a SHA-256 request signature with the following parameters:

Signature Generation:

1. Sort all Amazon Payment Services request parameters (both mandatory and optional) in ascending alphabetical order based on the parameter names.
2. Concatenate the parameter name with the value separated by = (e.g., param_name=param_value).
3. Concatenate all the parameters directly without any separator (e.g., param_name1=param_value1param_name2=param_value2).
4. Add the Merchant’s Passphrase at the beginning and end of the parameters string (e.g., REQUESTPHRASEparam_name1=param_value1param_name2=param_value2REQUESTPHRASE).
5. Use the SHA or HMAC SHA function to generate the SHA or HMAC SHA value of the resulting string depending on the type of SHA or HMAC SHA selected by the Merchant.

Please note that all values mentioned in the examples are fictitious.

The following is an example of the Request Parameters:

• command = PURCHASE
• merchant_reference = Test010
• amount = 2120
• access_code = SILgpo7pWbmzuURp2qri
• merchant_identifier = MxvOupuG
• currency = AED
• language = en
• customer_email = test@gmail.com
• req_passphrase = REQPASS
• redirect_url = www.myredirectpage.com

Below are the Merchant signature settings from the back office:

• SHA Request Phrase: PASS
• SHA-Type: SHA-256

These parameters have to be sorted in ascending order as seen below to generate the response signature:

REQPASSaccess_code=SILgpo7pWbmzuURp2qriamount=1000command=PURCHASEcurrency=AEDcustomer_email=test@gmail.comlanguage=enmerchant_identifier=MxvOupuGmerchant_reference=Test010REQPASS

Below is the C# code to generate the SHA 256 signature

using System;
using System.Security.Cryptography;
using System.Text;

public class PayFortSignatureGenerator
{
    public static string GenerateSignature(string requestPhrase, string responsePhrase, string[] parameters)
    {
        // Step 1: Sort parameters
        Array.Sort(parameters);

        // Step 2: Concatenate parameters
        StringBuilder concatenatedParams = new StringBuilder();
        foreach (var param in parameters)
        {
            concatenatedParams.Append(param);
        }

        // Step 3: Add passphrase
        string stringToHash = $"{requestPhrase}{concatenatedParams}{responsePhrase}";

        // Step 4: Compute SHA-256 hash
        using (SHA256 sha256 = SHA256.Create())
        {
            byte[] hashBytes = sha256.ComputeHash(Encoding.UTF8.GetBytes(stringToHash));

            // Step 5: Convert to hexadecimal string
            StringBuilder hashString = new StringBuilder();
            foreach (byte b in hashBytes)
            {
                hashString.Append(b.ToString("X2")); // Convert byte to hexadecimal string
            }

            return hashString.ToString();
        }
    }

    public static void Main()
    {
        // Example parameters
        string requestPhrase = "REQPASS";
        string responsePhrase = "RESPONSEPASS";
        string[] parameters = 
        {
            "command=PURCHASE",
            "merchant_reference=Test010",
            "amount=1000",
            "access_code=SILgpo7pWbmzuURp2qri",
            "merchant_identifier=MxvOupuG",
            "currency=AED",
            "language=en",
            "customer_email=test@gmail.com"
        };

        string signature = GenerateSignature(requestPhrase, responsePhrase, parameters);
        Console.WriteLine("Generated SHA-256 Signature: " + signature);
    }
}

After running this through the SHA-256 algorithm, the following signature is obtained:

Signature = 94C38AFC7BDAE0114FC8C740EDF12416F22998241CE4B4EA70D5521233A2C882

Using the above signature, submit a POST redirection request to the Amazon PayFort payment gateway with the parameters indicated with $. To do this, create a JavaScript action using the JavaScript Widget and pipe the signature response along with other required parameters in a single Payment action

// Define the request parameters
var requestParams = {
  "command": $parameters.command,
  "access_code": $parameters.access_code,
  "merchant_identifier": $parameters.merchant_id,
  "merchant_reference": $parameters.merchant_ref,
  "amount": $parameters.amount,
  "currency": $parameters.curr,
  "language": $parameters.lang,
  "customer_email": $parameters.cust_email,
  "return_url": $parameters.return_url,
  "signature": $parameters.signature
  // Add other parameters as needed
};
// Create an HTML element
// Create a form element
var form = document.createElement('form');
form.action = paymentGatewayURL;
form.method = 'post';
form.name = 'frm';
// Add hidden input fields to the form
for (var key in requestParams) {
  if (requestParams.hasOwnProperty(key)) {
    var input = document.createElement('input');
    input.type = 'hidden';
    input.name = key;
    input.value = requestParams[key];
    form.appendChild(input);
  }
}
// Create a script element to submit the form automatically after it's appended to the body
var script = document.createElement('script');
script.type = 'text/javascript';
script.innerHTML = 'document.frm.submit();';
// Append the form and script elements to the body
document.body.appendChild(form);
document.body.appendChild(script);
console.log(document.body);

After the above JavaScript code has executed, the PayFort will automatically redirect from the client application to the payment gateway using the “paymentGatewayURL” and you will see the screen below.

Once the payment is processed, Amazon PayFort will automatically redirect to the URL we provided in the redirect_url parameter while creating the request signature.

The redirect_url has to be a POST request, which will be treated as a webhook by Amazon PayFort to send back the below JSON:

{
  "response_message": "Success",
  "amount": "21200",
  "response_code": "14000",
  "signature": "d02ab49f6117fd8dc03a3708160e42908dfaa3e95208c491928337d809c9a0dd",
  "merchant_identifier": "f607a65f",
  "access_code": "hhw5KWsQTbx6ny1IXYVO",
  "card_number": "5123********0008",
  "card_holder_name": "Jamie",
  "payment_option": "MASTERCARD",
  "expiry_date": "3901",
  "merchant_reference": "CM1117390360",
  "fort_id": "169996200018759633",
  "language": "en",
  "eci": "ECOMMERCE",
  "authorization_code": "310005",
  "token_name": "110be15d16d645b4890a102fe6a377f0",
  "customer_email": "jamie@jack.com",
  "reconciliation_reference": "424716010005",
  "currency": "AED",
  "status": "14"
}

Below are the steps to be followed to extract the response and redirect to a confirmation or error page post-payment processing:

1. Set the status code in this API to 302, indicating that the control will be redirected out of the API post-processing the response.
2. Using the GetFormValue server action, extract each and every JSON key-value pair.
3. Once all the key-value pairs are extracted, use the same C# signature extension created earlier to generate the reverse signature to verify against the signature obtained in the JSON response.
4. If the signature received and the signature generated using the extension match, the client application will accept the response as success or failure and vice versa.
5. The signature also contains a response_code, which is a combination of a 2-digit status and a 3-digit message as seen here.
6. Irrespective of the result, the entire response received from the Amazon PayFort payment gateway needs to be stored in a central payment service module, which can be handy in case of reconciliations with the bank.
7. Redirect the user to the necessary landing zone, i.e., page based on the processed outcome.

“The journey of a thousand miles begins with one step. And the more you share, the more you will learn and grow.”

— Lao Tzu & Leonard Nimoy