Initiate Refund

The Initiate Refund process allows merchants to request a refund for a completed transaction by providing the paymentId and refund amount. The payment gateway processes the refund and returns a status with any relevant error messages if the refund fails.

Request Parameters

Parameter	Mandatory	Description	Type	Example
paymentId	Yes	Unique identifier of the payment transaction to be refunded.	String	"051ca748-14e2-4507-a39a-e45a28afc10b"
amount	Yes	The amount to refund.	Numeric	100.00

Example Request

curl --location --request POST '{{baseUrl}}/transaction/refund' \
--header 'Authorization: Basic <base64-encoded-clientId:clientSecret>' \
--header 'X-Signature: <generated_signature>' \
--header 'X-MERCHANT-BROWSER-FINGERPRINT: 8357426ac73fcd60b17355ab7de60421' \
--header 'X-MERCHANT-USER-AGENT: <user-agent>' \
--header 'X-MERCHANT-DOMAIN: https://www.xyz.com' \
--header 'X-MERCHANT-IP: 123.123.123.123' \
--data-raw '{
  "paymentId": "051ca748-14e2-4507-a39a-e45a28afc10b",
  "amount": 100.00
}'

Success Response

To ensure the integrity and authenticity of the refund request, it is crucial to verify the HMAC signature before processing the refund status update (described in Signature Verification for Payment Response).

{
  "resCode": 200,
  "status": "success",
  "data": {
    "refundId": "ref123456789",
    "paymentId": "pay798378b8c272451f90cb2b491a86ed17",
    "orderId": "wb-70c20048-9dc8-4fc3-858e-0a3a5c742190",
    "receiptId": "R12345678910",
    "paymentStatus": "success",
    "paymentMethod": "card",
    "amount": 100.00,
    "currency": "OMR",
    "initiatedAt": "2025-05-29T07:21:19.845Z",
    "completedAt": "2025-05-29T07:21:19.846Z",
    "signature": "10ff8c4ddbeb8fcf24fcc110acb31599690a8057ecd3a7141b22354f9b73337f"
  }
}

Failure Responses

ResCode	Status	Description
409	failure	Refund has already been initiated for this payment
400	failure	Amount mismatch
403	failure	Refunds are currently not allowed for this transaction due to platform restrictions
400	failure	Refund failed
401	failure	Missing Authorization header
401	failure	Invalid or inactive client credentials
404	failure	Transaction not found for paymentId
422	failure	Invalid paymentId or transaction not in success state
500	failure	Internal Server Error