ربط تطبيق شركتكم بنجم
نجم تدير التحصيل والمطابقة والتسويات وفق عقد شركتكم، عبر وسائل الدفع المتفق عليها.
بيئتا الاختبار والإنتاج
بيئتان منفصلتان بمفاتيح مختلفة: الاختبار (njm_test_…) للتجربة دون تحريك أموال، والإنتاج (njm_live_…) بعد اعتماد العقد وتفعيل الوسائل المتفق عليها. تُسلَّم المفاتيح وعناوين الربط لكل شركة عند التفعيل.
الاختبار: <sandbox-base-url> مفتاح njm_test_… الإنتاج: <live-base-url> مفتاح njm_live_… # تُسلَّم العناوين والمفاتيح عند تفعيل الشركة
المصادقة
يُرسل مفتاح الشركة في الترويسة Authorization مع مفتاح منع التكرار لكل عملية. المفتاح سري ويُستخدم من الخادم فقط، ولا يوضع في تطبيق الهاتف أو المتصفح.
Authorization: Bearer <company-api-key> Idempotency-Key: ORD-2026-1042 Content-Type: application/json
إنشاء عملية دفع (صفحة مستضافة)
يُنشئ خادمكم العملية ويحصل على checkout_url، ثم يوجّه الزبون إليها ليختار وسيلته. المبالغ بأصغر وحدة (1 د.ل = 1000 درهم).
POST /payments
{
"amount_minor": 1000000,
"currency": "LYD",
"merchant_reference": "ORD-2026-1042",
"customer_phone": "0912345678",
"return_url": "https://your-app.ly/done",
"callback_url": "https://your-app.ly/najm/webhook"
}
→ 201 { "id": "pay_…", "status": "awaiting_customer", "checkout_url": "https://…/pay/…" }مثال PHP (cURL)
مثال توضيحي لإنشاء عملية من خادم PHP وتوجيه الزبون.
<?php
$ch = curl_init('<sandbox-base-url>/payments');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('NAJM_API_KEY'),
'Idempotency-Key: ORD-2026-1042',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'amount_minor' => 1000000,
'currency' => 'LYD',
'merchant_reference' => 'ORD-2026-1042',
'return_url' => 'https://your-app.ly/done',
'callback_url' => 'https://your-app.ly/najm/webhook',
]),
]);
$res = json_decode(curl_exec($ch), true);
header('Location: ' . $res['checkout_url']);مثال Laravel
استخدام عميل HTTP في Laravel مع حفظ المفتاح في .env كـ NAJM_API_KEY.
use Illuminate\Support\Facades\Http;
$res = Http::withToken(config('services.najm.key'))
->withHeaders(['Idempotency-Key' => $order->reference])
->post(config('services.najm.base_url') . '/payments', [
'amount_minor' => $order->total_minor,
'currency' => 'LYD',
'merchant_reference' => $order->reference,
'return_url' => route('checkout.done'),
'callback_url' => route('najm.webhook'),
])->throw()->json();
return redirect()->away($res['checkout_url']);التحقق من توقيع HMAC
كل إشعار يحمل توقيع HMAC-SHA256 على «الطابع الزمني.جسم الطلب الخام» بمفتاح التوقيع الخاص بكم (whsec_…). تحقّق بمقارنة آمنة زمنياً، وارفض الإشعارات الأقدم من 5 دقائق، ثم استعلم عن العملية من الخادم قبل تسليم الخدمة.
// Laravel — routes/web.php (استثنِ المسار من CSRF)
Route::post('/najm/webhook', function (Request $r) {
$raw = $r->getContent();
parse_str(str_replace(',', '&', $r->header('X-Najm-Signature')), $sig);
$t = (int) ($sig['t'] ?? 0);
if (abs(time() - $t) > 300) abort(400);
$expected = hash_hmac('sha256', $t . '.' . $raw, env('NAJM_WEBHOOK_SECRET'));
if (!hash_equals($expected, $sig['v1'] ?? '')) abort(401);
$event = json_decode($raw, true);
// تحقّق من الحالة عبر GET /payments/{id} ثم حدّث الطلب مرة واحدة
return response()->noContent();
});الاستعلام عن عملية
استعلم دائماً عن الحالة من الخادم قبل تسليم الخدمة، ولا تعتمد على صفحة العودة وحدها.
GET /payments/{id}
→ 200 { "id": "pay_…", "status": "collected", "amount_minor": 1000000 }طلب استرجاع
يُنشأ الطلب بحالة بانتظار الموافقة ويُنفذ بعد اعتماده. ويخضع الاسترجاع لموافقة مزدوجة.
POST /payments/{id}/refunds
{ "amount_minor": 250000, "reason": "إلغاء حجز" }محاكيات الوسائل في الاختبار
صفحة الدفع ومحاكيات الوسائل المحلية الثماني متاحة عبر روابط الدفع من لوحة الشركة، دون تحصيل أموال حقيقية.
0910000000 → failed (ينتهي بـ 0000) 0912345678 → collected
رموز الأخطاء
رموز أخطاء موحّدة وثابتة.
400 invalid_request · 401 invalid_key · 403 ip_not_allowed 409 duplicate_idempotency_key · 422 provider_disabled · 429 rate_limited