Troubleshooting & Issue Resolution
Welcome to the Amwal Tech Diagnostic Center. This section contains step-by-step playbooks to diagnose, resolve, and prevent issues across customer checkouts, bank installment approvals, API integrations, webhooks, and e-commerce plugins.
Quick Diagnostic Matrix
Use the matrix below to identify your issue and jump straight to the relevant guide:
Payments & Checkout
Declined bank installments, credit vs. debit card eligibility, passkey biometric failures, and expired payment links.
API & Webhooks
401/403 authentication mismatches, HMAC signature verification failures, webhook delivery retries, and rate limits.
E-Commerce Plugins
Shopify widget display issues, WooCommerce order status synchronization, and Magento 2 module configuration.
Merchant Portal & Settlement
Settlement payout schedules (T+2), rolling reserve holds, refund balance requirements, and 2FA recovery.
Common Error Codes Reference
| Error Code | HTTP Status | Typical Cause | Resolution |
|---|---|---|---|
INSTALLMENT_NOT_ELIGIBLE | 400 | Card is a standard Mada debit or prepaid card. | Installments require a supported Saudi credit card. |
MIN_AMOUNT_NOT_MET | 400 | Transaction amount is below the bank minimum (SAR 100). | Increase order value or offer 1-click pay in full. |
UNAUTHORIZED_MERCHANT | 401 | Secret key mismatch or missing X-Amwal-Key header. | Verify credentials in Merchant Portal -> API Keys. |
INVALID_SIGNATURE | 403 | Webhook signature verification failed or payload altered. | Verify using Amwal public RSA key and raw unparsed payload via RSA-PSS SHA-256. |
LINK_ALREADY_USED | 410 | Single-use payment link was already completed. | Generate a new payment link via REST API. |
RATE_LIMIT_EXCEEDED | 429 | More than 100 requests/minute from a single API key. | Implement exponential backoff or use webhooks. |
INSUFFICIENT_MERCHANT_BALANCE | 422 | Merchant float balance is insufficient to cover a refund. | Top up balance or wait for pending settlement cycle. |
Getting Technical Support
If your issue is not listed or requires direct engineering assistance, reach out directly to the Amwal Support Engineering Team:
Direct Escalation Channels
- Developer WhatsApp Support:
+966 57 373 7043(Instant response during business hours) - Technical Support Email:
support@amwal.tech - Merchant Onboarding & Sales:
sales@amwal.tech - Merchant Portal Live Chat: Available at merchant.sa.amwal.tech