مكتبة خادم إيصالات لـ PHP

التثبيت

composer require esaalat/esaalat-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

تحقق من الـ Webhook

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);

ما تتولاه الحزمة عنك

• •رمز الوصول مخزّن — رمز واحد لكل عملية، يُجدَّد قبل دقيقة من exp داخل الـ JWT، فلا تبدأ طلباتك بالفشل عند انتهاء الساعة.
• •مفتاح التكرار تلقائي — مفتاح واحد لكل إنشاء، يُستخدم نفسه في كل محاولة إعادة: لا يمكن لـ 429 أو انتهاء المهلة أن ينشئ الطلب مرتين.
• •إعادة المحاولة — على 429 و5xx وفشل الشبكة، مع احترام Retry-After.
• •أخطاء مصنّفة — كل خطأ يحمل رمزاً وحالة HTTP والحقل المتسبب وأخطاء الحقول التي يعيدها الـ API.
• •لخادمك فقط — لا يصل إلى المتصفح إلا رمز الجلسة. أما سر العميل فيبقى على خادمك حيث يجب أن يكون.

الإعدادات

قبل أن تنطلق

• •Client::fromEnv() يقرأ بيئة العملية و$_ENV/$_SERVER، فيُلتقط ملف .env الذي يحمّله Laravel أو Symfony.
• •ext-curl مُقترح لا مطلوب: من دونه تستخدم الحزمة streams في PHP.
• •المبالغ بالريال اليمني كأرقام صحيحة، وClient::formatAmount(5000.5) يرفض قبل إرسال الطلب.