Laravel Alinma Pay

Laravel integration for Alinma Pay payment gateway. It provides a small, framework-friendly API for creating payment requests, redirecting customers to the gateway, verifying encrypted callbacks, and inquiring about transactions.

This package is not affiliated with or officially maintained by Alinma Bank. You must have an active Alinma Pay merchant account and valid gateway credentials.

Requirements

• PHP 8.0 or newer
• Laravel 8, 9, 10, 11, or 12
• PHP OpenSSL extension
• An Alinma Pay merchant account

Installation

composer require mohammedradwan3/laravel-alinma-pay
php artisan vendor:publish --tag=alinmapay-config

Laravel package discovery registers the service provider automatically. If your application disables package discovery, register MohammedRadwan3\AlinmaPay\AlinmaPayServiceProvider::class manually.

Configuration

Add your credentials to .env:

ALINMAPAY_ENV=sandbox
ALINMAPAY_TERMINAL_ID=your-terminal-id
ALINMAPAY_PASSWORD=your-password
ALINMAPAY_MERCHANT_KEY=your-merchant-key
ALINMAPAY_CURRENCY=SAR
ALINMAPAY_PAYMENT_METHOD=DCI
ALINMAPAY_TIMEOUT=60

Use production only after completing your gateway testing:

ALINMAPAY_ENV=production

Never commit credentials, .env, or merchant keys to Git.

Create a payment

The simplest option is the facade:

use MohammedRadwan3\AlinmaPay\Facades\AlinmaPay;

$payment = AlinmaPay::createPayment([
    'amount' => 100.00,
    'order_id' => 'ORDER-123',
    'description' => 'Order payment',
    'customer' => [
        'email' => 'customer@example.com',
        'phone' => '966500000000',
        'city' => 'Riyadh',
    ],
    'user_data' => ['order_id' => 123],
]);

if ($payment['success']) {
    return redirect()->away($payment['redirect_url']);
}

return back()->withErrors($payment['message'] ?: 'Unable to create payment.');

The response contains:

[
    'success' => true,
    'payment_id' => 'ORDER-123',
    'gateway_transaction_id' => '...',
    'redirect_url' => 'https://...',
    'response' => [...],
    'message' => '...',
]

Verify the gateway callback

Create a route in your application. The callback endpoint must be publicly reachable by Alinma Pay:

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;
use MohammedRadwan3\AlinmaPay\Facades\AlinmaPay;

Route::match(['get', 'post'], '/payments/alinmapay/callback', function (Request $request) {
    $payment = AlinmaPay::verifyCallback($request);

    if ($payment['success']) {
        // Find the order using $payment['payment_id'].
        // Mark it as paid only after this verification succeeds.
    }

    return response()->json($payment);
});

If the endpoint is protected by Laravel CSRF middleware, exclude it from CSRF verification or expose it as an API route.

Transaction inquiry

$result = AlinmaPay::inquire(
    transactionId: $gatewayTransactionId,
    orderId: 'ORDER-123',
    amount: 100.00,
    customer: ['email' => 'customer@example.com', 'phone' => '966500000000'],
    description: 'Order payment inquiry',
);

Dependency injection

For services and larger applications, inject the client instead of using the facade:

use MohammedRadwan3\AlinmaPay\AlinmaPayClient;

public function __construct(private AlinmaPayClient $alinmaPay) {}

public function pay()
{
    return $this->alinmaPay->createPayment(['amount' => 100]);
}

Optional package callback route

You can enable the package route in .env:

ALINMAPAY_ROUTES_ENABLED=true

This registers POST /alinmapay/callback. For most applications, a custom route is recommended so you can update your own order model after verification.

Security and production checklist

• Keep all credentials in environment variables.
• Use HTTPS for callback URLs.
• Verify the callback before marking an order as paid.
• Make callback processing idempotent; gateways may retry callbacks.
• Test successful, failed, cancelled, and duplicated callbacks in Sandbox.
• Confirm the callback URL and merchant key with Alinma Pay before production use.

Local development

git clone https://github.com/MohammedRadwan3/laravel-alinma-pay.git
cd laravel-alinma-pay
composer validate

License

This package is open-sourced software licensed under the MIT license.