Troubleshooting Refund Failures & Adjustments

Merchants can issue full or partial payment refunds via the Amwal Merchant Portal or programmatically via the Refund Installment API. If a refund attempt fails, follow this diagnostic guide.

1. "Insufficient Balance for Supplier"

Error Response

{
  "message": "Your balance is not sufficient to initiate any refund process. You can retry when you have a balance exceeding the amount you are trying to refund.",
  "validation_errors": [{ "Name": "Supplier", "Error": "Insufficient balance for supplier" }]
}

Root Cause

When a refund is initiated, Amwal deducts the refund principal directly from your unsettled processing balance. If your daily settlement has already been transferred to your corporate IBAN, your available gateway balance may be zero.

Resolution

• Wait for incoming customer sales volume to accumulate in your balance before retrying, OR
• Contact Amwal Merchant Operations to request an adjustment.

2. SAMA Card Scheme Reversal Timeframe Expiration

Error Response

{
  "detail": "This transaction is not refundable"
}

Root Cause

Under Saudi Central Bank (SAMA) banking regulations, card schemes impose strict eligibility windows for direct electronic reversals:

• Mada Debit Cards: Eligible for electronic reversal within 30 days of authorization.
• Visa & Mastercard: Eligible for card scheme credit reversal within 60 days.
• Bank Installment Plans: Subject to partner bank loan cancellation policies.

Resolution

For orders exceeding these scheme limits, initiate an offline manual bank transfer (via SARIE) to the customer and record the note in your store administration panel.

3. "The Transaction Is Already Under Processing"

Error Response

{
  "message": "The transaction is already under processing!",
  "validation_errors": [{ "Name": "Key", "Error": "The transaction is already under processing!" }]
}

Root Cause

A transient lock is placed on a transaction while an initial refund request communicates with the card scheme network.

Resolution

Wait 10–15 seconds before retrying. Do not send rapid duplicate refund requests for the same transaction ID.

4. Partial Refund Mechanics for 0% Bank Installments

When you refund a portion of a bank installment purchase (e.g. refunding 300 SAR on a 1,200 SAR 6-month plan):

• Customer Notification: The customer does not receive cash; instead, their issuing bank (Al Rajhi, SNB, Alinma, Riyad Bank) automatically adjusts their remaining monthly installment schedule or issues a credit to their card account.

Programmatic API Example

Refunds can also be triggered via the REST API. Note that transaction_id is passed as a URL path parameter with a trailing slash:

curl -X POST "https://backend.sa.amwal.tech/transactions/refund/60b43176-5991-4475-8ef6-c73c2417c805/" \
  -H "Authorization: YOUR_SECRET_KEY" \
  -H "X-Amwal-Key: YOUR_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "refund_amount": 150.00,
    "reason": "Customer returned 1 item from invoice"
  }'

Related Guides