Overview #

The Void Payment API allows merchants to cancel an eligible transaction.

A successful void request reverses the specified transaction and returns the details of the void transaction, including the transaction identifier, host response information, merchant details, amount, and currency.

---

Environment #

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

---

Endpoint #

POST

/Execute/Void

Content Type #

application/json

---

Request #

Request Headers #

Header	Required	Value
Content-Type	Yes	application/json

Request Method #

POST

Sample Request #

{
    "transactionId": "41d196b9-c487-43b6-a7f5-dd6beeba9fdb",
    "transactionIdentifierValue": "fea3ac40-8362-4ef6-8695-91ee08b05163",
    "transactionIdentifierType": 2,
    "requestDateTime": "2023-03-08T20:51:38.401Z",
    "terminalId": 221143,
    "merchantId": 7921,
    "currencyCode": 512,
    "amount": 1,
    "secureHashValue": "84EB3BF8F62EF25717D1E9E13C3CFB719A890980BBF2631AFD8965182ADE1754"
}

---

Request Parameters #

Field	Required	Type	Constraints	Description	Example
transactionId	Yes	String	Maximum 256 characters	Unique identifier of the transaction.	41d196b9-c487-43b6-a7f5-dd6beeba9fdb
transactionIdentifierValue	Yes	GUID / Numeric	Maximum 32 characters	Identifier of the transaction that is being voided. The value can represent either the transaction numeric ID or GUID depending on transactionIdentifierType.	fea3ac40-8362-4ef6-8695-91ee08b05163
transactionIdentifierType	Yes	Numeric	Maximum 1 character	Specifies the type of identifier provided in transactionIdentifierValue.	2
requestDateTime	Yes	String	Valid UTC date/time	Date and time when the transaction request was generated.	2023-03-08T20:51:38.401Z
terminalId	Yes	Numeric	Maximum 30 characters	Terminal ID initiating the transaction.	140052
merchantId	Yes	Numeric	Maximum 30 characters	Merchant ID initiating the transaction.	1345
currencyCode	Yes	String	Length: 2–4	Currency code used for the transaction.	512
amount	Yes	Numeric	Length: 1–9	Amount of the transaction being voided.	3000.50
secureHashValue	Yes	String	Maximum 256 characters	Secure hash value used to validate the integrity and authenticity of the request.	3DB2F9CB975DADB533A2068F5C2911F9CCFF8AA0DFF3F92

---

Transaction Identifier Type #

The transactionIdentifierType determines which type of transaction identifier is supplied in transactionIdentifierValue.

Value	Identifier Type	Description
1	Transaction IDN	The numeric transaction identifier is provided.
2	Transaction GUID	The GUID transaction identifier is provided.

Example #

For a GUID transaction identifier:

{
    "transactionIdentifierValue": "fea3ac40-8362-4ef6-8695-91ee08b05163",
    "transactionIdentifierType": 2
}

---

Response #

Successful Response #

A successful request returns success: true and response code 00.

The transaction result is returned in the data object.

Sample Success Response #

{
    "success": true,
    "responseCode": "00",
    "message": "Success",
    "data": {
        "systemTraceNr": null,
        "message": "VOIDED - ",
        "transactionId": "7a0baaff-99e1-46a8-a0bf-e2d5241c1031",
        "isOtpRequired": false,
        "hostResponseData": {
            "TransactionId": "202432895186454",
            "Rrn": "432880000005",
            "TrackId": "7a0baaff99e146a8a0bfe2d5241c1031",
            "PaymentId": "-1",
            "Auth": null
        },
        "terminalId": 221143,
        "transactionTypeId": 3,
        "transactionTypeDisplayName": "الغاء بيع",
        "merchantId": 7921,
        "currency": "OMR",
        "amount": 1,
        "currencyId": 512,
        "customerId": null,
        "customerTokenId": null
    },
    "errorList": []
}

---

Response Parameters #

General Response #

Field	Type	Description	Example
success	Boolean	Indicates whether the void request was successfully processed.	true
responseCode	String	Response code returned by the API.	00
message	String	General response message.	Success
data	Object	Contains the details of the void transaction.	Object
errorList	String Array	List of errors. This should be empty for a successful response.	[]

---

Void Transaction Details #

Field	Type	Description	Example
data.systemTraceNr	String	System trace number associated with the transaction.	null
data.message	String	Message describing the transaction result.	VOIDED
data.transactionId	String	Unique identifier of the void transaction.	7a0baaff-99e1-46a8-a0bf-e2d5241c1031
data.isOtpRequired	Boolean	Indicates whether OTP verification is required.	false
data.terminalId	Numeric	Unique identifier of the terminal used.	221143
data.transactionTypeId	Numeric	Identifier of the transaction type.	3
data.transactionTypeDisplayName	String	Display name of the transaction type based on the Accept-Language header.	الغاء بيع
data.merchantId	Numeric	Merchant identifier associated with the transaction.	7921
data.currency	String	Currency used to execute the transaction.	OMR
data.amount	Numeric	Amount of the void transaction.	1
data.currencyId	Numeric	Currency identifier used for the transaction.	512
data.customerId	String	Customer identifier associated with the transaction, when applicable.	null
data.customerTokenId	String	Customer token identifier associated with the transaction, when applicable.	null

---

Host Response Data #

The data.hostResponseData object contains information returned by the payment host.

Field	Type	Description	Example
data.hostResponseData.TransactionId	String	Transaction identifier assigned by the payment host.	202432895186454
data.hostResponseData.Rrn	String	Retrieval Reference Number associated with the transaction.	432880000005
data.hostResponseData.TrackId	String	Track identifier associated with the transaction.	7a0baaff99e146a8a0bfe2d5241c1031
data.hostResponseData.PaymentId	String	Payment identifier returned by the payment host.	-1
data.hostResponseData.Auth	String	Authorization code returned by the payment host, when applicable.	null

Example #

"hostResponseData": {
    "TransactionId": "202432895186454",
    "Rrn": "432880000005",
    "TrackId": "7a0baaff99e146a8a0bfe2d5241c1031",
    "PaymentId": "-1",
    "Auth": null
}

---

Failure Response #

If the transaction cannot be voided, the API returns success: false along with the failure information.

Sample Failure Response #

{
    "success": false,
    "responseCode": null,
    "message": "APGEX: bcaed933e7fb",
    "data": null,
    "errorList": [
        "Can not Refund or void an already Refunded Transaction"
    ]
}

---

Failure Response Parameters #

Field	Type	Description	Example
success	Boolean	Indicates whether the void request was successfully processed.	false
responseCode	String	Response code returned by the API.	02
message	String	Response or error message describing the failure.	APGEX: bcaed933e7fb
data	Object	Transaction data. This is null when the request fails.	null
errorList	String Array	List containing one or more errors describing the failure.	["Can not Refund or void an already Refunded Transaction"]

---

Common Failure Example #

Transaction Already Refunded #

{
    "success": false,
    "responseCode": null,
    "message": "APGEX: bcaed933e7fb",
    "data": null,
    "errorList": [
        "Can not Refund or void an already Refunded Transaction"
    ]
}

This error indicates that the transaction has already been refunded and therefore cannot be voided.

---

Transaction Flow #

The Void Payment process follows these steps:

1. Identify the transaction that needs to be voided.
2. Provide the appropriate transaction identifier in transactionIdentifierValue.
3. Set transactionIdentifierType according to the identifier being provided.
4. Provide the merchant, terminal, currency, and transaction amount.
5. Generate the required secureHashValue.
6. Submit the request to the Execute/Void endpoint.
7. The API validates the request and determines whether the transaction is eligible for voiding.
8. If successful, the API returns the void transaction details and host response information.
9. If the transaction cannot be voided, the API returns the relevant error information.

Important: A transaction that has already been refunded cannot be voided.

Note: Use the appropriate merchant credentials and environment-specific configuration when switching between UAT and Production.