Initialize Payment

Create a payment session and generate a Smart Payment Link for your customer.

---

Endpoint #

Method: POST
Path: /MerchantOrder/InitializePayment

Environments #

Environment	Base URL
UAT	https://test.amwalpg.com:14443
Production	https://webhook.amwalpg.com

Full Endpoint URLs #

UAT

https://test.amwalpg.com:14443/MerchantOrder/InitializePayment

Production

https://webhook.amwalpg.com/MerchantOrder/InitializePayment

---

Overview #

The Initialize Payment API creates a new payment session for the merchant and returns a Smart Payment Link.

The merchant should:

1. Prepare the payment request.
2. Generate the secureHashValue.
3. Send the request to the Initialize Payment endpoint.
4. Receive the SmartBox payment URL.
5. Redirect the customer to the returned URL.
6. Track the payment result using the merchant reference and configured notifications/reconciliation mechanisms.

A successful Initialize Payment response only confirms that the payment URL was created. It does not mean that the customer has completed the payment.

---

Authentication & Credentials #

The following credentials and permissions are required.

Item	Description
merchantId	Amwal merchant identifier
terminalId	E-commerce/digital terminal linked to the merchant
Merchant Secure Hash Key	Secret key used to generate secureHashValue
Webhook access	Merchant must be enabled to use webhook APIs
InitializePayment API	Must be enabled for the merchant

---

Request #

Headers #

Header	Required	Value
Content-Type	Yes	application/json

---

Initialize Payment Request #

Request Body #

{
  "merchantId": 13593,
  "terminalId": 101311,
  "amount": 10.5,
  "currency": 512,
  "language": 0,
  "merchantReference": "ORD-20260824-001",
  "requestDateTime": "2026-08-24T08:00:00.000Z",
  "returnUrl": "https://merchant.example.com/pay/success",
  "cancelUrl": "https://merchant.example.com/pay/cancel",
  "returnUrlMethodType": "Get",
  "paymentViewType": 2,
  "sessionToken": "",
  "orderItems": [
    {
      "name": "Item 1",
      "price": "10.500",
      "descriptionOne": "Desc 1",
      "descriptionTwo": "Desc 2"
    }
  ],
  "askForContactInformationFieldsType": 1,
  "splitProfileId": "",
  "udf": "optional-merchant-data",
  "primaryColor": "#0B3D5C",
  "requestSource": 1016,
  "secureHashValue": "REPLACE_WITH_VALID_HASH"
}

---

Request Parameters #

Field	Type	Required	Description
merchantId	Integer	Yes	Merchant ID
terminalId	Integer	Yes	E-commerce/digital terminal ID
amount	Decimal	Yes	Transaction amount in major currency units
currency	Integer	Yes	ISO 4217 numeric currency code
language	Integer	Yes	0 = English, 1 = Arabic
merchantReference	String	Yes	Unique merchant-generated payment reference
requestDateTime	String	Yes	Request timestamp in ISO 8601 UTC format
returnUrl	String	Recommended	URL where the customer is redirected after payment
cancelUrl	String	No	URL where the customer is redirected when payment is cancelled
returnUrlMethodType	String	No	Get or Post. Default: Get
paymentViewType	Integer	No	1 = PopUp, 2 = FullPage. Default: 2
sessionToken	String	No	Optional SmartBox customer session token
orderItems	Array / JSON String	No	Items displayed on the checkout
askForContactInformationFieldsType	Integer	No	1 = All, 2 = Email Only, 3 = Mobile Only, 4 = None
splitProfileId	String	No	Existing split profile ID
udf	String	No	Merchant-defined data passed through checkout
primaryColor	String	No	Checkout brand color in hexadecimal format
requestSource	Integer	No	Request source. Prefer 1016 for Webhook
secureHashValue	String	Yes	HMAC-SHA256 hash of the request fields

---

Order Items #

When orderItems is provided, each item should use the following structure.

Field	Type	Maximum Length
name	String	100
price	String	30
descriptionOne	String	150
descriptionTwo	String	150

Example #

[
  {
    "name": "Item 1",
    "price": "10.500",
    "descriptionOne": "Product description",
    "descriptionTwo": "Additional information"
  }
]

For secure-hash compatibility with the webhook gateway, it is recommended to send orderItems as a JSON string or omit the field when it is not required.

---

Success Response #

{
  "success": true,
  "responseCode": "00",
  "message": "Success",
  "data": "https://smartbox.example.com/add-payment/Ab12Cd34Ef"
}

Response Parameters #

Field	Type	Description
success	Boolean	Indicates whether the API request was successful
responseCode	String	API response code. 00 indicates success
message	String	Human-readable response message
data	String	Short SmartBox payment URL
errorList	Array	Error details when the request fails

Payment URL #

The value returned in data is the customer’s SmartBox payment URL.

Redirect the customer to this URL to continue the payment process.

Important: Do not interpret success: true as a successful payment. It only means that the payment URL was successfully created.

---

Payment URL Lifecycle #

The payment URL has a limited lifetime.

Step	Process
1	Merchant sends InitializePayment request
2	Amwal creates a unique order key/token
3	The full SmartBox URL is cached for approximately 30 minutes
4	A Merchant Order is created and associated with the merchantReference
5	API returns a short SmartBox URL
6	Customer opens the short URL
7	SmartBox resolves the token to the checkout URL
8	Customer completes or cancels the payment

URL Expiration #

The short payment URL should not be reused after its expiration period.

If the URL expires, the order is already paid, or the cached payment information is unavailable, the customer may receive an order-not-found or already-paid error.

Create a new Initialize Payment request when a new payment URL is required.

Saved Card #

If you want to enable saved card / card tokenization functionality during the Initialize Payment flow, first obtain the required Acquiring Session Token.

For the complete process of generating and using the Acquiring Session Token, refer to:
Acquiring Session Token – Amwal Pay →
After obtaining the session token, use it in the Initialize Payment request when configuring the payment flow for saved-card functionality.

---

Secure Hash Generation #

secureHashValue is required for Initialize Payment requests.

The hash is generated using the merchant’s Secure Hash Key.

Hash Generation Steps #

1. Collect all request body fields.
2. Exclude secureHashValue.
3. Exclude fields whose value is null.
4. Sort the field names alphabetically.
5. Convert each field into key=value.
6. Join the fields using &.
7. Calculate HMAC-SHA256 using the Merchant Secure Hash Key.
8. Treat the configured secret as hexadecimal and convert it to bytes before HMAC.
9. Convert the resulting digest to uppercase hexadecimal.
10. Send the result as secureHashValue.

Example Hash Input #

amount=10.5&currency=512&language=0&merchantId=13593&merchantReference=ORD-20260824-001&requestDateTime=2026-08-24T08:00:00.000Z&requestSource=1016&returnUrl=https://merchant.example.com/pay/success&terminalId=101311

The exact hash input depends on the fields included in the request.

If primaryColor, orderItems, or another supported field is included in the request, it must also be included in the hash according to the gateway’s field serialization rules.

Node.js Example #

const crypto = require('crypto');

function calcWebhookHash(obj, secretHex) {
  const sorted = Object.keys(obj)
    .filter(
      (key) =>
        key !== 'secureHashValue' &&
        obj[key] !== null &&
        obj[key] !== undefined
    )
    .sort()
    .reduce((acc, key) => {
      acc[key] = obj[key];
      return acc;
    }, {});

  const payload = Object.entries(sorted)
    .map(([key, value]) => {
      const serializedValue =
        typeof value === 'object'
          ? JSON.stringify(value)
          : value;

      return `${key}=${serializedValue}`;
    })
    .join('&');

  return crypto
    .createHmac('sha256', Buffer.from(secretHex, 'hex'))
    .update(payload, 'utf8')
    .digest('hex')
    .toUpperCase();
}

---

cURL Example #

UAT #

curl -X POST 'https://test.amwalpg.com:14443/MerchantOrder/InitializePayment' \
  -H 'Content-Type: application/json' \
  -d '{
    "merchantId": 13593,
    "terminalId": 101311,
    "amount": 10.5,
    "currency": 512,
    "language": 0,
    "merchantReference": "ORD-20260824-001",
    "requestDateTime": "2026-08-24T08:00:00.000Z",
    "returnUrl": "https://merchant.example.com/pay/success",
    "cancelUrl": "https://merchant.example.com/pay/cancel",
    "returnUrlMethodType": "Get",
    "paymentViewType": 2,
    "sessionToken": "",
    "orderItems": [],
    "askForContactInformationFieldsType": 1,
    "splitProfileId": "",
    "udf": "optional-merchant-data",
    "primaryColor": "#0B3D5C",
    "requestSource": 1016,
    "secureHashValue": "REPLACE_WITH_VALID_HASH"
  }'

Production #

Use the Production Initialize Payment endpoint with the same request structure and a valid production merchant configuration.

---

Response Handling #

A successful Initialize Payment request means:

• The merchant request was accepted.
• The secure hash was valid.
• The payment order was created.
• A SmartBox payment URL was generated.

It does not mean:

• The customer has opened the checkout.
• The customer has entered card details.
• The payment was authorized.
• The payment was captured.
• The payment was settled.

Payment completion should be handled separately through the configured payment return/notification and reconciliation mechanisms.

Use the merchantReference to correlate the payment with the merchant’s order.

---

Error Handling #

Error / Situation	Typical Cause	Recommended Action
SecureHashValueIsRequired	Hash was not provided	Generate and send secureHashValue
InvalidHashing	Hash does not match the request	Verify field sorting, serialization, secret, and hash generation
MerchantIdIsRequired	Merchant ID is missing	Provide a valid merchantId
MerchantNotFound	Merchant ID is invalid or unknown	Verify the merchant configuration
MerchantNotAllowedToUseWebHook	Webhook access is disabled	Ask Amwal to enable webhook access
WebhookApiNotEnabledForMerchant	Initialize Payment API is not enabled	Ask Amwal to enable this Api webhook access
NotAllowedForEcommerce	Terminal is not configured for e-commerce	Use a valid e-commerce terminal
InvalidMerchantTransactionCurrency	Currency is not supported	Use a currency enabled for the merchant
Order not found / already paid	Payment URL expired, cache missing, or order already paid	Create a new Initialize Payment request

---

Common Integration Errors #

Invalid Secure Hash #

Check that:

• secureHashValue itself is excluded from the hash.
• null values are excluded.
• Field names are sorted alphabetically.
• Values are serialized consistently.
• The Secure Hash Key is treated as hexadecimal.
• HMAC-SHA256 is used.
• The final hash is converted to uppercase hexadecimal.
• Any field included in the request is also included in the hash.

Incorrect Currency #

Make sure the currency is supported by the merchant and that the numeric ISO 4217 code is used.

For OMR:

currency = 512

Expired Payment URL #

Do not store and reuse an old SmartBox URL indefinitely.

If the URL has expired, initialize a new payment and redirect the customer to the newly generated URL.

---

Integration Flow #

Merchant
   |
   | 1. Prepare payment
   |
   | 2. Generate secureHashValue
   |
   v
AMWAL InitializePayment API
   |
   | 3. Validate merchant + hash
   |
   | 4. Create payment order
   |
   | 5. Generate SmartBox URL
   |
   v
Merchant
   |
   | 6. Redirect customer
   v
SmartBox Checkout
   |
   | 7. Customer completes payment
   |
   v
Payment Result / Notification
   |
   | 8. Merchant reconciles transaction
   v
Merchant Order

---

Implementation Checklist #

Before going live, verify the following:

• Merchant ID is correct.
• E-commerce terminal ID is correct.
• Merchant Secure Hash Key is configured securely.
• Webhook access is enabled.
• Initialize Payment API is enabled.
• API type 23 is enabled for the merchant.
• Content-Type: application/json is sent.
• merchantReference is unique for every payment.
• requestDateTime uses the recommended UTC ISO 8601 format.
• currency is supported by the merchant.
• secureHashValue is calculated before sending the request.
• secureHashValue excludes itself from the hash input.
• requestSource is included in the hash when it is included in the request.
• primaryColor is included in the hash when it is included in the request.
• The customer is redirected to the returned SmartBox URL.
• Payment completion is handled separately from Initialize Payment success.
• Expired payment URLs are not reused.
• UAT testing is completed before switching to Production.

---

Important Notes #

Initialize Payment is a payment-session creation API.
A successful response indicates that AMWAL Pay successfully generated a SmartBox payment URL. It does not represent a successful card transaction.

Never expose the Merchant Secure Hash Key in frontend code, JavaScript, browser requests, logs, or publicly accessible configuration. The hash must be generated server-side.

Always use a unique merchantReference so that your system can reliably associate the payment with the corresponding merchant order.