لارافيل + سيريتل كاش: ربط بوابة الدفع بمشروع Laravel
في Laravel: طلب بحالة ومهلة، وحقل transaction_id فريد، وخدمة HTTP تسأل البوابة عن رقم العملية. قفل الصف والقيد الفريد يمنعان تعليم طلبين من رقم واحد. نفس المنطق يخدم سيريتل كاش وشام كاش بحقل wallet.
لمن هذا المقال
أكثر طلب يصلني من مطوّري المتاجر المخصصة في سوريا يبدأ بجملة قريبة من هذه: المشروع على لارافيل، والزبائن يدفعون بسيريتل كاش، كيف أخلي الطلب يصير مدفوعًا من غير ما أفتح التطبيق لكل عملية؟ أحيانًا يكون المتجر مبنيًا من الصفر. أحيانًا لوحة طلبات لمطعم أو لمتجر جملة. ووكومرس له مسار مختلف، وكتبته في سيريتل كاش على ووكومرس: يدوي أم تلقائي؟. هنا أبقى عند لارافيل سيريتل كاش: نموذج طلب، مسار يؤكد الدفع، وقيد فريد على رقم العملية، وحديث مع بوابة الدفع الجاهزة.
التدفق العام شرحته في تأكيد الدفع التلقائي، وخطوات الربط من زاوية صاحب المتجر في كيف تربط سيريتل كاش بمتجرك الإلكتروني. هذا المقال للكود داخل المشروع.
ما الذي تربطه في المشروع
رقم سيريتل كاش يبقى رقمك. إن قبلت شام كاش أيضًا، الحساب يبقى حسابك. أنا أقدّم بوابة مستضافة تمنح تطبيق لارافيل وصولًا برمجيًا إلى التحويل الوارد. الزبون يحوّل، ثم يدخل رقم العملية في صفحة الطلب أو في واجهة الـAPI، ومشروعك يسأل البوابة ويقرّر.
سعر API سيريتل كاش دولاران للرقم في الشهر، من دون رسوم إعداد للرقم الواحد. API شام كاش خمسة دولارات للحساب في الشهر، ويُحاسب ويُدار بشكل منفصل. الإعداد يتم في اليوم نفسه. التسليم خدمة جاهزة من دون كود مصدري للبوابة. يمكن طلب وصول تجريبي قبل الرقم أو الحساب الحي. الواجهة تعمل من خارج سوريا من دون وسيط سوري ومن دون VPN، وهذا يناسب إن كان سيرفر لارافيل عندك على VPS خارج البلد.
تحويل سيريتل كاش وتحويل شام كاش لا يتيحان حقل ملاحظة يكتبه الزبون. لا تضف في صفحة الدفع عبارة «اكتب رقم الطلب في الملاحظة». الحقل غير موجود. بعد نجاح التحويل يظهر رقم العملية، وهذا ما يدخله الزبون عندك.
حدود الاستلام تختلف وقد تتغيّر. إذا كنت تتوقع يومًا مزدحمًا أو طلبات كبيرة، اسأل الجهة التي تدير المحفظة عن الحدود الحالية لحسابك، وأبقِ الحديث في الكود عامًا: مهلة، وحالة مراجعة، لا رقم حد ثابت تختبره في كل طلب.
إذا كان سؤالك أقرب إلى «هل أبني المتجر مستضافًا أم أمتلك الكود»، فهذا قرار منفصل عن بوابة الدفع. قارنته في متجر مستضاف مقابل متجر تمتلكه. البوابة تتصل بالاثنين، لأن الحديث يتم عبر HTTP من سيرفرك.
نموذج الطلب والحقول التي تحتاجها
قبل أن تظهر رقم التحويل للزبون، يجب أن يكون في قاعدة البيانات طلب بمبلغ وحالة. الحقول التي أعتمدها في البداية:
```php <?php
use Illuminate\Database\Migrations\Migration; use Illuminate\Database\Schema\Blueprint; use Illuminate\Support\Facades\Schema;
return new class extends Migration { public function up(): void { Schema::create('orders', function (Blueprint $table) { $table->id(); $table->unsignedBigInteger('amount'); $table->string('wallet'); // syriatel_cash أو sham_cash $table->string('status'); // awaiting_payment, paid, needs_review, expired $table->string('transaction_id')->nullable()->unique(); $table->string('sender_number')->nullable(); $table->timestamp('paid_at')->nullable(); $table->timestamps(); }); }
public function down(): void { Schema::dropIfExists('orders'); } }; ```
transaction_id فريد على مستوى الجدول كله، لا داخل الطلب الواحد فقط. رقم العملية الذي نجح على طلب لا يجوز أن يغلق طلبًا ثانيًا حتى لو كان المبلغ مطابقًا.
wallet يحدد أي اشتراك تسأل عنه البوابة. لا تخلط التحقق: طلب ينتظر سيريتل كاش لا يُغلق بعملية شام كاش. كل محفظة تُدار وحدها، والتفاصيل في مقارنة الواجهتين.
رقم المرسل عمود منفصل. البوابة ترجعه دائمًا مع كل تحويل. أحفظه للدعم. لا أضعه في شرط المطابقة، ولا أربطه بهاتف الفاتورة كشرط نجاح؛ الدفع من محفظة شخص آخر شائع.
تدفق الدفع من صفحة الطلب إلى تغيير الحالة
الزبون يتمم الطلب في موقعك. لارافيل يخزّن المبلغ، مثلًا 85,000 ل.س، والحالة awaiting_payment، والمحفظة التي اختارها. الصفحة تعرض رقم سيريتل كاش (أو حساب شام كاش) والمبلغ كما هو، وحقلًا لرقم العملية، وجملة واحدة: التحويل لا يحتاج ملاحظة، أدخل الرقم بعد نجاحه.
بعد أن يحوّل، يرسل النموذج إلى مسار عندك. المسار لا يعلّم الطلب مدفوعًا مباشرة. يستدعي خدمة تسأل البوابة على العنوان الذي يصلك عند الإعداد (YOUR_GATEWAY_URL حتى ذلك الحين). إن وُجدت العملية، يعود الرد بالمبلغ ووقت الوصول ورقم المرسل.
إذا كان رقم العملية مستخدمًا، ارفض الطلب الجديد واتركه بانتظار الدفع. إذا لم تظهر العملية بعد، لا تستهلك الرقم؛ اطلب الانتظار وإعادة المحاولة. إذا وُجدت العملية والمبلغ مختلف، انقل الطلب إلى needs_review، واربط الرقم به، وأرسل إشعارًا لك. إذا وُجدت العملية والمبلغ ينطبق والرقم جديد، احفظ الحالة paid مع رقم العملية ورقم المرسل ووقت الرد، ثم أخطر الزبون والتاجر.
المبلغ يُقارن كعدد صحيح. لا تعتمد على مقارنة نصية بين 85000 و85000.00. طلبان بنفس المجموع لا يتعارضان، لأن المفتاح هو رقم العملية.
المهلة قرارك. خزّن وقت إنشاء الطلب، وشغّل أمرًا مجدولًا يغيّر الحالة إلى expired بعد النافذة التي أعلنتها. إذا وصل رقم عملية صحيح بعد الانتهاء، لا تترك القرار للكود الصامت: أبقِ مسار مراجعة يعيد فتح الطلب أو يسجّل المبلغ بانتظار قرارك.
خدمة لارافيل تؤكد دفع سيريتل كاش عبر البوابة
الكود التالي يعمل مع عميل HTTP المدمج في لارافيل (الإصدارات الحالية، بما فيها 11 وما بعدها). هو نمط لحديث مشروعك مع البوابة الجاهزة، لا حزمة رسمية من سيريتل أو شام كاش. استبدل العنوان والمفتاح وأسماء الحقول بما يصلك عند الإعداد. المفتاح يبقى في ملف البيئة، لا في المستودع.
```php <?php
namespace App\Services;
use App\Models\Order; use Illuminate\Support\Facades\DB; use Illuminate\Support\Facades\Http; use RuntimeException;
class WalletPaymentGateway { public function confirm(Order $order, string $transactionId): array { $transactionId = trim($transactionId); if ($transactionId === '' || $order->status !== 'awaiting_payment') { return ['status' => $transactionId === '' ? 'bad_payload' : 'closed']; }
return DB::transaction(function () use ($order, $transactionId) { $order = Order::query() ->whereKey($order->id) ->lockForUpdate() ->firstOrFail();
if ($order->status !== 'awaiting_payment') { return ['status' => 'closed']; }
$taken = Order::query() ->where('transaction_id', $transactionId) ->exists(); if ($taken) { return ['status' => 'already_used']; }
$payload = $this->lookup($transactionId, $order->wallet); if (! $payload || empty($payload['found'])) { return ['status' => 'not_found']; }
$paid = $this->toIntAmount($payload['amount'] ?? null); $expected = $this->toIntAmount($order->amount); $sender = $payload['senderNumber'] ?? null; $receivedAt = $payload['receivedAt'] ?? now();
$order->transaction_id = $transactionId; $order->sender_number = $sender;
if ($paid !== $expected) { $order->status = 'needs_review'; $order->save();
return [ 'status' => 'wrong_amount', 'paid' => $paid, 'senderNumber' => $sender, ]; }
$order->status = 'paid'; $order->paid_at = $receivedAt; $order->save();
return [ 'status' => 'paid', 'senderNumber' => $sender, 'paidAt' => $receivedAt, ]; }); }
private function lookup(string $transactionId, string $wallet): array { // حقول تقريبية في الرد: found, amount, receivedAt, senderNumber $response = Http::timeout(20) ->withToken(config('services.wallet_gateway.key')) ->acceptJson() ->post(config('services.wallet_gateway.url'), [ 'transactionId' => $transactionId, 'wallet' => $wallet, ]);
if ($response->failed()) { throw new RuntimeException('gateway_http_'.$response->status()); }
return $response->json() ?? []; }
private function toIntAmount(mixed $value): int { return (int) round((float) $value); } } ```
في config/services.php أضف مدخلًا يستخدم العنوان الذي يصلك، وحتى ذلك الحين أبقِ القيمة واضحة أنها مستبدلة:
``php 'wallet_gateway' => [ 'url' => env('WALLET_GATEWAY_URL', 'YOUR_GATEWAY_URL'), 'key' => env('WALLET_GATEWAY_KEY'), ], ``
والمعامل في .env.example:
`` WALLET_GATEWAY_URL=YOUR_GATEWAY_URL WALLET_GATEWAY_KEY= ``
القيد الفريد في القاعدة يحمي من سباق طلبين. lockForUpdate يحمي من ضغط الزر مرتين على نفس الطلب قبل أن يُحفظ الرقم. إذا وصل الاستثناء من قيد التفرّد، أرجعه للواجهة كـ already_used، لا كخطأ خادم عام.
نداء HTTP داخل المعاملة يبقي القفل إلى أن ترد البوابة. إذا كان زمن الرد عندك أحيانًا أطول مما تحب، انقل البحث إلى خارج المعاملة ثم أعد قفل الصف قبل الكتابة، وأعد فحص أن الرقم ما زال غير مستخدم وأن الطلب ما زال بانتظار الدفع. أبقيت النداء داخل المعاملة هنا لأن معظم تأكيدات المتجر قصيرة، والكود أسهل للتتبع في المسار الأول.
المتحكم والمسار ورسالة الزبون
```php <?php
namespace App\Http\Controllers;
use App\Models\Order; use App\Services\WalletPaymentGateway; use Illuminate\Http\Request; use Illuminate\Support\Facades\Log;
class PaymentConfirmationController extends Controller { public function store(Request $request, Order $order, WalletPaymentGateway $gateway) { $data = $request->validate([ 'transaction_id' => ['required', 'string', 'max:64'], ]);
$this->authorize('confirmPayment', $order);
try { $result = $gateway->confirm($order, $data['transaction_id']); } catch (\RuntimeException $e) { Log::warning('wallet_gateway_failed', [ 'order_id' => $order->id, 'message' => $e->getMessage(), ]);
return back()->withErrors([ 'transaction_id' => 'التأكيد تأخر لحظة. أعد المحاولة بعد قليل.', ]); }
return match ($result['status']) { 'paid' => redirect() ->route('orders.show', $order) ->with('status', 'وصل المبلغ. طلبك دخل التجهيز.'), 'not_found' => back()->withErrors([ 'transaction_id' => 'ما ظهرت العملية بعد. راجع الرقم، وانتظر دقيقة إذا كان التحويل للتو، ثم أعد المحاولة.', ]), 'already_used' => back()->withErrors([ 'transaction_id' => 'هذا الرقم مستخدم من قبل على طلب آخر.', ]), 'wrong_amount' => redirect() ->route('orders.show', $order) ->with('status', 'وصل تحويل والمبلغ مختلف. رح نراجعه ونرجع لك.'), default => back()->withErrors([ 'transaction_id' => 'لا يمكن تأكيد هذا الطلب الآن.', ]), }; } } ```
أضف سياسة confirmPayment بحيث لا يؤكد الدفع إلا صاحب الطلب أو موظف مخوّل. من دونها يرمي لارافيل خطأ تفويض.
والمسار، مع وسيط المصادقة الذي تستخدمه أصلًا:
```php use App\Http\Controllers\PaymentConfirmationController; use Illuminate\Support\Facades\Route;
Route::post('/orders/{order}/payment', [PaymentConfirmationController::class, 'store']) ->middleware(['auth', 'throttle:10,1']) ->name('orders.payment.store'); ```
في صفحة Blade يكفي حقل واحد وزر. لا تضع في التعليمات طلب ملاحظة داخل التحويل:
``blade <form method="POST" action="{{ route('orders.payment.store', $order) }}"> @csrf <p> حوّل {{ number_format($order->amount) }} ل.س إلى {{ $order->wallet === 'syriatel_cash' ? 'رقم سيريتل كاش' : 'حساب شام كاش' }} المعروض أعلاه. التحويل لا يحتاج ملاحظة. بعد نجاحه أدخل رقم العملية. </p> <label for="transaction_id">رقم العملية</label> <input id="transaction_id" name="transaction_id" value="{{ old('transaction_id') }}" required> @error('transaction_id') <p>{{ $message }}</p> @enderror <button type="submit">تأكيد الدفع</button> </form> ``
الإشعار للزبون ولك يأتي بعد نجاح الحفظ. أطلق حدثًا أو مهمة طابور من المتحكم فقط عندما يكون الوضع paid أو wrong_amount. إذا فشلت المهمة، تعيد المحاولة على الإشعار، لا على confirm.
أضف في لوحة الإدارة مسارًا يسمح لك بلصق رقم العملية وتشغيل الخدمة نفسها، ومسارًا للرفض مع سبب. من دون هذا الزر تعلق الطلبات الغريبة إلى أن يراسل الزبون.
إذا كان المتجر يعرّض API لتطبيق موبايل، أعد استخدام WalletPaymentGateway من متحكم API وأرجع JSON بالحالات نفسها. لا تكتب شرط المبلغ مرة ثانية في التطبيق؛ التطبيق يرسل الرقم وينتظر النتيجة.
حالات يجب أن تقررها قبل الإطلاق
رقم مكتوب خطأ أو رقم من تحويل قديم هو أكثر حالة أراها. إذا لم تجد البوابة العملية، لا تخمّن طلبًا مفتوحًا بالمبلغ. أظهر الرسالة، واترك الرقم غير مستهلك.
الدفع الناقص أو الزائد يُربط بهذا الطلب ويدخل المراجعة. لا تشحن حتى ينطبق المبلغ أو يؤكد شخص القاعدة التي كتبتها (مثلًا: زيادة صغيرة تُقبل كفرق وتُغلق الطلب). اكتب القاعدة في مكان واحد.
الزبون يدفع ولا يعود إلى الصفحة. الطلب يبقى awaiting_payment إلى أن تدخل الرقم من اللوحة أو يعود هو. البوابة ترى ما وصل إلى حسابك، ولا تغلق الطلبات بالتخمين.
إذا انتهت صلاحية الجلسة بعد التحويل، يجب أن يتمكن الزبون من فتح صفحة الطلب وهو مسجّل الدخول وإدخال الرقم على الطلب نفسه، لا إنشاء طلب جديد بالمبلغ نفسه.
ربط ووكومرس، إن كان عندك موقع ثانٍ على ووردبريس، لا يغني عن هذا الكود في لارافيل. كل نظام يحتفظ بطلباته ويكلم البوابة من جهته. النسخة الإنكليزية للواجهة على المواقع عامة موجودة في Syriatel Cash API: Accept Payments on Your Site، وخطوات شام كاش بالعربية في ربط شام كاش API بمتجرك.
قائمة تحقق قبل فتح الدفع في الإنتاج
- الرقم أو الحساب الحي متصل بالبوابة، ومفتاح الإنتاج في البيئة لا مفتاح التجربة.
- الطلب يُنشأ بمبلغ ومحفظة وحالة قبل إظهار تعليمات التحويل.
- الصفحة لا تطلب ملاحظة داخل التحويل، وتطلب رقم العملية بعده.
transaction_idفريد، وإعادة الاستخدام تُرفض.- رقم غير موجود بعد لا يُحفظ على الطلب.
- المبلغ يُقارن كعدد، والمبلغ المختلف ينقل الطلب إلى المراجعة ويربط الرقم.
- رقم المرسل يُحفظ ولا يُشترط تطابقه مع هاتف الحساب.
- مسار لوحة للتأكيد والرفض اليدوي، مع أثر (من، ومتى، وأي رقم).
- الإشعارات بعد الحفظ، مع إعادة محاولة للمهمة إن فشلت.
- جرّبت النجاح، والتكرار، والمبلغ المختلف، والرقم غير الظاهر، وضغط الزر مرتين.
أسئلة تتكرر
هل أحتاج حزمة Composer رسمية من سيريتل كاش؟
لا. مشروعك ينادي البوابة المستضافة عبر HTTP كما في الخدمة أعلاه. لا تعتمد على حزمة تدّعي مسارًا رسميًا لم أزوّدك به.
هل يعمل هذا مع شام كاش في نفس مشروع لارافيل؟
نعم. أضف المحفظة كحقل على الطلب، واشترك في الواجهتين إن كنت تقبل الاثنتين. كل طلب ينتظر محفظة واحدة في اللحظة. سيريتل كاش دولاران للرقم شهريًا، وشام كاش خمسة دولارات للحساب.
هل يكتب الزبون رقم الطلب في التحويل؟
لا. ما فيه حقل ملاحظة في سيريتل كاش ولا في شام كاش. المطابقة برقم العملية الذي يدخله في موقعك.
ماذا لو ضغط تأكيد مرتين أو أرسل التطبيق الطلب مرتين؟
القيد الفريد وقفل الصف يمنعان تعليم طلبين من رقم واحد. الواجهة تعرض أن الرقم مستخدم أو أن الطلب صار مدفوعًا، حسب أي الطلبين وصل أولًا.
كم يستغرق الإعداد وهل أجرب قبل الإنتاج؟
الإعداد يتم في اليوم نفسه. يمكن طلب وصول تجريبي، وهذا ما أنصح به قبل مفتاح الإنتاج.
هل السيرفر لازم يكون داخل سوريا؟
لا. البوابة تعمل من خارج سوريا من دون وسيط سوري ومن دون VPN.
بعد أن يمرّ الاختبار على الحالات الأربع
انشر الدفع على منتج واحد أو على مسار طلبات محدود، وأبقِ المراجعة اليدوية مفتوحة في الأسبوع الأول. راقب كيف يصل رقم العملية: بطول مختلف، أو مع مسافات، أو بعد انتهاء الجلسة. بعد أن يستقر المسار تضيف المحفظة الثانية أو تربط البوت إذا كان جزء من البيع يتم في تيليغرام أو واتساب.
إذا بدك تربط سيريتل كاش أو شام كاش بمشروع Laravel، راسلني من صفحة الموقع أو على fayezalshami.dev@gmail.com. اذكر المحفظة، وعدد الأرقام أو الحسابات، وإصدار لارافيل التقريبي عندك، وهل الدفع يتم من موقع أو من API لتطبيق.