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:

Prepare the payment request.
Generate the secureHashValue.
Send the request to the Initialize Payment endpoint.
Receive the SmartBox payment URL.
Redirect the customer to the returned URL.
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,
  "merchantCustomerId": "137852015",
  "orderItems": "[\n  {\n    \"name\": \"Item 1\",\n    \"price\": \"10.500\",\n    \"descriptionOne\": \"Desc 1\",\n    \"descriptionTwo\": \"Desc 2\"\n  }\n]",
  "askForContactInformationFieldsType": 1,
  "splitProfileId": "",
  "udf":"{\"v1\":\"test value 1\",\"v2\":\"test value 2\",\"v3\":\"test value 3\",\"v4\":\"test value 4\"}",
  "primaryColor": "#0B3D5C",
  "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`
`merchantCustomerId`	String	No	Some merchant value.
`orderItems`	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
`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

#

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.

Payment Cancellation Response #

When the customer clicks the Cancel button on the AMWAL Pay checkout page, the customer is redirected to the configured cancelUrl.

AMWAL Pay sends the payment result as URL query parameters. The following response is returned when the customer cancels the payment:

Sample Cancellation Response #

isSuccess=false
&message=Payment+cancelled
&status=Cancelled+by+customer
&statusId=4
&amount=1.501
&currency=OMR
&currencyId=512
&merchantName=TestMerchant
&merchantId=182132
&terminalId=603876
&merchantReference=322
&responseCode=304
&requestSource=1001
&udf=%7B%22v1%22%3A%22test+value+1%22%2C%22v2%22%3A%22test+value+2%22%2C%22v3%22%3A%22test+value+3%22%2C%22v4%22%3A%22test+value+4%22%7D
&secureHashValue=CE678314A2EFA96B3DE19AB3EFC20BA99A42C00304B186AAB224892C0B67F479

Response Parameters #

Field Name	Type	Description	Sample Value
`isSuccess`	Boolean	Indicates whether the payment was successful. This is `false` when the customer cancels the payment.	`false`
`message`	String	General payment result message.	`Payment cancelled`
`status`	String	Provides the reason/status of the payment result.	`Cancelled by customer`
`statusId`	Integer	Numeric identifier representing the payment status.	`4`
`amount`	Decimal	Payment amount.	`1.501`
`currency`	String	Currency used for the transaction.	`OMR`
`currencyId`	Integer	Numeric currency identifier.	`512`
`merchantName`	String	Merchant name associated with the payment.	`BabarMerchant`
`merchantId`	Integer	AMWAL Pay merchant identifier.	`182117`
`terminalId`	Integer	Terminal identifier used for the payment.	`603876`
`merchantReference`	String	Merchant’s order/payment reference.	`322`
`responseCode`	String	Response code returned for the canceled payment.	`304`
`requestSource`	Integer	Identifies the source of the payment request.	`1001`
`udf`	String / JSON	Merchant-defined user data. The value is URL-encoded in the callback.	`{"v1":"test value 1",...}`
`secureHashValue`	String	HMAC secure hash used to verify the authenticity and integrity of the callback response.	`CE678314A2EF...`

#

Callback Response #

After the payment process is completed, AMWAL Pay redirects the customer to the merchant’s configured callback/return URL.

Sample Callback Response #

isSuccess=true&message=AUTHORIZED&transactionId=ceb693a5-21b8-4be7-ae84-63e09dc451f8&transactionTypeDisplayName=Purchase&amount=1.501&merchantName=TestMerchant&transactionTime=07%2F09%2F2026%2C+10%3A45%3A13+AM&transactionDateTime=2026-09-07T10%3A45%3A13.3344599Z&merchantId=182132&terminalId=603571&transactionTypeId=2&currencyId=512&responseCode=00&merchantReference=2463&customerId=45c6c848-8c8e-405b-b3cf-fba95322c08d&customerTokenId=1b9433c7-17fd-4aac-850f-1cf03bd9bf88&udf=%7B%22v1%22%3A%22test+value+1%22%2C%22v2%22%3A%22test+value+2%22%2C%22v3%22%3A%22test+value+3%22%2C%22v4%22%3A%22test+value+4%22%7D&gatewayTransactionReference=016153570198200&rrn=624906200281&receiptNumber=624906200281&cardNumber=400000******0002&cardType=Visa&authCode=293030&authCode=290677&requestSource=1001&sessionId=91805821-40d1-4c92-8194-2b4c7ca5af46&secureHashValue=E48313AB4E011EAB89D774CEA50BE65994803FD36BA8EE7C8AD5C13782ADD386

Callback Parameters #

Field Name	Type	Description	Sample Value
`isSuccess`	Boolean	Indicates whether the payment transaction was successful.	`true`
`message`	String	Transaction status message returned by AMWAL Pay.	`AUTHORIZED`
`transactionId`	String	Unique identifier of the transaction.	`516412d2-3e35-4c30-aa8a-43788c1cf873`
`transactionTypeDisplayName`	String	Display name of the transaction type.	`Purchase`
`amount`	Decimal	Transaction amount.	`1.501`
`merchantName`	String	Name of the merchant.	`Pets Shop`
`udf`	String (JSON)	User-defined field containing custom merchant data passed during payment initialization.	`{"v1":"test value 1","v2":"test value 2","v3":"test value 3","v4":"test value 4"}`
`transactionTime`	String	Oman time (UTC+4): Date and time when the transaction was processed.	`25/08/2026, 10:39:45 AM`
transactionDateTime	String	(UTC): Date and time when the transaction was processed.	2026-08-26T13:22:12.2021424Z
`merchantId`	Numeric	Unique identifier of the merchant.	`40522`
`terminalId`	Numeric	Unique identifier of the terminal used for the transaction.	`104431`
`transactionTypeId`	Numeric	Identifier of the transaction type.	`2`
`currencyId`	Numeric	Numeric currency identifier. `512` represents OMR.	`512`
`responseCode`	String	Response code returned by AMWAL Pay. `00` indicates a successful authorization.	`00`
`merchantReference`	String	Unique payment/order reference provided by the merchant.	`1581`
`customerId`	String	Unique customer identifier. Available only when the Save Card option is enabled.	`b1d26da2-d580-4464-b3b0-362b30714dc6`
`customerTokenId`	String	Token identifier associated with the customer’s saved card. Available only when the Save Card option is enabled.	`f9222110-f7fc-4859-ae62-225baca831c6`
`gatewayTransactionReference`	String	Unique transaction reference generated by the payment gateway.	`016153570198200`
`rrn`	String	Retrieval Reference Number associated with the transaction.	`623606308855`
`requestSource`	Numeric	Identifies the source through which the transaction was initiated.	`1001`
`sessionId`	String	Unique session identifier associated with the payment session.	`377093e0-dc76-48f1-9e0b-6d0a1fb9e68f`
receiptNumber	Numeric	Unique receipt number associated with the payment	624915651668
cardNumber	Numeric	Card number used for payment	400000******0002
cardType	String	Card type used for payment	Visa
authCode	Numeric	Authorization code	293030
`secureHashValue`	String	HMAC secure hash used to verify the integrity and authenticity of the callback response.	`80207610C23F3AA5E846EE3D8AB145EDBD0C3A8B005F8B7F23D188C5AE08C3FD`

Save Card: customerId and customerTokenId are returned only when the Save Card option is enabled for the payment. When Save Card is not enabled, these fields may not be included in the callback response.

Callback Response Parameters Used for Hash #

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

}

Secure Hash Generation #

secureHashValue is required for Initialize Payment requests.

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

Hash Generation Steps #

Collect all request body fields.
Exclude secureHashValue.
Exclude fields whose value is null.
Sort the field names alphabetically.
Convert each field into key=value.
Join the fields using &.
Calculate HMAC-SHA256 using the Merchant Secure Hash Key.
Treat the configured secret as hexadecimal and convert it to bytes before HMAC.
Convert the resulting digest to uppercase hexadecimal.
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",
    "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.
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.

Updated on September 7, 2026

What are your Feelings

Happy
Normal
Sad

Endpoint #

Environments #

Full Endpoint URLs #

Overview #

Authentication & Credentials #

Request #

Headers #

Initialize Payment Request #

Request Body #

Request Parameters #

Order Items #

#

Success Response #

Response Parameters #

Payment URL #

Payment URL Lifecycle #

URL Expiration #

Payment Cancellation Response #

Sample Cancellation Response #

Response Parameters #

#

Callback Response #

Sample Callback Response #

Callback Parameters #

Callback Response Parameters Used for Hash #

Secure Hash Generation #

Hash Generation Steps #

Example Hash Input #

Node.js Example #

cURL Example #

UAT #

Production #

Response Handling #

Error Handling #

Common Integration Errors #

Invalid Secure Hash #

Incorrect Currency #

Expired Payment URL #

Integration Flow #

Implementation Checklist #

Important Notes #

Share This Article :

Support

Resources

Company