This API retrieves orders associated with a specific merchantReference.

1. Environments #

Note: Complete all development and certification against the UAT environment. Switch to the production URL only after AMWAL Pay confirms production enablement for this API on your merchant profile.

2. Endpoint #

HTTP Method: POST

Path:

/GetOrderByMerchantReference

UAT #

https://test.amwalpg.com:14443/GetOrderByMerchantReference

Production #

https://webhook.amwalpg.com/GetOrderByMerchantReference

3. Prerequisites #

Before using this API, ensure that:

• You have an active AMWAL Pay merchant account.
• A valid numeric merchantId is available.
• Your merchant is enabled to use the required webhook/API functionality.
• A valid merchant secure-hash key has been provided by AMWAL Pay.
• Requests are sent over HTTPS.
• The request uses Content-Type: application/json.

4. Headers #

5. Request #

The request requires the merchant ID, merchant reference, request timestamp, and a valid secureHashValue.

Sample Request #

{
    "merchantId": 182121,
    "merchantReference": "344223",
    "requestDateTime": "20260824105500",
    "secureHashValue": "YOUR_SECURE_HASH"
}

Request Parameters #

6. Secure Hash Generation #

Every request must include a valid secureHashValue.

Hash Input #

Exclude secureHashValue from the hash calculation.

The fields should be sorted alphabetically and concatenated in the following format:

merchantId={merchantId}&merchantReference={merchantReference}&requestDateTime={requestDateTime}

For the sample request:

merchantId=182117&merchantReference=344223&requestDateTime=20260824105500

Generate an HMAC-SHA256 hash using the merchant secure-hash key and convert the resulting digest to uppercase hexadecimal.

Example:

{
    "secureHashValue": "YOUR_GENERATED_HASH"
}

Security: Never expose or store the merchant secure-hash key in client-side JavaScript, mobile applications, or other publicly accessible code.

7. API Response #

The API returns a standard response envelope containing the matching orders in the data array.

A single merchantReference may return multiple orders.

Sample Successful Response #

{
    "success": true,
    "responseCode": null,
    "message": "Success",
    "data": [
        {
            "orderId": "4ef3bb32-d320-42fc-8466-edc5cdfd85df",
            "orderIdN": 27000,
            "orderKey": "4QNJ8KOMG5",
            "merchantReference": "432",
            "amount": 1.501,
            "currency": 512,
            "currencyName": "OMR",
            "isPaid": true,
            "status": "Paid",
            "expireDateTime": "2026-09-01T19:22:14.731558",
            "payerName": "",
            "requestDateTime": "2026-09-03T16:48:11.163431",
            "captureDatetime": "2026-09-03T16:51:44.371479",
            "serviceDescription": null,
            "udf": "{\"v1\":\"test value 1\",\"v2\":\"test value   2\",\"v3\":\"test value 3\",\"v4\":\"test value 4\"}",
            "receiptNumber": "624915651668",
            "cardNumber": "40000000*****002",
            "cardType": "VISA",
            "authCode": "293030"
        }
    ],
    "errorList": null
}

8. Response Parameters #

8.1 Response Envelope #

8.2 Order Object #

Each object inside the data array represents an order.

#

11. cURL Example #

UAT #

curl --location 'https://test.amwalpg.com:14443/GetOrderByMerchantReference' \
--header 'Content-Type: application/json' \
--data '{
    "merchantId": 182131,
    "merchantReference": "344223",
    "requestDateTime": "20260824105500",
    "secureHashValue": "YOUR_SECURE_HASH"
}'

Production #

curl --location 'https://webhook.amwalpg.com/GetOrderByMerchantReference' \
--header 'Content-Type: application/json' \
--data '{
    "merchantId": 182131,
    "merchantReference": "344223",
    "requestDateTime": "20260824105500",
    "secureHashValue": "YOUR_SECURE_HASH"
}'