Esaalat server SDK for PHP

PHP 8.1+

Create the checkout session, attach the buyer's reference and verify signed webhooks from plain PHP, Laravel or Symfony. PHP 8.1+, curl or streams, no dependencies.

Install

composer require esaalat/esaalat-php

Create the session

index.php

use Esaalat\Client;

// Reads ESAALAT_CLIENT_ID, ESAALAT_CLIENT_SECRET and ESAALAT_WEBHOOK_SECRET.
$esaalat = Client::fromEnv();

$session = $esaalat->createSession([
    'orderId' => 'order-12345',
    'amount'  => 5000,          // whole riyals
]);

// $session['session_token'] → open the checkout from your page
// $session['portal_url']    → or redirect the buyer straight to it

Verify the webhook

webhook.php

try {
    $event = $esaalat->verifyWebhook(
        file_get_contents('php://input'),                 // the RAW body
        $_SERVER['HTTP_X_ESAALAT_SIGNATURE'] ?? ''
    );
} catch (\Esaalat\EsaalatException $error) {
    http_response_code(400);                              // anything but 2xx retries
    exit;
}

if ($event['event'] === 'payment.verified') {
    releaseOrder($event['order_id']);                     // idempotent on intent_id
}
http_response_code(200);

Verify the signature over the raw body. Re-serializing it changes the bytes and the signature will not match — which is the correct outcome, because a re-serialized body proves nothing.

What it handles for you

•Token cached — One token per process, refreshed from the JWT's own exp a minute early, so an integration does not start returning 401s at the hour boundary.
•Idempotency automatic — One key per create call, reused on every retry: a 429 or a timeout cannot create the same order twice.
•Retries — 429, 5xx and network failures, honouring Retry-After.
•Typed errors — Every failure carries a code, the HTTP status, the offending field and the API's per-field errors.
•Server-only — Only the session token reaches the browser. The client secret stays on your server, where it belongs.

Configuration

Argument	Environment variable	Default
`$clientId`	`ESAALAT_CLIENT_ID`	required
`$clientSecret`	`ESAALAT_CLIENT_SECRET`	required
`$webhookSecret`	`ESAALAT_WEBHOOK_SECRET`	needed by `verifyWebhook`
`$baseUrl`	`ESAALAT_BASE_URL`	`https://api.esaalat.com/api/v1`
`$timeout`	`—`	`20` seconds
`$maxRetries`	`—`	`2`

Before you go live

•Client::fromEnv() reads the process environment and $_ENV/$_SERVER, so a .env file loaded by Laravel or Symfony is picked up.
•ext-curl is suggested, not required: without it the client falls back to PHP streams.
•Amounts are whole Yemeni riyals; Client::formatAmount(5000.5) refuses before the request is sent.

Merchant API reference

Create the session

index.php

use Esaalat\Client;

// Reads ESAALAT_CLIENT_ID, ESAALAT_CLIENT_SECRET and ESAALAT_WEBHOOK_SECRET.
$esaalat = Client::fromEnv();

$session = $esaalat->createSession([
    'orderId' => 'order-12345',
    'amount'  => 5000,          // whole riyals
]);

// $session['session_token'] → open the checkout from your page
// $session['portal_url']    → or redirect the buyer straight to it

Verify the webhook

webhook.php

try {
    $event = $esaalat->verifyWebhook(
        file_get_contents('php://input'),                 // the RAW body
        $_SERVER['HTTP_X_ESAALAT_SIGNATURE'] ?? ''
    );
} catch (\Esaalat\EsaalatException $error) {
    http_response_code(400);                              // anything but 2xx retries
    exit;
}

if ($event['event'] === 'payment.verified') {
    releaseOrder($event['order_id']);                     // idempotent on intent_id
}
http_response_code(200);

Verify the signature over the raw body. Re-serializing it changes the bytes and the signature will not match — which is the correct outcome, because a re-serialized body proves nothing.

What it handles for you

•Token cached — One token per process, refreshed from the JWT's own exp a minute early, so an integration does not start returning 401s at the hour boundary.

•Idempotency automatic — One key per create call, reused on every retry: a 429 or a timeout cannot create the same order twice.

•Retries — 429, 5xx and network failures, honouring Retry-After.

•Typed errors — Every failure carries a code, the HTTP status, the offending field and the API's per-field errors.

•Server-only — Only the session token reaches the browser. The client secret stays on your server, where it belongs.

Argument

Environment variable

Default

$clientId

ESAALAT_CLIENT_ID

required

$clientSecret

ESAALAT_CLIENT_SECRET

required

$webhookSecret

ESAALAT_WEBHOOK_SECRET

needed by verifyWebhook

$baseUrl

ESAALAT_BASE_URL

https://api.esaalat.com/api/v1

$timeout

—

20 seconds

$maxRetries

—

2

Before you go live

•Client::fromEnv() reads the process environment and $_ENV/$_SERVER, so a .env file loaded by Laravel or Symfony is picked up.

•ext-curl is suggested, not required: without it the client falls back to PHP streams.

•Amounts are whole Yemeni riyals; Client::formatAmount(5000.5) refuses before the request is sent.