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
Before escalating, try asking Amwal Integration, Amwal's AI integration assistant. You can connect it to Claude Code, Cursor, or Claude Desktop via MCP and ask it about a specific error code, header, or field name without leaving your editor.
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