Louis Innovations has released an open source Magento 2 module for SADAD Payment Gateway, enabling enterprise e-commerce operations in Qatar to accept local card payments and QPay transactions through their Magento stores. The module integrates with Magentos native checkout flow, supports authorize-and-capture workflows, and logs all transaction activity in the Magento admin panel.
Installation via Composer
The module is distributed through Packagist under the namespace louisinnovations/magento2-sadad. Install it via Composer in your Magento 2 root directory:
composer require louisinnovations/magento2-sadad
php bin/magento module:enable LouisInnovations_Sadad
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento cache:flush
After installation, the module registers itself as a new payment method and appears in the Magento admin panel under Stores > Configuration > Sales > Payment Methods.
Configuration in Admin Panel
Navigate to Stores > Configuration > Sales > Payment Methods and locate the SADAD payment method section. Configure the following fields:
- Enabled: Set to Yes to activate the payment method
- Title: Display name shown at checkout (e.g., "Credit Card / SADAD")
- Merchant ID: Your SADAD merchant identifier provided by QNB
- API Key: The secret API key for authentication
- Environment: Select Sandbox for testing or Production for live transactions
- Payment Action: Authorize Only or Authorize and Capture
- Order Status: Select the order status for successful payments (default: Processing)
The module also supports minimum order amount thresholds and specific customer group restrictions, configurable through the standard Magento payment method interface.
Payment Flow Implementation
The module implements Magento 2s payment method interface using a gateway command pattern. When a customer places an order, the following sequence executes:
class SadadGatewayCommand implements CommandInterface
{
public function execute(array $commandSubject)
{
$payment = $commandSubject['payment']->getPayment();
$amount = $commandSubject['amount'];
$sadadClient = $this->sadadClientFactory->create();
$transaction = $sadadClient->createTransaction([
'amount' => $amount,
'orderId' => $payment->getOrder()->getIncrementId(),
'currency' => 'QAR',
'customerEmail' => $payment->getOrder()->getCustomerEmail(),
]);
$payment->setTransactionId($transaction->getId());
$payment->setIsTransactionPending(true);
$payment->setAdditionalInformation('sadad_transaction_id', $transaction->getId());
return $this;
}
}
The customer is redirected to the SADAD hosted payment page. Upon completion, SADAD sends a callback to the configured return URL, and the module processes the response using an observer on the checkout_onepage_controller_success_action event.
Event Observers for Order Status Updates
The module registers Magento event observers to handle post-payment workflows:
<!-- etc/events.xml -->
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<event name="sadad_payment_callback_received">
<observer name="sadad_update_order_status" instance="LouisInnovations\Sadad\Observer\UpdateOrderStatus"/>
</event>
<event name="sales_order_payment_refund">
<observer name="sadad_process_refund" instance="LouisInnovations\Sadad\Observer\ProcessRefund"/>
</event>
</config>
The UpdateOrderStatus observer checks the transaction status from the SADAD API and transitions the Magento order to the appropriate state: Processing for success, Canceled for failure, or Pending Payment for transactions awaiting confirmation.
Transaction Management
All SADAD transactions are logged in a dedicated database table and visible in the Magento admin under Sales > SADAD Transactions. The grid displays transaction ID, order ID, amount, currency, status, and timestamps. Admin users can manually inquire about transaction status or initiate refunds directly from the transaction grid.
The module also includes a cron job that reconciles pending transactions every 15 minutes, querying the SADAD API for status updates on any order stuck in a pending payment state. This ensures orders are automatically finalized even if the customers browser closes during the redirect to the SADAD payment page.
Frequently Asked Questions
Q: Does the module support Magento 2.4.x?
Yes. The module is tested on Magento 2.4.4 through 2.4.7. It requires PHP 8.1 or later and uses Magento native APIs without deprecated methods.
Q: Can I customize the payment form appearance?
The module uses the SADAD hosted payment page for PCI compliance, so the payment form itself is not customizable. However, the module supports custom success and failure page URLs that you can set in the admin configuration.
Q: How are partial refunds handled?
Partial refunds are supported through Magento's native credit memo workflow. When you create a credit memo for an order, the module automatically sends a partial refund request to the SADAD API.
Q: Does this work with Magento's multi-store setup?
Yes. The module is multi-store compatible. You can configure different SADAD merchant accounts for different store views, which is useful for businesses operating under multiple brands. For custom enterprise configurations, contact us through our web development services.