Implementation

Before beginning the integration process, ensure that you have the following:

• AMWAL Merchant Account: You need to have an active merchant account with AMWAL Payment Gateway. If you do not have one, please contact AMWAL’s support team using support@amwal-pay.com
• API Credentials: You will be provided with the credentials that include your Merchant ID, API Key, and any other information required to generate the secure hash.
• Access to Smartbox.js: The Smartbox.js file should be included or linked in your web application to initialize the AMWAL Checkout Page.
• Production: https://checkout.amwalpg.com/js/SmartBox.js?v=1.1
• SIT environment: https://test.amwalpg.com:19443/js/SmartBox.js?v=1.1
• UAT environment: https://test.amwalpg.com:7443/js/SmartBox.js?v=1.1

SSL Certificate: Your website must be hosted over HTTPS to ensure secure communication between your site and the payment gateway.

Integration #

The integration process consists of embedding the Smartbox.js file, configuring the required parameters, and ensuring secure communication between your website and AMWAL Payment Gateway using a secure hash. The following steps will guide you through the process:

Include Smartbox.js in Your Website

The first step is to include the Smartbox.js file in your website’s HTML file. You can do this by adding the following line of code within your or just before the closing tag:

<script src="path-to-your-js-folder/Smartbox.js"></script>

Make sure the file path is correct based on your project structure, it is better to link to the published Smartbox.js mainly for production to keep your web site updated with the new updates that may happen on the JS file in the future.

Configure Payment Settings

You will need to configure the necessary parameters to initialize the payment gateway. These configurations include details such as the amount to be paid, the currency, and the merchant information

Below is an example configuration that you can modify based on your specific business needs:

SmartBox.Checkout.configure = {
    MID: "YOUR_MERCHANT_ID",          // Merchant ID provided by Amwal
    TID: "YOUR_TERMINAL_ID",          // Terminal ID provided by Amwal
    CurrencyId: 512,                  // Currency ID (512 = OMR only)
    AmountTrxn: "1.025",              // Total transaction amount (sum of all order items)
    MerchantReference: "ORDER_1001",  // Unique order reference from merchant system
    LanguageId: "en",                 // 'en' for English, 'ar' for Arabic
    PaymentViewType: 1,               // 1 = Popup, 2 = Full Screen
    TrxDateTime: "2025-12-23 11:30:00",// Transaction date & time
    SessionToken: "",                 // Optional – required for recurring payments
    ContactInfoType: 1,               // Optional – 1=All, 2=Email only, 3=Phone only, 4=None

    /*
     |--------------------------------------------------------------------------
     | OrderItems  // Optional
     |--------------------------------------------------------------------------
     | This parameter is an array of objects.
     | Each object represents ONE item in the order.
     |
     | Name            : Product name
     | DescriptionOne  : Additional details (size, color, etc.)
     | DescriptionTwo  : Quantity or other info
     | Price           : Item price WITH currency (OMR)
     |
     | NOTE:
     | - AmountTrxn must equal the sum of all item prices
     | - Price should be string formatted as: "OMR X.XXX"
     |
     */
    OrderItems: [    // Optional
        {
            Name: "Nike Shoes",
            DescriptionOne: "Size: 41 Color: Black",
            DescriptionTwo: "Quantity: 1",
            Price: "OMR 0.500"
        },
        {
            Name: "Skechers Shoes _02",
            DescriptionOne: "Size: 42 Color: Blue",
            DescriptionTwo: "Quantity: 1",
            Price: "OMR 0.500"
        },
        {
            Name: "Puma T-Shirt",
            DescriptionOne: "Size: 43 Color: Red",
            DescriptionTwo: "Quantity: 1",
            Price: "OMR 0.025"
        }
    ],

    SecureHash: "GENERATED_SECURE_HASH", // Refer to secure hash generation section to generate secure hash.
    completeCallback: function (data) {
        console.log("completeCallback Received Data", data);
    },

    errorCallback: function (data) {
        console.log("errorCallback Received Data", data);
    },

    cancelCallback: function () {
        console.log("cancelCallback Triggered");
    }
};

Make sure to replace the placeholder values (your_merchant_id, order12345, etc.) with the actual values specific to your website and order.

Submit the Payment Request

Once the configuration and secure hash are set, submit the payment request by initializing
the checkout session using Smartbox.js. When the user clicks the “Pay” button, this request
is sent to the AMWAL Payment Gateway for validation:

<button id="payButton">Pay Now</button> 
<script> 
document.getElementById("payButton").onclick = function() { 
SmartBox.Checkout.showSmartBox();// Triggers the payment process 
}; 
</script> 

Once the request is submitted, the AMWAL Payment Gateway will validate the request and
open the checkout page for the user to complete the payment.