View Categories

Express ApplePay 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 Express ApplePay Payment</title>
</head>

<body>
               <div id=”applePayButton”></div>

<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.020”,              // Total transaction amount (sum of all order items)
        MerchantReference: “1581”,  // Unique order reference from merchant system
        LanguageId: “en”,                 // ‘en’ for English, ‘ar’ for Arabic
        TrxDateTime: “2026-06-07T06:41:55.114Z”,// Transaction date & time
        SessionToken: “”,                 // Optional – required for recurring payments
        ApplePayElementId: “applePayButton”, // The ID of the HTML element where the Apple Pay button will be rendered
        RequiredBillingContactFields: [“postalAddress”, “name”, “email”, “phone”], // Optional – Fields required from the user for billing contact
        RequiredShippingContactFields: [“postalAddress”, “name”, “email”, “phone”], // Optional – Fields required from the user for shipping contact
        SecureHash: “YOUR_GENERATED_SECURE_HASH” // Refer to secure hash generation section to generate secure hash.
        ,
        completeCallback: function (data) {
            console.log(“Payment completed”, data);
        },

        errorCallback: function (data) {
            console.log(“Payment error”, data);
        },
    };

    SmartBox.isApplePayPageReadyCallback = function (data) {
        console.log(“Apple Pay page is ready”, data); // This callback is triggered when the Apple Pay page is ready. You can check if the user can make Apple Pay payments here.
        if (data?.data?.canMakeApplePayPayments) {
            console.log(“User can make Apple Pay payments”);
        }
    };
    SmartBox.Checkout.addPayWithApplePayButton();


</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.020
CurrencyId=512
MerchantId=YOUR_MERCHANT_ID
MerchantReference=1581
RequestDateTime=2026-06-07T06:41:55.114Z”
SessionToken=”
TerminalId= YOUR_TERMINAL_ID

Server-side Examples: #

PHP

<?php
$data = ‘Amount=1.020&CurrencyId=512&MerchantId=YOUR_MERCHANT_ID&MerchantReference=1581&RequestDateTime=2026-06-07T06:41:55.114Z”&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

What are your Feelings