Configuration

📘

Prerequisites

If you don't yet have Amwal Merchant account (either SANDBOX or PRODUCTION), please refer to our Amwal Integration Key guide to get started.

Complete the required configuration steps to enable Amwal Payments checkout functionality in your Magento store.

⚙️ Access Configuration

Navigate to Stores > Configuration > Sales > Payment methods in your Magento admin panel. Find the "Amwal" section under "Other payment methods".

❗ Required Setup

1. Enable the Plugin

Set "Enabled" to Yes to activate Amwal Payments.

2. Configure Merchant Settings

Merchant ID: Enter your Merchant ID from https://merchant.sa.amwal.tech/. Use "Verify Merchant ID" to confirm it's correct.

Module Type: Choose your version:

• Pro: Enables all the features of the Amwal extension, including payment options available at the product level (PDP), category level (PLP), and the standard checkout process.
• Lite: A simplified version of the module that only works with the regular checkout process, disabling other features such as payments from product and category pages.

Secret Key: Enter your authentication key. Keep this secure and contact support if compromised.

Installment URL: This is the URL to the installment options page. This page will be displayed to the customer when they click the “Installments” button on the checkout page. Please ensure that this URL is correct and that the page is accessible to your customers.

🎨 Visual settings

Title: Name displayed during checkout (e.g., "Amwal Installments")

Dark Mode:

• Off: Black button with white text
• On: White button with black text

Style CSS: Add custom CSS to style the checkout button. This is useful if you want to change the size, color, or font of the button. You can also use this to hide the button on certain pages. For example, if you want to hide the button on the cart page, you can add the following CSS:

.amwal-express-checkout-button.product-detail-page,  .box-tocart .action.tocart{
    width: 70%;
}

@media (max-width: 767px) {
    .amwal-express-checkout-button.product-detail-page {
        width: unset;
    }

    .catalog-product-view .hydrated center {
        text-align: right;
        background: #fff;
        position: fixed;
        bottom: 0;
        left: 0;
        z-index: 9999;
        width: 100%;
    }
    .button-text {
        padding-left: 0 !important;
    }
    .products-grid .product-item-actions .amwal-express-checkout-button {
        width: 90% !important;
    }
   
   .ribbon~.button-text{
        font-size: 10px !important;
    }
}

.product-item-actions .actions-primary, .actions-secondary{
  width: 100%;
}

Discount Ribbon: When set to “On” a ribbon will be displayed on the checkout button to indicate that a discount is available. When set to “Off” the ribbon will not be displayed. Adjust this to fit the look and feel of your store.

💳 Installment Configuration

Custom Installments Redirect URL: The URL to which the user should be redirected after selecting the installment option. Note: Make sure to include either the http:// or https:// protocol.

Bank Installments: Available for orders ≥1,000 SAR. See Bank Installments page for details.

🏷️ Promotions Setup

Discount Rule: Select applicable discount (e.g., "25% Off")

Credit Card BIN Codes: Enter eligible card BIN codes (comma-separated: "545454, 424242, 411111")

Promotion Display Options:

• Enable promotion widget on product pages
• Enable promotion widget on shopping cart

📦 Order Management

Order Confirmed Status: Magento status for successful Installment

Create Customer on Order: Auto-create customer accounts for new orders

Email Notifications:

• Send customer emails on status changes by the Magento cron job
• Send admin emails on status changes by the Magento cron job

🌍 Country Specific Setting

1. Payment from Applicable Countries Indicated if the payment method should be available for all countries, or a selected list of countries. To limit the allowed countries set this option to “Specific countries”

2. Payment from Specific Countries If the “Payment from Applicable Countries” is set to “Specific countries” you can select the countries that should be allowed to use the Amwal checkout option here.

⏱️CronJob Setting

This is specifically designed to periodically check and update the status of orders that are currently marked with a 'Pending Payment' status. By running at regular intervals, this automated process ensures timely updates, reducing manual intervention and helping maintain accurate and up-to-date order status information in the system..

Frequency Cron Job Frequency is 1 hours.

Jobs 1. Update Pending Orders This job retrieves all orders that are currently marked with a 'Pending Payment' status from -1 hour. It then checks the status of these orders with the payment gateway and updates the order status accordingly.

2. Update Canceled Orders

This job retrieves all orders that are currently marked with a 'Canceled' status from -1 hour. It then checks the status of these orders with the payment gateway and updates the order status accordingly.

🔗 Webhooks Setting

1. Enable Webhooks Set to "Yes" to activate webhook notifications for your store.

2. Webhook Endpoint URL This is your store's webhook endpoint that will receive notifications.

3. Webhook Events

Available Webhook Events:

• Order Success
• Order Failed

Choose the events that will trigger the webhook.

4. Create Amwal Webhook API Key Click to create a new Webhook API key from Amwal and configure webhook integration.

5. API Key Fingerprint This will be automatically populated when you create an Webhook API key.

6. Private Key Status This field displays the current status of your private key. If your key has been successfully stored, you will see the message: "✓ Private key is securely stored."

7. Debug Mode Enable detailed logging for webhook events.

💳 Installment Methods

Amwal Apple Pay

The Amwal Apple Pay Installment method allows customers to complete their purchases using Apple Pay. This feature is designed to enhance the user experience by providing a quick and secure Installment option.

Amwal Apple Pay is only available on the regular checkout page.

Amwal Bank Installments

The Amwal Bank Installments method allows customers to make purchases using installment plans. This option is only available during the regular checkout process.

Development Settings

1. Debug mode If enabled this option will log additional information during the checkout process. Should be disabled in production environments and only be activated for debugging purposes.

2. Report errors to Sentry If enabled, this option will report any errors that occur during the checkout process to Amwal sentry.

3. PWA Mode If you are using any PWA frameworks this setting will help you much as you can as headless integration.

4. Quote override If enabled, will override certain quote data. Use only if you are having issues related to quote amounts or currencies.

After completing configuration, save your settings and test the payment process to ensure proper functionality.