Refund an Installment

The Amwal Installment API allows for both partial and full refunds of installment transactions using a transaction ID. This ID is generated upon payment completion and is crucial for processing refunds.

Transaction ID in Refunds

Generated at Payment Completion: A unique transaction ID (UUID) is issued when a payment is completed.
Required for Refunds: This transaction ID must be included in any refund request.
Supports Partial & Full Refunds:
- Partial Refund: Specify a refund amount that is less than the original transaction.
- Full Refund: Set the refund amount equal to the original transaction amount.

API Endpoint

POST /transactions/refund/{transaction_id}/

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

Request Parameters

Parameter	Type	Required	Description
`transaction_id`	string (UUID)	✅	Unique transaction ID for the refund
`refund_amount`	number	✅	Amount to refund (must be > 0 and ≤ original transaction)

Request Examples

Full Refund:
```
{
  "refund_amount": 299.99
}
```
Partial Refund:
```
{
  "refund_amount": 150.00
}
```

Success Response

{
  "status": "success",
  "key_type": "RefundReference", 
  "key": "2025001773"
}

Field	Description
`status`	Status of the refund process
`key_type`	Type of reference key provided
`key`	Refund reference number for tracking

Error Responses (400)

Possible errors include:

Transaction not refundable
Insufficient merchant account balance

Developer Guidelines

Store the transaction ID after payment completion for future refunds or transaction details.
Choose between partial or full refunds based on business needs.
Monitor the response status to confirm refund success.

Important Notes

sufficient balance: Merchants must have a sufficient account balance in order to process refunds.
Online Refunds: Typically take 3–5 business days.
Bank Installments: Processing time varies, usually 5-7 business days.
Minimum Requirements: Original transaction must be ≥ 1,000 SAR for bank installment refunds.
Partial Refunds: Useful for order modifications and returns.
Reference Tracking: Keep the refund reference key for customer service.