Paynimb Documentation v2.5.0

مركز التوثيق ودليل المطورين الشامل

دليلك الكامل لمعرفة تفاصيل العمولات، بوابات الإيداع والسحب، محرك تبديل العملات، وطريقة ربط بوابة الدفع عبر REST API.

🌍

محافظ العملات المتعددة

يتم إنشاء المحفظة الأساسية تلقائياً بعملة دولتك (الجنيه المصري، الدينار العراقي، الريال السعودي، الدولار...)، مع إمكانية فتح محافظ لجميع العملات العالمية الأخرى بنقرة واحدة.

🔄

محرك تبديل العملات FX

نظام تبديل مالي متطور بأسعار بيع وشراء منفصلة، توجيه دقيق للأزواج المسموحة، وحدود دنيا وقصوى وعمولة ثابتة ونسبية واضحة.

📅

التحويلات البنكية Net30

دعم سحب أرباح التجار عبر الحوالات البنكية المجدولة شهرياً (Net30 كل أول يوم عمل من كل شهر) للدول المعتمدة.

💳 رسوم طرق الإيداع والسحب المتاحة في قاعدة البيانات

الوسيلة	النوع	العملة / الدولة	الحد الأدنى - الأقصى	رسوم المزود الخارجي	عمولة منصة Paynimb	وقت التنفيذ
فودافون كاش / اتصالات / أورنج	إيداع وسحب	EGP (مصر)	50 - 30000	0 + 1%	5 + 0.5%	فوري خلال 5-15 دقيقة
إنستاباي InstaPay مصر	إيداع وسحب	EGP (مصر)	100 - 50000	0 + 0%	5 + 0.5%	فوري خلال 5 دقائق
زين كاش Zain Cash العراق	إيداع وسحب	IQD (العراق)	15000 - 5000000	0 + 1.5%	1000 + 0.5%	فوري خلال 10 دقائق
فاست باي FastPay العراق	إيداع وسحب	IQD (العراق)	15000 - 5000000	0 + 1%	1000 + 0.5%	فوري خلال 15 دقيقة
تيذر USDT (TRC-20)	إيداع وسحب	USDT (عالمي)	10 - 100000	1 + 0%	0 + 1%	تأكيد آلي بعد 3 تأكيدات بلوكتشين
البطاقات البنكية Visa / MasterCard	إيداع	USD (عالمي)	10 - 5000	0.3 + 2.9%	0 + 0.5%	فوري مباشر
فودافون كاش / اتصالات / أورنج	إيداع وسحب	EGP (مصر)	50 - 30000	0 + 1%	5 + 0.5%	فوري خلال 5-15 دقيقة
إنستاباي InstaPay مصر	إيداع وسحب	EGP (مصر)	100 - 50000	0 + 0%	5 + 0.5%	فوري خلال 5 دقائق
زين كاش Zain Cash العراق	إيداع وسحب	IQD (العراق)	15000 - 5000000	0 + 1.5%	1000 + 0.5%	فوري خلال 10 دقائق
فاست باي FastPay العراق	إيداع وسحب	IQD (العراق)	15000 - 5000000	0 + 1%	1000 + 0.5%	فوري خلال 15 دقيقة
تيذر USDT (TRC-20)	إيداع وسحب	USDT (عالمي)	10 - 100000	1 + 0%	0 + 1%	تأكيد آلي بعد 3 تأكيدات بلوكتشين
التحويل البنكي الدولي المجدول (Net30)	سحب	USD (عالمي)	500 - 200000	25 + 0%	10 + 0%	مجدول شهرياً (Net30)

🔄 أسعار وعمولات أزواج تبديل العملات (FX Pairs)

الزوج	سعر الشراء (Buy Rate)	سعر البيع (Sell Rate)	العمولة الثابتة + النسبة	الحدود
USD ➔ EGP	49.2	48.6	0.01 + 0%	5 إلى 10000
EGP ➔ USD	0.0203	0.02	10 + 0.75%	200 إلى 500000
USD ➔ IQD	1320	1300	0.5 + 0.5%	5 إلى 10000
IQD ➔ USD	0.00076	0.00074	1000 + 0.5%	10000 إلى 15000000
USD ➔ USDT	1	0.995	0 + 0.1%	10 إلى 50000
USDT ➔ USD	1	0.995	0 + 0.1%	10 إلى 50000

POST /api/v1/checkout/create

1. إنشاء جلسة دفع (Create Checkout Session)

يقوم متجرك بإرسال طلب إلى الـ API لتوليد رابط صفحة الدفع المخصصة للعميل على Paynimb.

curl -X POST https://paynimb.com/api/v1/checkout/create \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_PUBLIC_KEY" \
  -H "X-API-SECRET: YOUR_SECRET_KEY" \
  -d '{
    "amount": 49.99,
    "currency": "USD",
    "order_id": "ORD-2026-991",
    "customer_email": "client@example.com",
    "success_url": "https://mystore.com/order/success",
    "cancel_url": "https://mystore.com/cart"
  }'

<?php
$payload = [
    'amount' => 49.99,
    'currency' => 'USD',
    'order_id' => 'ORD-2026-991',
    'customer_email' => 'client@example.com',
    'success_url' => 'https://mystore.com/order/success',
    'cancel_url' => 'https://mystore.com/cart'
];

$ch = curl_init('https://paynimb.com/api/v1/checkout/create');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-API-KEY: YOUR_PUBLIC_KEY',
        'X-API-SECRET: YOUR_SECRET_KEY'
    ]
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

// Redirect client to hosted checkout
header('Location: ' . $response['checkout_url']);
exit;

const res = await fetch('https://paynimb.com/api/v1/checkout/create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_PUBLIC_KEY',
    'X-API-SECRET': 'YOUR_SECRET_KEY'
  },
  body: JSON.stringify({
    amount: 49.99,
    currency: 'USD',
    order_id: 'ORD-2026-991',
    customer_email: 'client@example.com',
    success_url: 'https://mystore.com/order/success',
    cancel_url: 'https://mystore.com/cart'
  })
});

const data = await res.json();
window.location.href = data.checkout_url;

import requests

headers = {
    'Content-Type': 'application/json',
    'X-API-KEY': 'YOUR_PUBLIC_KEY',
    'X-API-SECRET': 'YOUR_SECRET_KEY'
}

data = {
    'amount': 49.99,
    'currency': 'USD',
    'order_id': 'ORD-2026-991',
    'customer_email': 'client@example.com',
    'success_url': 'https://mystore.com/order/success',
    'cancel_url': 'https://mystore.com/cart'
}

response = requests.post('https://paynimb.com/api/v1/checkout/create', headers=headers, json=data)
checkout_data = response.json()
print("Checkout URL:", checkout_data['checkout_url'])

نموذج الاستجابة الناجحة (HTTP 201 Created):

{
  "status": "success",
  "charge_id": "ch_7a9f1c2e8d3b4a5690f1234567890abc",
  "amount": 49.99,
  "currency": "USD",
  "mode": "live",
  "checkout_url": "https://paynimb.com/checkout/ch_7a9f1c2e8d3b4a5690f1234567890abc",
  "expires_at": "2026-09-05T21:30:00+00:00"
}

GET /api/v1/checkout/verify/{charge_id}

2. التحقق اليدوي من حالة الدفع (Verify Charge Status)

يمكن لمتجرك الاستعلام المباشر عن حالة أي جلسة دفع في أي وقت.

curl -X GET https://paynimb.com/api/v1/checkout/verify/ch_7a9f1c2e8d3b4a5690f1234567890abc \
  -H "X-API-KEY: YOUR_PUBLIC_KEY" \
  -H "X-API-SECRET: YOUR_SECRET_KEY"

نموذج استجابة التحقق (HTTP 200 OK):

{
  "status": "success",
  "charge_id": "ch_7a9f1c2e8d3b4a5690f1234567890abc",
  "paid": true,
  "amount": 49.99,
  "transaction_id": "TXN-8821940182",
  "order_id": "ORD-2026-991",
  "paid_at": "2026-09-05 20:30:15"
}

HMAC-SHA256 Security

التحقق من صحة إشعار الـ Webhook وتأمين المتجر

عند إتمام أي عملية بنجاح، يُرسل خادم Paynimb إشعار HTTP POST إلى رابط الـ Webhook الخاص بك مصحوباً بهيدر التوقيع الرقمي X-Paynimb-Signature.

1. نموذج بيانات الإشعار المرسل (JSON Payload):

{
  "event": "payment.succeeded",
  "charge_id": "ch_7a9f1c2e8d3b4a5690f1234567890abc",
  "order_id": "ORD-2026-991",
  "amount": 49.99,
  "currency": "USD",
  "transaction_id": "TXN-8821940182",
  "timestamp": 1757104215
}

2. كود التحقق من التوقيع ومنع التلاعب (PHP Backend):

<?php
// 1. استقبال الـ Raw Payload والهيدر
$rawPayload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_PAYNIMB_SIGNATURE'] ?? '';
$webhookSecret = 'YOUR_WEBHOOK_SECRET'; // من لوحة تحكم التاجر

// 2. حساب التوقيع المتوقع باستخدام HMAC-SHA256
$expectedSignature = hash_hmac('sha256', $rawPayload, $webhookSecret);

// 3. مقارنة التوقيع في وقت ثابت لمنع Timing Attacks
if (!hash_equals($expectedSignature, $signature)) {
    http_response_code(400);
    echo json_encode(['error' => 'Invalid signature']);
    exit;
}

// 4. معالجة الحدث بعد التأكد من المصدر 100%
$eventData = json_decode($rawPayload, true);
$eventName = $eventData['event'] ?? '';

switch ($eventName) {
    case 'payment.succeeded':
        $orderId = $eventData['order_id'];
        $txnId = $eventData['transaction_id'];
        $amount = $eventData['amount'];
        // TODO: تفعيل الطلب وشحن الرصيد للعميل في قاعدة بيانات متجرك
        break;

    case 'payment.failed':
        // TODO: تسجيل فشل العملية
        break;

    case 'dispute.opened':
        // TODO: إشعار الإدارة بوجود نزاع
        break;
}

// 5. إرجاع 200 OK لتأكيد الاستلام
http_response_code(200);
echo json_encode(['status' => 'acknowledged']);
exit;

⚠️ إرشادات أمنية هامة للمطورين:

استخدم دائماً file_get_contents('php://input') لقراءة البايلود الخام قبل فك تشفيره لتطابق التوقيع.
استخدم دالة hash_equals() بدلاً من === لتجنب ثغرات التوقيت الزمني (Timing Attacks).
تأكد من إرجاع كود الاستجابة 200 OK فوراً لكي لا يعيد النظام إرسال الإشعار مرة أخرى.

الإضافات الجاهزة والمكتبات البرمجية الرسمية

قم بالربط والتكامل الفوري مع متجرك أو منصتك دون الحاجة لكتابة كود من الصفر مع دعم التحقق التلقائي من الفواتير والـ IPN

v1.1.0 • WHMCS 8.x+

موديول WHMCS (استضافات وخدمات)

إضافة بوابة الدفع الرسمية لمنصة إدارة الاستضافات WHMCS مع معالجة فواتير التجديد التلقائي وتأكيد الدفع عبر Callback IPN الفوري.

/modules/gateways/paynimb.php

تحميل إضافة WHMCS (.zip)

v1.0.0 • WooCommerce

إضافة ووكومرس (WooCommerce)

إضافة ووردبريس وووكومرس لقبول المدفوعات والبطاقات وزين كاش وفاس باي في متجرك الإلكتروني مع توجيه سلس وتحديث تلقائي لحالة الطلبات.

/wp-content/plugins/paynimb/

تحميل إضافة WooCommerce (.zip)

OpenCart 3.x / 4.x

إضافة أوبن كارت (OpenCart)

موديول الدفع الكامل لمتاجر OpenCart مع لوحة إعدادات متكاملة داخل لوحة إدارة المتجر لدعم العملات المتعددة.

extension/payment/paynimb

تحميل إضافة OpenCart (.zip)

PrestaShop 1.7 / 8.x

موديول بريستاشوب (PrestaShop)

إضافة بوابة PayNimb الرسمية لمتاجر PrestaShop العالمية مع دعم التثبيت التلقائي بنقرة واحدة من لوحة التحكم.

/modules/paynimb/

تحميل إضافة PrestaShop (.zip)

PHP 7.4 - 8.3+

حزمة PHP & Laravel SDK

مكتبة برمجية PSR-4 متوافقة مع إطار عمل Laravel و Symfony مع دعم إنشاء عمليات الدفع والتحقق من التوقيع الرقمي للـ Webhooks.

composer require paynimb/paynimb-php

تحميل حزمة PHP SDK (.zip)

NPM Package

مكتبة Node.js & Express

حزمة JavaScript / TypeScript لربط خوادم Node.js و Express و NestJS مع دعم كامل لعمليات الدفع والتأكد الأمني الآمن.

npm install paynimb-node

تحميل حزمة Node.js SDK (.zip)

PyPI Package

حزمة Python / Django SDK

مكتبة بايثون المتوافقة مع Django, Flask, FastAPI مع أدوات التحقق من التوقيع HMAC وتوليد الفواتير والاشتراكات.

pip install paynimb-python

تحميل حزمة Python SDK (.zip)