Troubleshooting Magento 2 Integration

This diagnostic guide covers common issues when installing, configuring, or upgrading the official Amwal Payments module on Adobe Commerce (Magento 2).

1. Module Compilation or DI Errors

Symptom

Running bin/magento setup:di:compile fails with Class Amwal\Payment\Model\... does not exist or Interception cache generation failed.

Resolution

Execute the full clean compilation sequence from your Magento root directory:

# 1. Ensure module is registered
php bin/magento module:enable Amwal_Payments

# 2. Update database schemas
php bin/magento setup:upgrade

# 3. Clean generated code and caches
rm -rf generated/code/* generated/metadata/* var/cache/* var/page_cache/* var/view_preprocessed/*

# 4. Re-compile Dependency Injection
php bin/magento setup:di:compile

# 5. Deploy static view files
php bin/magento setup:static-content:deploy -f

# 6. Flush cache
php bin/magento cache:flush

2. Credit Memo & Online Refund Failures

Symptom

Clicking Refund inside a Magento Credit Memo displays an error or fails to credit the customer.

Root Causes & Fixes

1. Missing or Invalid Secret Key:

   • Online refunds require your private Secret Key (not the public Merchant ID).
   • Go to Stores → Configuration → Sales → Payment Methods → Amwal and confirm the Secret Key field is populated.

2. Online vs. Offline Refund Selection:

   • Clicking Refund Offline only records a credit memo in Magento's database and does not notify the Amwal gateway or reverse customer funds.
   • Always click the orange Refund button to trigger automatic gateway reversals. See Magento Online Refunds.

3. SAMA Scheme Timeframe Expiration:

   • Mada Cards: SAMA limits debit card scheme reversals to 30 days from original authorization.
   • Visa / Mastercard: Reversals permitted up to 60 days.
   • If an order is older than the scheme limit, you must issue an offline manual bank transfer to the customer.

3. Orders Stuck in "Pending Payment"

Symptom

Customer completes bank installment authorization, but the order remains in Pending Payment in Magento Admin.

Resolution

1. Verify Magento Cron Job Execution:
   • Amwal runs an automated hourly background task to synchronize pending orders. Verify your server's cron is running:

   php bin/magento cron:run

2. Inspect Amwal Logs:
   • Check var/log/amwal.log and var/log/system.log for gateway synchronization errors or 3DS timeout responses.
3. Verify Webhook Status:
   • Navigate to Stores → Configuration → Sales → Payment Methods → Amwal → Webhooks Setting.
   • Ensure Enable Webhooks is set to Yes and Private Key Status displays ✓ Private key is securely stored.

4. Installments or Apple Pay Hidden on Checkout

Symptoms

• 0% Bank Installments does not appear in checkout.
• Apple Pay button does not render on Safari / iOS devices.

Checklist

5. Multi-Store Scoping & Merchant ID Mismatches

Symptom

Transactions in Store View B are credited to Store View A's Merchant Account.

Root Cause

Configuration was applied at the "Default Config" global level instead of individual Website or Store View scopes.

Resolution

1. In Magento Admin, go to Stores → Configuration → Sales → Payment Methods → Amwal.
2. In the top-left Scope selector, choose your specific Saudi Store View.
3. Uncheck Use Default and enter the distinct Merchant ID and Secret Key provisioned for that store entity.
4. Save and flush cache (bin/magento cache:flush).

Related Guides