شعار نجم
نجم
NAJM PAYMENTS
وثائق الربط · بيئة الاختبار

ربط تطبيق شركتكم بنجم

نجم تدير التحصيل والمطابقة والتسويات وفق عقد شركتكم، عبر وسائل الدفع المتفق عليها.

تُسلَّم مفاتيح الاختبار والإنتاج وعناوين الربط لكل شركة بعد الاتفاق والتفعيل، ويرافقكم فريق نجم في خطوات الربط.

بيئتا الاختبار والإنتاج

بيئتان منفصلتان بمفاتيح مختلفة: الاختبار (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