SADAD Payment Gateway Package for Laravel PHP Framework

Louis Innovations has released a comprehensive Laravel package for SADAD Payment Gateway integration, purpose-built for the Qatar market. The package follows Laravel conventions including facades, service providers, events, and middleware, making it feel like a native part of the framework. It supports checkout, refund, transaction inquiry, and Instant Payment Notification (IPN) handling.

Installation and Service Registration

Install the package via Composer from Packagist:

composer require louisinnovations/laravel-sadad

The package is auto-discovered by Laravel's package discovery system. After installation, publish the configuration file:

php artisan vendor:publish --provider="LouisInnovations\Sadad\SadadServiceProvider"

This publishes a config/sadad.php configuration file where you set your merchant credentials:

return [
    'merchant_id' => env('SADAD_MERCHANT_ID'),
    'api_key' => env('SADAD_API_KEY'),
    'environment' => env('SADAD_ENV', 'sandbox'),
    'currency' => env('SADAD_CURRENCY', 'QAR'),
    'callback_url' => env('SADAD_CALLBACK_URL', '/sadad/callback'),
];

Using the Facade

The package provides a Sadad facade for accessing all payment operations:

use LouisInnovations\Sadad\Facades\Sadad;

// Create a payment request
$transaction = Sadad::createTransaction([
    'amount' => 250.00,
    'order_id' => 'ORD-2026-001',
    'customer_email' => 'customer@example.com',
    'description' => 'Premium Service Package',
]);

// The response contains a payment URL for redirect
return redirect($transaction->payment_url);

Additional facade methods include inquireTransaction($transactionId) for checking payment status, processRefund($transactionId, $amount) for issuing refunds, and verifySignature($payload) for validating IPN callbacks.

Handling Instant Payment Notifications

SADAD sends IPN callbacks to a configured endpoint after payment processing. The package includes a dedicated IPN controller and route macro:

// In routes/api.php or routes/web.php
Route::sadadIpn();

// Or manually define the route
Route::post('/sadad/ipn', 'SadadIpnController@handle');

The IPN handler validates the HMAC signature, updates the transaction record, and dispatches Laravel events:

use LouisInnovations\Sadad\Events\PaymentReceived;
use LouisInnovations\Sadad\Events\PaymentFailed;

// These events are dispatched automatically
event(new PaymentReceived($transaction, $order));
event(new PaymentFailed($transaction, $order, $reason));

Create listeners for these events to update your order status, send confirmation emails, or trigger fulfillment workflows.

Eloquent Models for Transaction Logging

The package ships with an Eloquent model and migration for persisting transaction records:

php artisan migrate

The sadad_transactions table stores every payment attempt with the following schema:

Schema::create('sadad_transactions', function (Blueprint $table) {
    $table->id();
    $table->string('transaction_id')->unique();
    $table->string('order_id');
    $table->decimal('amount', 10, 2);
    $table->string('currency', 3)->default('QAR');
    $table->string('status'); // pending, success, failed, refunded
    $table->json('raw_response')->nullable();
    $table->timestamps();
});

use LouisInnovations\Sadad\Models\SadadTransaction;

$transaction = SadadTransaction::where('order_id', 'ORD-2026-001')->first();
echo $transaction->status; // success

Middleware for Signature Verification

Protect your callback routes with the included signature verification middleware:

// In App\Http\Kernel.php
protected $routeMiddleware = [
    'sadad.signature' => \LouisInnovations\Sadad\Http\Middleware\VerifySadadSignature::class,
];

// In routes
Route::post('/sadad/callback', [SadadController::class, 'callback'])
    ->middleware('sadad.signature');

This middleware validates the HMAC-SHA256 signature on incoming SADAD requests, rejecting any request that does not match the expected signature computed from the shared API key.

Frequently Asked Questions

Q: Does the package support Laravel 11?

Yes. The package is compatible with Laravel 10 and 11. It requires PHP 8.2 or later and leverages Laravels latest service container and event features.

Q: Can I use multiple SADAD merchant accounts?

Yes. The facade supports named connections. Configure multiple accounts in config/sadad.php under a connections array and use Sadad::connection('secondary')->createTransaction(...).

Q: How are failed payment retries handled?

The package does not automatically retry failed payments. Instead, it dispatches a PaymentFailed event with the failure reason. You can implement retry logic in your listener, or redirect the customer back to the checkout page. For applications handling recurring billing, our enterprise software services include subscription payment solutions.

Q: Does this package support QPay alongside card payments?

Yes. The package supports both SADAD card payments and QPay. Pass the payment_method parameter in the createTransaction call with a value of card or qpay. The SADAD gateway handles the rest.