Get Transaction by Merchant Reference

Retrieve Purchase transaction details using the merchant reference associated with the transaction.

1. Environments #

Environment	Base URL	Full Endpoint
UAT / Test	`https://test.amwalpg.com:14443`	`https://test.amwalpg.com:14443/Transaction/GetByMerchantReference`
Production	`https://webhook.amwalpg.com`	`https://webhook.amwalpg.com/Transaction/GetByMerchantReference`

Note: Complete all development and certification against the UAT environment. Switch to the Production base URL only after AMWAL Pay confirms that this API has been enabled for your merchant profile.

2. Prerequisites #

Before using this API, ensure that:

Your merchant account is active and enabled for webhook APIs.
You have a valid numeric merchantId.
You have received a Merchant Secure Hash Key from AMWAL Pay.
The secure-hash key is provided as a hex-encoded HMAC key.
GetByMerchantReference is enabled in your merchant’s webhook API list.
Requests are sent over HTTPS.
The request body uses application/json.

3. Authentication & Secure Hash #

Every request must include a valid secureHashValue.

The gateway rejects requests when:

secureHashValue is missing.
The hash is invalid.
The request timestamp is stale.
The merchant is not authorized to use the API.
The API is not enabled for the merchant.

3.1 Secure Hash Algorithm #

Generate the secureHashValue using the following process:

Collect all JSON request fields except secureHashValue.
Exclude fields with null values.
Sort the field names in ascending alphabetical order.
Concatenate the fields using the format:

key1=value1&key2=value2&key3=value3

Calculate HMAC-SHA256 using the merchant secure-hash key.
Decode the merchant secure-hash key from hex to bytes before using it.
Convert the resulting digest to uppercase hexadecimal.
Send the resulting value as secureHashValue.

3.2 Fields Included in the Hash #

For a standard request, the hash string is:

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

The alphabetical field order is:

merchantId
merchantReference
requestDateTime

For example:

merchantId=123456&merchantReference=ORD-001&requestDateTime=20260824105500

Important: Hash only the fields that you send in the request. Do not hash a gateway-generated or enriched request envelope.

3.3 Request Date Time #

The requestDateTime must use the following format:

yyyyMMddHHmmss

Example:

20260824105500

The timestamp should be close to the current UTC time. Stale timestamps may be rejected as part of replay protection.

Security: Never expose or log your secure-hash key in client-side applications.

4. Endpoint Specification #

Property	Value
HTTP Method	`POST`
Path	`/Transaction/GetByMerchantReference`
Content-Type	`application/json`
Success HTTP Status	`200`

UAT #

https://test.amwalpg.com:14443/Transaction/GetByMerchantReference

Production #

https://webhook.amwalpg.com/Transaction/GetByMerchantReference

5. Request #

Send only the following fields in the request body.

5.1 Request Parameters #

Field	Type	Required	Description
`merchantId`	Number	Yes	AMWAL Pay merchant identifier. Used to identify the merchant and validate the secure hash.
`merchantReference`	String	Yes	Your order or invoice reference. The value must exactly match the stored transaction merchant reference.
`requestDateTime`	String	Yes	Request timestamp in `yyyyMMddHHmmss` format.
`secureHashValue`	String	Yes	HMAC-SHA256 hexadecimal digest generated according to the secure-hash algorithm.

5.2 Sample Request #

{
  "merchantId": 123456,
  "merchantReference": "ORD-001",
  "requestDateTime": "20260824105500",
  "secureHashValue": "A1B2C3D4E5F6..."
}

6. Transaction Matching Rules #

After the request is enriched by the gateway, the following rules are applied:

The merchantReference must match exactly.
The transaction is scoped to the authenticated merchant.
Only Purchase transactions are returned.
Results are ordered by idN in descending order.
The highest idN transaction is returned first.

If there are no matching Purchase transactions, the API returns an empty data array.

7. Response #

The response follows the standard AMWAL Pay webhook API response envelope.

7.1 Response Envelope #

Field	Type	Description
`success`	Boolean	Indicates whether the API request was processed successfully.
`responseCode`	String	AMWAL Pay response code. `00` indicates success.
`message`	String	Human-readable response message.
`errorList`	String[]	Validation or processing errors. Empty on success.
`data`	Array	List of matching Purchase transactions.

7.2 Transaction Object #

Each object inside the data array contains transaction information.

Field	Type	Description
`id`	String (GUID)	Unique AMWAL Pay transaction identifier. Use this value with Get Transaction by ID and follow-up transaction operations.
`idN`	Number	Internal numeric transaction identifier.
`transactionTime`	String	Transaction time in the AMWAL Pay default system format.
`transactionDateTime`	DateTime	Transaction timestamp.
`transferDateTime`	DateTime / Null	Date and time when the transaction was transferred/settled. `null` when not transferred.
`amount`	Number	Transaction amount in major currency units.
`totalAmount`	Number	Total transaction amount, including applicable aggregator amounts.
`tips`	Number	Tip amount, when applicable.
`convFees`	Number	Convenience fee, when applicable.
`currencyId`	Number	ISO numeric currency code. For example, `512` = OMR.
`currency`	String	Currency name.
`responseCode`	String	Host or processor response code.
`responseCodeName`	String	Human-readable response description.
`transactionTypeId`	Number	Transaction type identifier. This API returns Purchase transactions.
`transactionType`	String	Transaction type name.
`transactionTypeDisplayName`	String	Localized transaction type display name.
`merchantReference`	String	Merchant reference used in the lookup.
`merchantId`	Number	Merchant identifier.
`merchantName`	String	Merchant name.
`terminalId`	Number	Terminal identifier, when available.
`stan`	String	System Trace Audit Number.
`cardNumber`	String	Masked card number, when applicable.
`cardHolderName`	String	Cardholder name, when available.
`gatewayTransactionReference`	String	Host or gateway transaction reference, such as a processor transaction ID or OmanNet RRN.
`orderId`	String (GUID) / Null	Linked merchant order ID, when the transaction was created from an order.
`isRefunded`	Boolean	Indicates whether a refund has been applied.
`isCaptured`	Boolean	Indicates whether the transaction has been captured.
`isTransferred`	Boolean	Indicates whether settlement/withdrawal has occurred.
`channelType`	Number	Payment channel type.
`methodName`	String	Payment method name.
`amountAvailableForRefundOrCompletion`	Number	Remaining amount available for refund or completion, when applicable.
`transactionActions`	Object	Indicates which transaction actions are currently available.
`hostData`	Object / Null	Host-specific transaction details.
`digitalTransaction`	Object / Null	Digital wallet or other digital transaction details, when applicable.

7.3 Transaction Actions #

The transactionActions object contains the operations currently available for the transaction.

Field	Type	Description
`canRefund`	Boolean	Whether the transaction can be refunded.
`canVoid`	Boolean	Whether the transaction can be voided.
`canCapture`	Boolean	Whether the transaction can be captured.
`canPartialRefund`	Boolean	Whether a partial refund is allowed.
`canPartialVoid`	Boolean	Whether a partial void is allowed.
`canPartialCompletion`	Boolean	Whether a partial completion is allowed.
`canSplitTransaction`	Boolean	Whether the transaction can be split.

8. Sample Responses #

8.1 Successful Response #

The following example shows a successful lookup containing a Purchase transaction:

{
  "success": true,
  "responseCode": "00",
  "message": "Success",
  "errorList": [],
  "data": [
    {
      "id": "8f3c1a2e-4b91-4d77-9c10-2a8e5b6d1c44",
      "idN": 2045821,
      "transactionTime": "24/08/2026 10:12:01",
      "transactionDateTime": "2026-08-24T10:12:01Z",
      "transferDateTime": "2026-08-25T08:30:00Z",
      "amount": 10.500,
      "totalAmount": 10.500,
      "currencyId": 512,
      "currency": "OMR",
      "responseCode": "00",
      "responseCodeName": "Approved",
      "transactionTypeId": 2,
      "transactionType": "Purchase",
      "merchantReference": "ORD-001",
      "merchantId": 123456,
      "stan": "000123",
      "gatewayTransactionReference": "723456789012345",
      "isRefunded": false,
      "isCaptured": true,
      "transactionActions": {
        "canRefund": true,
        "canVoid": false,
        "canCapture": false,
        "canPartialRefund": true,
        "canPartialVoid": false,
        "canPartialCompletion": false,
        "canSplitTransaction": false
      }
    }
  ]
}

Success Response #

A response with:

"success": true,
"responseCode": "00"

indicates that the lookup request was successfully processed.

8.2 Successful Response with No Matching Transaction #

If no Purchase transaction matches the supplied merchantReference, the API still returns a successful response:

{
  "success": true,
  "responseCode": "00",
  "message": "Success",
  "errorList": [],
  "data": []
}

Important: An empty data array is a successful lookup with no matching Purchase transactions. It is not a transport or API error.

9. cURL Examples #

9.1 UAT #

curl -X POST 'https://test.amwalpg.com:14443/Transaction/GetByMerchantReference' \
  -H 'Content-Type: application/json' \
  -d '{
    "merchantId": 123456,
    "merchantReference": "ORD-001",
    "requestDateTime": "20260824105500",
    "secureHashValue": "YOUR_SECURE_HASH"
  }'

9.2 Production #

curl -X POST 'https://webhook.amwalpg.com/Transaction/GetByMerchantReference' \
  -H 'Content-Type: application/json' \
  -d '{
    "merchantId": 123456,
    "merchantReference": "ORD-001",
    "requestDateTime": "20260824105500",
    "secureHashValue": "YOUR_SECURE_HASH"
  }'

Replace the following values with your actual merchant information:

merchantId
merchantReference
requestDateTime
secureHashValue

Generate a new secure hash for every request, because requestDateTime changes for each request.

10. Error Handling #

Situation	Typical Outcome	Recommended Action
Missing or invalid `merchantId`	Gateway rejects the request	Confirm the `merchantId` with AMWAL Pay.
Invalid `secureHashValue`	Gateway rejects the request	Recalculate the HMAC using the exact request fields and verify the secure-hash key.
Replay protection failure	Request rejected	Generate a new `requestDateTime` using the current UTC time.
Stale `requestDateTime`	Request rejected	Use the current UTC timestamp in `yyyyMMddHHmmss` format.
API not enabled	Gateway unauthorized	Ask AMWAL Pay to enable GetByMerchantReference for your merchant webhook profile.
Blank `merchantReference`	Business validation error	Send a non-empty `merchantReference`.
No matching Purchase transaction	HTTP `200`, `success: true`, `data: []`	Treat the response as a successful lookup with no matching transaction.

Updated on August 24, 2026

What are your Feelings

Happy
Normal
Sad