elryad/payments

Multi-gateway payment package for Laravel - Paymob, Moyasar, Tap

dev-main 2026-02-02 12:48 UTC

Requires

• php: ^8.2
• illuminate/http: ^11.0|^12.0
• illuminate/support: ^11.0|^12.0

Requires (Dev)

• orchestra/testbench: ^10.9
• phpunit/phpunit: ^11.5

MIT

• Elryad

README

حزمة Laravel لبوابات الدفع - Paymob، Moyasar، Tap - قابلة لإعادة الاستخدام في أي مشروع.

البوابات المدعومة

البوابة	الدولة/المنطقة	النطاق
Paymob	مصر، السعودية	تكامل كامل داخل الحزمة
Moyasar	السعودية	تكامل كامل داخل الحزمة
Tap	السعودية، الخليج	تكامل كامل داخل الحزمة
Stripe	عالمي	Adapter + Handler من المشروع
Tamara	السعودية/الخليج	Adapter + Handler من المشروع
Hyperpay	السعودية/الخليج	Adapter + Handler من المشروع
Paytabs	السعودية/الخليج	Adapter + Handler من المشروع

التثبيت

composer require elryad/payments

مزود الخدمة (Service Provider)

• Laravel Auto-Discovery يعمل تلقائياً.
• إن كنت تعطل الـ auto-discovery، أضف المزود يدوياً في bootstrap/providers.php:

Elryad\Payments\PaymentsServiceProvider::class,

نشر الإعدادات (اختياري)

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

نشر الـ Views (اختياري)

php artisan vendor:publish --tag=payments-views

هيكل الحزمة

Elryad\Payments\
├── Gateways\
│   ├── Paymob\      # مصر / السعودية
│   │   ├── PaymobService.php
│   │   ├── Contracts\PaymobPaymentHandlerInterface.php
│   │   └── Http\Controllers\
│   ├── Moyasar\     # السعودية
│   │   ├── MoyasarService.php
│   │   ├── Contracts\MoyasarPaymentHandlerInterface.php
│   │   └── Http\Controllers\
│   └── Tap\         # السعودية / الخليج
│       ├── TapService.php
│       ├── Contracts\TapPaymentHandlerInterface.php
│       └── Http\Controllers\
├── config\payments.php
└── resources\views\moyasar\

الإعداد

Paymob

PAYMOB_API_KEY=
PAYMOB_INTEGRATION_ID=
PAYMOB_HMAC_SECRET=
PAYMOB_IFRAME_ID=
PAYMOB_HANDLER=App\Http\Services\Payment\GiftCardPaymobHandler

Moyasar

MOYASAR_SECRET_KEY=
MOYASAR_PUBLISHABLE_KEY=
MOYASAR_WEBHOOK_SECRET=
MOYASAR_HANDLER=App\Http\Services\Payment\MoyasarHandler
MOYASAR_SUCCESS_REDIRECT=
MOYASAR_FAILED_REDIRECT=

Tap

TAP_SECRET_KEY=
TAP_HANDLER=App\Http\Services\Payment\TapHandler
TAP_SUCCESS_REDIRECT=
TAP_FAILED_REDIRECT=

Stripe

STRIPE_SECRET_KEY=
STRIPE_WEBHOOK_SECRET=
STRIPE_CURRENCY=USD
STRIPE_HANDLER=App\Http\Services\Payment\StripeHandler

Tamara

TAMARA_BASE_URL=
TAMARA_API_KEY=
TAMARA_WEBHOOK_SECRET=
TAMARA_HANDLER=App\Http\Services\Payment\TamaraHandler

Hyperpay

HYPERPAY_BASE_URL=
HYPERPAY_ENTITY_ID=
HYPERPAY_ACCESS_TOKEN=
HYPERPAY_HANDLER=App\Http\Services\Payment\HyperpayHandler

Paytabs

PAYTABS_BASE_URL=
PAYTABS_PROFILE_ID=
PAYTABS_SERVER_KEY=
PAYTABS_HANDLER=App\Http\Services\Payment\PaytabsHandler

تنفيذ Handler للمشروع

كل بوابة تحتاج Handler يطبق الواجهة الخاصة بها:

Paymob

PaymobPaymentHandlerInterface - initiatePayment, initiatePaymentAndSend, checkPaymentStatus, getPaymentByOrderId, ...

Moyasar

MoyasarPaymentHandlerInterface - initiatePayment, getPaymentViewData, handleCallback, handlePaidWebhook, handleFailedWebhook

Tap

TapPaymentHandlerInterface - initiatePayment, handleCallback, handleWebhook

Stripe

StripePaymentHandlerInterface - initiatePayment, handleCallback, handleWebhook

Tamara

TamaraPaymentHandlerInterface - initiatePayment, handleCallback, handleWebhook

Hyperpay

HyperpayPaymentHandlerInterface - initiatePayment, handleCallback, handleWebhook

Paytabs

PaytabsPaymentHandlerInterface - initiatePayment, handleCallback, handleWebhook

اختيار البوابة ديناميكياً (Gateway Manager)

يمكنك اختيار البوابة أثناء التشغيل:

use Elryad\Payments\GatewayManager;
use Elryad\Payments\Support\GatewayActions;

$gateway = app(GatewayManager::class)->driver('moyasar'); // أو config('payments.default')

return $gateway->perform(GatewayActions::INITIATE, [
    'amount' => 100,
    'metadata' => ['order_id' => 123],
]);

تغيير البوابة الافتراضية:

PAYMENTS_DEFAULT_GATEWAY=moyasar

الوثائق التفصيلية

راجع ملفات الوثائق لكل بوابة:

• docs/gateways/paymob.md
• docs/gateways/moyasar.md
• docs/gateways/tap.md
• docs/gateways/stripe.md
• docs/gateways/tamara.md
• docs/gateways/hyperpay.md
• docs/gateways/paytabs.md

مثال Handler لـ Moyasar (مشروع الاشتراكات)

// app/Http/Services/Payment/MoyasarSubscriptionHandler.php
class MoyasarSubscriptionHandler implements MoyasarPaymentHandlerInterface
{
    public function initiatePayment(array $validatedData): mixed
    {
        return redirect()->route('payment.view', [
            'amount' => $validatedData['amount'],
            'subscriptionId' => $validatedData['subscription_id'],
        ]);
    }

    public function getPaymentViewData(float $amount, array $metadata = []): array
    {
        $moyasar = app(MoyasarService::class);
        return [
            'amount' => (int) round($amount * 100), // halala
            'publishable_key' => $moyasar->getPublishableKey(),
            'callback_url' => route('payments.moyasar.callback', $metadata),
            'metadata' => $metadata,
        ];
    }

    public function handleCallback(string $paymentId, string $status, array $queryParams): mixed
    {
        $subscriptionId = $queryParams['subscription_id'] ?? null;
        $payment = app(MoyasarService::class)->verifyPayment($paymentId);
        if ($payment && $payment['status'] === 'paid') {
            $this->processSuccessfulPayment($subscriptionId, $payment);
            return redirect(config('app.frontend_url').'/payment/success');
        }
        return redirect(config('app.frontend_url').'/payment/failed');
    }

    public function handlePaidWebhook(array $paymentData): \Illuminate\Http\JsonResponse
    {
        $subscriptionId = $paymentData['metadata']['subscription_id'] ?? null;
        if ($subscriptionId) {
            $this->processSuccessfulPayment($subscriptionId, $paymentData);
        }
        return response()->json(['status' => 'success']);
    }

    public function handleFailedWebhook(array $paymentData): \Illuminate\Http\JsonResponse
    {
        // mark as failed
        return response()->json(['status' => 'updated']);
    }
}

Routes للمشاريع

// Paymob
Route::post('/payments/paymob/webhook', [PaymobWebhookController::class, 'callback']);
Route::get('/payments/paymob/webhook', [PaymobWebhookController::class, 'redirect']);

// Moyasar
Route::post('/payments/moyasar/initiate', [MoyasarController::class, 'initiate']);
Route::get('/payments/moyasar/view', [MoyasarController::class, 'paymentView']);
Route::get('/payments/moyasar/callback', [MoyasarWebhookController::class, 'callback']);
Route::post('/payments/moyasar/webhook', [MoyasarWebhookController::class, 'webhook']);

// Tap
Route::post('/payments/tap/initiate', [TapController::class, 'initiate']);
Route::get('/payments/tap/callback', [TapController::class, 'callback']);
Route::post('/payments/tap/webhook', [TapWebhookController::class, 'webhook']);

التطوير والاختبارات محليًا

composer install
vendor\bin\phpunit

License

MIT