fbrpay/laravel-sdk

FBR-PAY Laravel SDK - Complete integration library for SaaS platforms to manage merchant onboarding, payments, invoices, payouts, settlements, and more

v1.0.2 2026-01-25 18:29 UTC

Requires

• php: ^8.2
• guzzlehttp/guzzle: ^7.0
• illuminate/http: ^10.0|^11.0|^12.0
• illuminate/support: ^10.0|^11.0|^12.0

Requires (Dev)

• orchestra/testbench: ^8.0|^9.0|^10.0
• phpunit/phpunit: ^10.0|^11.0

MIT

• FBR-PAY Team

• payment
• invoice
• laravel
• merchant
• saas
• onboarding
• settlement
• payout
• Moyasar
• fbrpay

README

مكتبة Laravel متكاملة للتكامل مع منصة FBR-PAY. تتيح لمنصات SaaS إدارة رحلة التاجر كاملة من التسجيل إلى استقبال المدفوعات.

المميزات

• إدارة التجار: تسجيل التجار، رفع المستندات، تتبع حالة الطلب
• المدفوعات: إنشاء المدفوعات، الاسترجاعات، الاستعلام عن الرصيد
• Webhooks: استقبال الإشعارات الفورية مع التحقق من التوقيع
• التقارير: تقارير المبيعات، التسويات، العمولات
• التخزين المؤقت: دعم Cache لتحسين الأداء
• Type Safety: DTOs وInterfaces لضمان صحة البيانات

التثبيت

composer require fbrpay/laravel-sdk

الإعداد

1. نشر ملف الإعدادات

php artisan vendor:publish --tag=fbrpay-config

2. إضافة المتغيرات في .env

FBRPAY_PARTNER_KEY=your_partner_key
FBRPAY_PARTNER_SECRET=your_partner_secret
FBRPAY_ENVIRONMENT=sandbox
FBRPAY_WEBHOOK_SECRET=your_webhook_secret

# اختياري
FBRPAY_MERCHANT_KEYS_VISIBLE=false
FBRPAY_DEFAULT_PACKAGE=basic

الاستخدام

1. إدارة التجار (Merchant Onboarding)

إنشاء طلب تسجيل تاجر جديد

use FBRPay\LaravelSDK\Facades\FBRPay;

// إنشاء طلب جديد
$application = FBRPay::merchants()->createApplication([
    'business_name' => 'متجر النجاح',
    'business_name_ar' => 'متجر النجاح',
    'business_type' => 'company', // أو 'freelancer'
    'email' => '[e-mail]',
    'mobile' => '0501234567',
    'cr_number' => '1234567890', // للشركات
    'iban' => 'SA0380000000608010167519',
    'website' => 'https://success-store.com',
    'external_reference' => 'STORE-001', // معرفك الداخلي
]);

echo $application->id; // معرف الطلب
echo $application->applicationNumber; // رقم الطلب
echo $application->status; // حالة الطلب

رفع المستندات

// رفع مستند واحد
$document = FBRPay::merchants()->uploadDocument(
    $application->id,
    'commercial_registration', // نوع المستند
    '/path/to/cr.pdf'
);

// رفع عدة مستندات
$documents = FBRPay::merchants()->uploadDocuments($application->id, [
    ['type' => 'commercial_registration', 'file' => '/path/to/cr.pdf'],
    ['type' => 'owner_id', 'file' => '/path/to/id.pdf'],
    ['type' => 'bank_iban_certificate', 'file' => '/path/to/iban.pdf'],
]);

// رفع مستند بصيغة Base64
$document = FBRPay::merchants()->uploadDocument(
    $application->id,
    'commercial_registration',
    'data:application/pdf;base64,JVBERi0xLjQK...'
);

تقديم الطلب للمراجعة

$application = FBRPay::merchants()->submitApplication($application->id);

متابعة حالة الطلب

// جلب الطلب بالمعرف
$application = FBRPay::merchants()->getApplication($applicationId);

// جلب الطلب بالمرجع الخارجي
$application = FBRPay::merchants()->getApplicationByReference('STORE-001');

// التحقق من الحالة
if ($application->isActivated()) {
    echo "التاجر مفعل! معرف التاجر: " . $application->merchantId;
}

// جلب المستندات المطلوبة
$docs = FBRPay::merchants()->getRequiredDocuments($application->id);
print_r($docs['required']); // المستندات المطلوبة
print_r($docs['submitted']); // المستندات المرفوعة

إدارة التجار المفعلين

// جلب بيانات التاجر
$merchant = FBRPay::merchants()->getMerchant($merchantId);

// قائمة التجار
$result = FBRPay::merchants()->listMerchants([
    'status' => 'active',
    'page' => 1,
    'per_page' => 20,
]);

foreach ($result['data'] as $merchant) {
    echo $merchant->name . ' - ' . $merchant->status;
}

// تعطيل تاجر
$merchant = FBRPay::merchants()->deactivateMerchant($merchantId, 'سبب التعطيل');

// إعادة تفعيل
$merchant = FBRPay::merchants()->reactivateMerchant($merchantId);

2. المدفوعات (Payments)

إنشاء عملية دفع

use FBRPay\LaravelSDK\Facades\FBRPayPayment;

// إنشاء دفعة جديدة
$payment = FBRPayPayment::create($merchantId, [
    'amount' => 10000, // المبلغ بالهللات (100 ريال)
    'description' => 'طلب رقم #12345',
    'callback_url' => 'https://your-app.com/payment/callback',
    'metadata' => [
        'order_id' => '12345',
        'customer_email' => '[e-mail]',
    ],
]);

// توجيه العميل لصفحة الدفع
return redirect($payment->redirectUrl);

التحقق من حالة الدفع

$payment = FBRPayPayment::get($merchantId, $paymentId);

if ($payment->isSuccessful()) {
    // الدفع ناجح
    echo "تم الدفع: " . $payment->getFormattedAmount();
} elseif ($payment->isFailed()) {
    // فشل الدفع
    echo "فشل: " . $payment->failureReason;
}

قائمة المدفوعات

$result = FBRPayPayment::list($merchantId, [
    'status' => 'paid',
    'from_date' => '2024-01-01',
    'to_date' => '2024-12-31',
    'page' => 1,
]);

foreach ($result['data'] as $payment) {
    echo $payment->id . ' - ' . $payment->getFormattedAmount();
}

الاسترجاع (Refund)

// استرجاع كامل
$refund = FBRPayPayment::refund($merchantId, $paymentId);

// استرجاع جزئي
$refund = FBRPayPayment::refund($merchantId, $paymentId, [
    'amount' => 5000, // 50 ريال
    'reason' => 'طلب العميل',
]);

// التحقق من حالة الاسترجاع
if ($refund->isSuccessful()) {
    echo "تم الاسترجاع: " . $refund->getFormattedAmount();
}

الرصيد والتقارير

// جلب الرصيد
$balance = FBRPayPayment::getBalance($merchantId);
echo "الرصيد المتاح: " . $balance->getFormattedAvailable();
echo "الرصيد المعلق: " . $balance->getPendingInSAR();

// ملخص التقارير
$summary = FBRPayPayment::getReportsSummary($merchantId, [
    'from_date' => '2024-01-01',
    'to_date' => '2024-12-31',
]);

// التقرير اليومي
$daily = FBRPayPayment::getDailyReport($merchantId);

// التسويات
$settlements = FBRPayPayment::getSettlements($merchantId);

رابط دفع (Payment Link)

$link = FBRPayPayment::createPaymentLink($merchantId, [
    'amount' => 50000, // 500 ريال
    'description' => 'فاتورة خدمات',
    'expires_at' => now()->addDays(7)->toISOString(),
]);

// إرسال الرابط للعميل
echo $link->url;

3. Webhooks

الإعداد التلقائي

المكتبة تسجل تلقائياً endpoint للـ webhooks على المسار:

POST /fbrpay/webhook

الاستماع للأحداث

// في EventServiceProvider
use FBRPay\LaravelSDK\Events\ApplicationStatusChanged;
use FBRPay\LaravelSDK\Events\PaymentCompleted;
use FBRPay\LaravelSDK\Events\PaymentFailed;
use FBRPay\LaravelSDK\Events\RefundCompleted;

protected $listen = [
    ApplicationStatusChanged::class => [
        \App\Listeners\HandleApplicationStatus::class,
    ],
    PaymentCompleted::class => [
        \App\Listeners\HandlePaymentSuccess::class,
    ],
    PaymentFailed::class => [
        \App\Listeners\HandlePaymentFailure::class,
    ],
];

مثال على Listener

// app/Listeners/HandleApplicationStatus.php
namespace App\Listeners;

use FBRPay\LaravelSDK\Events\ApplicationStatusChanged;

class HandleApplicationStatus
{
    public function handle(ApplicationStatusChanged $event)
    {
        if ($event->isActivated()) {
            // التاجر تم تفعيله
            $merchantId = $event->getMerchantId();
            $externalRef = $event->getExternalReference();

            // تحديث السجل في قاعدة بياناتك
            Store::where('external_ref', $externalRef)
                ->update(['fbrpay_merchant_id' => $merchantId, 'status' => 'active']);
        }

        if ($event->isRejected()) {
            // الطلب مرفوض
            $reason = $event->getRejectionReason();
            // إرسال إشعار للتاجر
        }
    }
}

// app/Listeners/HandlePaymentSuccess.php
namespace App\Listeners;

use FBRPay\LaravelSDK\Events\PaymentCompleted;

class HandlePaymentSuccess
{
    public function handle(PaymentCompleted $event)
    {
        $orderId = $event->getMeta('order_id');
        $amount = $event->getAmountInSAR();

        // تحديث حالة الطلب
        Order::find($orderId)->markAsPaid($amount);
    }
}

تسجيل معالجات مخصصة

use FBRPay\LaravelSDK\Facades\FBRPay;

// في AppServiceProvider::boot()
FBRPay::webhooks()->on('payment.completed', function ($data, $event) {
    // معالجة الدفع الناجح
});

FBRPay::webhooks()->on('application.activated', function ($data, $event) {
    // التاجر تم تفعيله
});

// الاستماع لجميع الأحداث
FBRPay::webhooks()->onAll(function ($data, $event) {
    Log::info("FBRPay Event: {$event}", $data);
});

4. التحقق من الإعدادات

use FBRPay\LaravelSDK\Facades\FBRPay;

// التحقق من صحة الإعدادات
if (FBRPay::isConfigured()) {
    // التحقق من صحة البيانات
    if (FBRPay::verifyCredentials()) {
        echo "الاتصال ناجح!";
    }
}

// معرفة البيئة الحالية
echo FBRPay::environment(); // sandbox أو production

if (FBRPay::isSandbox()) {
    // بيئة الاختبار
}

أنواع المستندات

النوع	الوصف
owner_id	هوية المالك
commercial_registration	السجل التجاري
bank_iban_certificate	شهادة الآيبان البنكي
freelance_certificate	وثيقة العمل الحر
vat_certificate	شهادة ضريبة القيمة المضافة
memorandum_of_association	عقد التأسيس
owner_address	عنوان المالك
company_address	عنوان المنشأة
activity_license	رخصة النشاط
investment_license	رخصة الاستثمار
power_of_attorney	وكالة شرعية
signatory_id	هوية المفوض
signatory_address	عنوان المفوض
official_letter	خطاب رسمي
other	مستندات أخرى

حالات الطلب

الحالة	الوصف
initiated	تم إنشاء الطلب
data_submitted	تم إرسال البيانات
docs_pending	بانتظار المستندات
docs_submitted	تم رفع المستندات
docs_under_review	المستندات قيد المراجعة
sent_to_provider	تم الإرسال للميسر
provider_approved	تمت الموافقة من الميسر
awaiting_payment	بانتظار الدفع
payment_received	تم استلام الدفع
awaiting_nafath	بانتظار نفاذ
activated	مفعل
rejected	مرفوض

حالات الدفع

الحالة	الوصف
initiated	تم إنشاء العملية
pending	قيد الانتظار
paid	تم الدفع
failed	فشل
expired	منتهي
refunded	مسترجع

الأمان

إخفاء مفاتيح API

لمنع التجار من رؤية مفاتيح API الخاصة بهم:

FBRPAY_MERCHANT_KEYS_VISIBLE=false

بهذه الطريقة، المدفوعات تتم فقط عبر منصتك.

التحقق من Webhooks

المكتبة تتحقق تلقائياً من:

• توقيع HMAC-SHA256
• صلاحية التوقيت (5 دقائق افتراضياً)

التخزين المؤقت (Caching)

المكتبة تستخدم Cache لتحسين الأداء:

// في config/fbrpay.php
'cache' => [
    'enabled' => true,
    'prefix' => 'fbrpay_',
    'ttl' => [
        'merchant' => 300,    // 5 دقائق
        'packages' => 3600,   // ساعة
        'balance' => 60,      // دقيقة
    ],
],

معالجة الأخطاء

use FBRPay\LaravelSDK\Exceptions\ApiException;
use FBRPay\LaravelSDK\Exceptions\AuthenticationException;
use FBRPay\LaravelSDK\Exceptions\ValidationException;

try {
    $payment = FBRPayPayment::create($merchantId, $data);
} catch (ValidationException $e) {
    // أخطاء التحقق
    $errors = $e->getErrors();
    foreach ($errors as $field => $messages) {
        echo "{$field}: " . implode(', ', $messages);
    }
} catch (AuthenticationException $e) {
    // خطأ في المصادقة
    echo "خطأ في بيانات الاعتماد: " . $e->getMessage();
} catch (ApiException $e) {
    // خطأ عام من API
    if ($e->isRetryable()) {
        // يمكن إعادة المحاولة
    }
    echo "خطأ: " . $e->getMessage();
}

الترخيص

MIT License

الدعم

• البريد: [e-mail]
• التوثيق: https://docs.fbrpay.com