Idempotency Refunds

Use idempotency to safely refund payments without creating duplicate refunds.

How idempotency works

Send an unique Idempotency-Key in the request header.
Include an unique order_refund_id in the request body.
Avoid using the same refund request with the same Idempotency-Key and order_refund_id values.

❗️
Important
Do not reuse the same Idempotency-Key and order_refund_id for different refund requests. Amwal will reject subsequent requests that reuse these values incorrectly.

This feature helps you:

Prevent duplicate refund requests.
Avoid completing the same payment or refund more than once.

API Endpoint

POST /transactions/refund/{transaction_id}/

To refund a specific installment transaction, provide the transaction ID, refund amount, and idempotency values.

Request Parameters

Parameter	Type	Required	Description
`transaction_id`	string (UUID)	✅	Unique Amwal transaction ID.
`refund_amount`	number	✅	Amount to refund. Must be > 0 and ≤ the original transaction amount.
`order_refund_id`	string (UUID)	✅	Unique order refund ID required for an idempotent refund request.

Request Examples

Use the Idempotency-Key header with each refund request.

Full refund

Header:

Idempotency-Key: refund-22b58269-5b24-53bb-9ca5-b57757395d03

Request body:

{ 
  "refund_amount": 100,
  "order_refund_id": "22b58269-5b24-53bb-9ca5-b57757395d03"
}

Partial refund

Header:

Idempotency-Key: refund-22b58269-5b24-53bb-9ca5-b57757395d04

Request body:

{ 
  "refund_amount": 1,
  "order_refund_id": "22b58269-5b24-53bb-9ca5-b57757395d04"
}