SADAD Payment Gateway SDK for PHP - Open Source Qatar Fintech

Louis Innovations has released an open source PHP SDK for SADAD Payment Gateway, providing a clean, PSR-compliant interface for processing Qatar payments. The SDK is MIT-licensed and available on Packagist, supporting web checkout, transaction inquiry, refunds, and invoice generation. It is designed for any PHP 8.1+ application including plain PHP projects, Laravel, Symfony, and WordPress.

SDK Architecture

The SDK follows a service-oriented architecture with clear namespace separation. The root namespace is LouisInnovations\SadadPhp with the following structure:

src/
  Client.php              - Main HTTP client
  Config.php              - Configuration manager
  Exceptions/
    SadadException.php    - Base exception
    AuthenticationException.php
    ValidationException.php
    GatewayException.php
  Models/
    Transaction.php       - Transaction value object
    Refund.php            - Refund value object
    PaymentRequest.php    - Request builder
  Services/
    PaymentService.php    - Transaction creation and processing
    RefundService.php     - Refund processing
    InquiryService.php    - Transaction status queries
  Security/
    Signature.php         - HMAC-SHA256 signature handling

Install via Composer:

composer require louisinnovations/sadad-php-sdk

Making API Calls to SADAD Endpoints

Initialize the client with your merchant credentials and make payment requests:

use LouisInnovations\SadadPhp\Client;
use LouisInnovations\SadadPhp\Config;
use LouisInnovations\SadadPhp\Models\PaymentRequest;

$config = new Config([
    'merchant_id' => getenv('SADAD_MERCHANT_ID'),
    'api_key' => getenv('SADAD_API_KEY'),
    'environment' => 'sandbox', // or 'production'
]);

$client = new Client($config);

$paymentRequest = (new PaymentRequest())
    ->setAmount(150.00)
    ->setCurrency('QAR')
    ->setOrderId('ORD-2026-089')
    ->setCustomerEmail('customer@example.com')
    ->setCallbackUrl('https://yourdomain.com/sadad/callback');

$transaction = $client->payment()->create($paymentRequest);

header('Location: ' . $transaction->getPaymentUrl());

The SDK maps all SADAD API endpoints to service methods. Each service method returns strongly-typed value objects rather than raw arrays, providing IDE autocompletion and type safety.

Handling HMAC Signatures

SADAD uses HMAC-SHA256 signatures for request and callback authentication. The SDK includes a dedicated signature handler:

use LouisInnovations\SadadPhp\Security\Signature;

$signature = new Signature($config->getApiKey());

// Verify incoming IPN callback
$payload = file_get_contents('php://input');
$receivedSignature = $_SERVER['HTTP_X_SADAD_SIGNATURE'];

if (!$signature->verify($payload, $receivedSignature)) {
    http_response_code(403);
    echo 'Invalid signature';
    exit;
}

// Decode and process the verified payload
$data = json_decode($payload, true);
$status = $data['transaction_status'];

Error Handling

The SDK defines a hierarchy of exception classes for granular error handling:

use LouisInnovations\SadadPhp\Exceptions\{
    AuthenticationException,
    ValidationException,
    GatewayException,
    SadadException,
};

try {
    $transaction = $client->payment()->create($paymentRequest);
} catch (AuthenticationException $e) {
    // Invalid merchant credentials - check your config
    logError('SADAD auth failed: ' . $e->getMessage());
} catch (ValidationException $e) {
    // Request validation failed - check error details
    foreach ($e->getErrors() as $field => $message) {
        echo "Field $field: $message\n";
    }
} catch (GatewayException $e) {
    // SADAD gateway returned an error
    echo 'Payment gateway error: ' . $e->getMessage();
} catch (SadadException $e) {
    // Generic SDK error
    echo 'SDK error: ' . $e->getMessage();
}

Unit Testing with PHPUnit

The SDK ships with PHPUnit test suites and a mock HTTP client for testing payment flows without real API calls:

use LouisInnovations\SadadPhp\Tests\MockClient;
use PHPUnit\Framework\TestCase;

class PaymentServiceTest extends TestCase
{
    public function testCreateTransactionReturnsTransactionObject()
    {
        $mockClient = new MockClient([
            'create_transaction_success.json' => [
                'transaction_id' => 'TXN-001',
                'payment_url' => 'https://sandbox.sadad.qa/pay/TXN-001',
                'status' => 'PENDING',
            ],
        ]);

        $service = new PaymentService($mockClient);
        $transaction = $service->create($this->getPaymentRequest());

        $this->assertEquals('TXN-001', $transaction->getId());
        $this->assertEquals('PENDING', $transaction->getStatus());
    }
}

The mock client reads JSON fixture files from a fixtures/ directory, enabling deterministic testing of all success and failure scenarios.

Contributing to the Open Source Project

The SDK is open source under the MIT license. Contributions are welcome through the GitHub repository. The project follows PSR-2 coding standards and uses GitHub Actions for CI. To contribute:

1. Fork the repository and create a feature branch
2. Write tests for your changes
3. Run composer test to verify all tests pass
4. Submit a pull request with a clear description of the change

The SDK follows semantic versioning. Core contributors review pull requests within one week. Feature requests and bug reports can be submitted through the GitHub issues page.

Frequently Asked Questions

Q: Can I use this SDK without a framework?

Yes. The SDK has zero framework dependencies. It only requires PHP 8.1+ with the curl, json, and mbstring extensions. It works in any PHP project, including vanilla PHP, WordPress plugins, and custom frameworks.

Q: Does the SDK support QPay integration?

Yes. The PaymentRequest model includes a setPaymentMethod() method that accepts card or qpay as values. The SDK also supports split payment scenarios where part of the amount is charged to a card and part to QPay.

Q: How do I run the SDK in production?

Set the environment configuration to production and ensure your server has a valid SSL certificate for the callback URL. The SDK enables verbose logging in sandbox mode and suppresses sensitive data logging in production automatically.

Q: What is the refund window for SADAD transactions?

The SADAD gateway supports full and partial refunds within 180 days of the original transaction. The SDKs RefundService validates the refund amount against the original transaction and raises a ValidationException if the refund exceeds the available balance. For custom payment solutions, explore our web development services.