View Categories

Offsite Implementation

1. Overview #

The AMWAL Payment Gateway offers merchants a secure and seamless way to accept payments online through a highly customizable and easy-to-integrate checkout solution.

2. Environment URLs #

EnvironmentURL
Productionhttps://checkout.amwalpg.com/js/SmartBox.js?v=1.1
UAT/Testinghttps://test.amwalpg.com:7443/js/SmartBox.js?v=1.1

Note: Always test thoroughly in UAT before going live.

3. Prerequisites #

  • ✅ HTTPS enabled website
  • ✅ Merchant ID (MID) – Provided by Amwal
  • ✅ Terminal ID (TID) – Provided by Amwal
  • ✅ Secure Hash Key – Provided by Amwal (Keep SECRET)
  • ✅ Server-side hash generation capability

4. Integration Steps #

1. Include SmartBox.js

2. Configure Payment Parameters

3. Generate Secure Hash (Server-side)

4. Redirect Customer to Payment Page

5. Validate Response (Server-side)

5. Sample Implementation #

Complete HTML Integration: #

<!DOCTYPE html>
<html>

<head>
               
            <title>Amwal SmartBox Payment</title>
</head>

<body>
                <button id=”payButton”>Pay Now</button>

       
    <script src=”https://test.amwalpg.com:7443/js/SmartBox.js?v=1.1″></script>
       
    <script>
        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: “1581”, // Unique order reference from merchant system
            LanguageId: “en”,  // ‘en’ for English, ‘ar’ for Arabic
            PaymentViewType: 1,  // 1 = Popup, 2 = Full Screen
            TrxDateTime: “2026-04-28T10:21:09.735Z”,// Transaction date & time
            SessionToken: “”, // Optional – required for recurring payments
            ContactInfoType: 1,  // Optional – 1=All, 2=Email only, 3=Phone only, 4=None
            ReturnUrl: “YOUR_RETURN_URL”, // URL to redirect after payment completion
            CancelUrl: “YOUR_CANCEL_URL”, // Optional – URL to redirect if user cancels payment,
            ReturnUrlMethodType: “Post”, // // Default value is “Get”, if you set “Get” then response will be sent as query string parameters, if You set “Post” then response will be sent as form data.
            CheckoutSiteMode: ‘offsite’, // Optional – ‘onsite’ or ‘offsite’ (default is ‘onsite’),
            IgnoreReceipt: ‘false’, // when true, shows simplified success view; when false, shows full receipt with merchant, reference, and host data.
            UDF: “[{
                  “v1”: “test value 1”,
            “v2”: “test value 2”,
            “v3”: “test value 3”
        }], // Merchant custom-defined fields
        SecureHash: “YOUR_GENERATED_SECURE_HASH”, // Refer to secure hash generation section to generate secure hash.
       };
        SmartBox.Checkout.configure.SmartBoxColorConfig = { PrimaryColor: ‘#7f22ff’ }; // Controls the primary color for the entire payment app (buttons, labels, accents).


        document.getElementById(“payButton”).onclick = function () {

            SmartBox.Checkout.showSmartBox(); // This will redirect the user to the SmartBox payment page.
        };
    </script>
</body>

</html>

6. Secure Hash Generation #

CRITICAL: Generate on BACKEND only! Never expose your Secure Key or generate hash on frontend.

1. Prepare ALL config parameters (except SecureHash)

2. Sort alphabetically (A-Z) by parameter name

3. Concatenate: key=value&key=value format

4. Generate HMAC SHA-256 using your Secure Key

5. Convert to UPPERCASE hex

7. Example Parameters #

Amount=1.025
CurrencyId=512
MerchantId=YOUR_MERCHANT_ID
MerchantReference=ORDER_1581
RequestDateTime=2026-04-28T10:21:09.735Z
SessionToken=”
TerminalId= YOUR_TERMINAL_ID

Server-side Examples: #

PHP

<?php
$data = ‘Amount=1.025&CurrencyId=512&MerchantId=YOUR_MERCHANT_ID&MerchantReference=ORDER_1581&RequestDateTime=2026-04-28T10:21:09.735Z&SessionToken=&TerminalId=YOUR_TERMINAL_ID’;
$key = hex2bin(‘YOUR_HEX_SECURE_KEY’);
$hash = strtoupper(hash_hmac(‘sha256’, $data, $key));
echo $hash; // Send this to frontend
?>

Node.js

const crypto = require(‘crypto’);
const dataString = ‘Amount=1.025&CurrencyId=512&MerchantId=YOUR_MERCHANT_ID&MerchantReference=ORDER_1581&RequestDateTime=2026-04-28T10:21:09.735Z&SessionToken=&TerminalId=YOUR_TERMINAL_ID’;
const key = Buffer.from(‘YOUR_HEX_SECURE_KEY’, ‘hex’);

const hash = crypto.createHmac(‘sha256’, key)
    .update(dataString, ‘utf8’)
    .digest(‘hex’)
    .toUpperCase();

console.log(hash); // Send this to frontend

8. Response Validation #

Every AMWAL response includes a field named “secureHashValue”. You must recalculate the hash on your backend and compare.

Callback Response: #

amount, currencyId, customerId, customerTokenId, merchantId,
merchantReference, responseCode, terminalId, transactionId, transactionTime

Cloud Notification Response: #

Amount, AuthorizationDateTime, CurrencyId, DateTimeLocalTrxn,
MerchantId, MerchantReference, Message, PaidThrough, ResponseCode,
SystemReference, TerminalId, TxnType

Validation Steps: #

1. Remove secureHashValue from response

2. Sort remaining parameters alphabetically

3. Concatenate: key=value&key=value

4. Generate HMAC SHA-256 with your Secure Key

5. Compare with received secureHashValue

PHP Validation Examples: #

<?php
$data = ‘amount=1&currencyId=512&customerId=82383bce-6e32-4f5b-b1ea-7e00d5c446ed&customerTokenId=aacd0817-2246-4521-a3df-9f3971c63a22&merchantId=7921&merchantReference=201204&responseCode=00&terminalId=221143&transactionId=6b75efb6-84ab-46f2-8a32-351a23490f45&transactionTime=2024-12-10T15:56:37.1099636Z’;
$key = hex2bin(‘YOUR_HEX_SECURE_KEY’);
$hash = strtoupper(hash_hmac(‘sha256’, $data, $key));
echo $hash;
?>

For more details: #

Follow the link below

https://amwalpay.om/developers/secure-hash-calculation/secure-hash-calculation-2

Updated on May 11, 2026

What are your Feelings

  • Happy
  • Normal
  • Sad