Troubleshooting Declined Installments

When a customer attempts to select a 3, 6, 12, or 24-month installment plan, the issuing Saudi bank performs real-time credit checks. If the bank declines the installment request, follow the diagnostic steps below.

Common Decline Reasons & Root Causes

1. Insufficient Credit Card Limit

• Symptom: The customer's bank rejects the authorization with code DECLINED_INSUFFICIENT_FUNDS or LIMIT_EXCEEDED.
• Reason: The full purchase amount is blocked against the customer's credit card limit while monthly payments are billed over time. If the customer's available credit is less than the total purchase amount, the bank declines the request.
• Resolution:
  • Advise the customer to verify their available balance via their bank mobile app.
  • Suggest splitting payments or paying in full using 1-Click Checkout.

2. Non-Partner Bank Credit Card

• Symptom: The bank selection modal does not list the customer's bank or displays BANK_NOT_SUPPORTED.
• Reason: Amwal currently supports credit cards issued by participating Saudi partner banks (e.g., Al Rajhi Bank, SNB, Alinma Bank, Riyad Bank). Corporate cards, international credit cards, and non-partner banks are ineligible for 0% installment promotions.
• Resolution:
  • Guide the customer to select a card issued by an active partner bank.
  • Review the list of live partner banks in Integration & API Keys.

3. Minimum Basket Value Threshold

• Symptom: Installment options are disabled or greyed out.
• Reason: Saudi Central Bank (SAMA) and partner banks mandate a minimum transaction threshold of SAR 100 for installment plans.
• Resolution:
  • Orders below SAR 100 are automatically routed to standard 1-Click Pay in Full.

4. 3D Secure / OTP Timeout

• Symptom: Checkout spins indefinitely or returns 3DS_AUTHENTICATION_TIMEOUT.
• Reason: The customer took longer than 3 minutes to enter the SMS OTP sent by their issuing bank, or the bank's SMS gateway was delayed.
• Resolution:
  • Instruct the customer to click "Resend OTP" or retry the checkout session.

Verifying Decline Reason in Merchant Portal

To view the exact failure reason returned by the bank:

1. Log in to Amwal Merchant Portal.
2. Navigate to Transactions -> Transaction History.
3. Locate the transaction ID or customer phone number.
4. Click on the transaction to expand the Bank Gateway Response Payload.
5. Check the failure_code and failure_reason fields.