Overview #

The Refund Payment API allows merchants to refund an eligible transaction.

A successful refund request creates a refund transaction against the specified original transaction and returns the refund transaction details, including the transaction identifier, host response information, merchant details, amount, currency, and customer token information when applicable.

---

Environment #

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

---

Endpoint #

POST

/Execute/Refund

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 original transaction to be refunded. 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 refund request was generated.	2023-03-08T20:51:38.401Z
terminalId	Yes	Numeric	Maximum 30 characters	Terminal ID initiating the refund request.	140052
merchantId	Yes	Numeric	Maximum 30 characters	Merchant ID initiating the refund request.	1345
currencyCode	Yes	String	Length: 2–4	Currency code used for the refund.	512
amount	Yes	Numeric	Length: 1–9	Amount to be refunded.	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 refund transaction details are returned in the data object.

Sample Success Response #

{
    "success": true,
    "responseCode": "00",
    "message": "Success",
    "data": {
        "systemTraceNr": null,
        "message": "CAPTURED - ",
        "transactionId": "8d5a303b-20ba-42db-aa49-bd97e0793add",
        "isOtpRequired": false,
        "hostResponseData": {
            "TransactionId": "202432805080506",
            "Rrn": "432880000007",
            "TrackId": "8d5a303b20ba42dbaa49bd97e0793add",
            "PaymentId": "-1",
            "Auth": "506414"
        },
        "terminalId": 221143,
        "transactionTypeId": 4,
        "transactionTypeDisplayName": "Refund",
        "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 refund 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 refund transaction.	Object
errorList	String Array	List of errors. This should be empty for a successful response.	[]

---

Refund Transaction Details #

Field	Type	Description	Example
data.systemTraceNr	String	System trace number associated with the refund transaction.	null
data.message	String	Message describing the transaction result.	CAPTURED
data.transactionId	String	Unique identifier of the refund transaction.	8d5a303b-20ba-42db-aa49-bd97e0793add
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.	4
data.transactionTypeDisplayName	String	Display name of the transaction type based on the Accept-Language header.	Refund
data.merchantId	Numeric	Merchant identifier associated with the refund.	7921
data.currency	String	Currency used to execute the refund.	OMR
data.amount	Numeric	Amount refunded.	1
data.currencyId	Numeric	Currency identifier used for the refund.	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.	202432805080506
data.hostResponseData.Rrn	String	Retrieval Reference Number associated with the refund.	432880000007
data.hostResponseData.TrackId	String	Track identifier associated with the refund transaction.	8d5a303b20ba42dbaa49bd97e0793add
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.	506414

Example #

"hostResponseData": {
    "TransactionId": "202432805080506",
    "Rrn": "432880000007",
    "TrackId": "8d5a303b20ba42dbaa49bd97e0793add",
    "PaymentId": "-1",
    "Auth": "506414"
}

---

Failure Response #

If the transaction cannot be refunded, 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 refund 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 cannot be refunded again.

---

Refund Flow #

The Refund Payment process follows these steps:

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

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

---

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