كيفية دمج بوابة الدفع Paymob في React و Node.js – الدليل الكامل لمنطقة الشرق الأوسط

جدول المحتويات

1. لماذا Paymob لأسواق الشرق الأوسط
2. فهم تدفق Accept API
3. التنفيذ من جانب الخادم
4. تكامل React مع Accept.js
5. تكامل المحافظ الإلكترونية
6. أمان ومعالجة Webhooks
7. التعامل مع خصوصيات السوق المصري
8. الأخطاء الشائعة في التكامل

لماذا Paymob لأسواق الشرق الأوسط

تهيمن Paymob على مشهد المدفوعات المصري وتتوسع في جميع أنحاء الشرق الأوسط. بعد دمج Paymob لعدة منصات تجارة إلكترونية مصرية، أستطيع أن أخبرك لماذا هي مهمة:

• طرق الدفع المحلية - فودافون كاش، أورانج موني، فوري، بطاقات ميزة
• الاستحواذ المحلي - معالجة محلية مباشرة، بدون رسوم دولية
• تجربة عربية أولاً - دعم RTL أصلي وواجهة عربية
• الامتثال التنظيمي - مرخصة من البنك المركزي المصري

إذا كنت تبني للسوق المصري أو تتوسع في الشرق الأوسط، فإن Paymob غالباً ما تكون الخيار الواقعي الوحيد لقبول طرق الدفع المحلية.

فهم تدفق Accept API

تستخدم Accept API من Paymob تدفق مصادقة متعدد الخطوات يختلف عن البوابات الغربية:

الخطوة 1: رمز المصادقة (auth_token)
الخطوة 2: تسجيل الطلب (order_id)
الخطوة 3: إنشاء مفتاح الدفع (payment_key)
الخطوة 4: الدفع من جانب العميل (iframe)
الخطوة 5: إشعار Webhook

نقطة حاسمة: على عكس Stripe حيث تنشئ PaymentIntent وتنتهي، تتطلب Paymob ثلاث استدعاءات API متتالية قبل أن يتمكن العميل من الدفع. احفظ رمز المصادقة في الذاكرة المؤقتة - إنه صالح لمدة ساعة واحدة.

التنفيذ من جانب الخادم

التكوين

// config/paymob.ts
export const PAYMOB_CONFIG = {
  apiKey: process.env.PAYMOB_API_KEY!,
  integrationId: process.env.PAYMOB_INTEGRATION_ID!,
  walletIntegrationId: process.env.PAYMOB_WALLET_INTEGRATION_ID!,
  iframeId: process.env.PAYMOB_IFRAME_ID!,
  hmacSecret: process.env.PAYMOB_HMAC_SECRET!,
  baseUrl: 'https://accept.paymob.com/api',
};

// التخزين المؤقت للرمز - صالح لمدة ساعة
let cachedToken: { token: string; expiresAt: number } | null = null;

export async function getAuthToken(): Promise<string> {
  if (cachedToken && cachedToken.expiresAt > Date.now() + 5 * 60 * 1000) {
    return cachedToken.token;
  }

  const response = await fetch(`${PAYMOB_CONFIG.baseUrl}/auth/tokens`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ api_key: PAYMOB_CONFIG.apiKey }),
  });

  const data = await response.json();
  
  cachedToken = {
    token: data.token,
    expiresAt: Date.now() + 55 * 60 * 1000,
  };

  return data.token;
}

تكامل المحافظ الإلكترونية

// للمحافظ الإلكترونية (فودافون كاش، أورانج موني)
async createWalletPayment(params) {
  const authToken = await getAuthToken();

  // تسجيل الطلب
  const orderResponse = await fetch(
    `${PAYMOB_CONFIG.baseUrl}/ecommerce/orders`,
    {
      method: 'POST',
      body: JSON.stringify({
        auth_token: authToken,
        amount_cents: params.amountCents,
        currency: params.currency,
        merchant_order_id: params.orderId,
      }),
    }
  );

  const orderData = await orderResponse.json();

  // إنشاء مفتاح الدفع للمحفظة
  const paymentKeyResponse = await fetch(
    `${PAYMOB_CONFIG.baseUrl}/acceptance/payment_keys`,
    {
      method: 'POST',
      body: JSON.stringify({
        auth_token: authToken,
        amount_cents: params.amountCents,
        order_id: orderData.id,
        integration_id: PAYMOB_CONFIG.walletIntegrationId,
        billing_data: { /* ... */ },
      }),
    }
  );

  // بدء دفع المحفظة
  const walletResponse = await fetch(
    `${PAYMOB_CONFIG.baseUrl}/acceptance/payments/pay`,
    {
      method: 'POST',
      body: JSON.stringify({
        source: {
          identifier: params.walletPhone,
          subtype: 'WALLET',
        },
        payment_token: paymentKeyData.token,
      }),
    }
  );

  return { redirectUrl: walletData.redirect_url };
}

أمان ومعالجة Webhooks

التحقق من HMAC

export function verifyPaymobHmac(data: any, receivedHmac: string): boolean {
  // يتم حساب HMAC من حقول محددة بترتيب معين
  const hmacString = [
    data.amount_cents,
    data.created_at,
    data.currency,
    data.error_occured,
    // ... الحقول الأخرى بالترتيب الصحيح
    data.success,
  ].join('');

  const calculatedHmac = crypto
    .createHmac('sha512', PAYMOB_CONFIG.hmacSecret)
    .update(hmacString)
    .digest('hex');

  return calculatedHmac === receivedHmac;
}

التعامل مع خصوصيات السوق المصري

التحقق من أرقام الهواتف المصرية

// أرقام الجوال المصرية: 01x xxxx xxxx (11 رقم)
export function validateEgyptianPhone(phone: string): boolean {
  const cleaned = phone.replace(/\D/g, '');
  const normalized = cleaned.startsWith('20') 
    ? cleaned.slice(2) 
    : cleaned;

  return /^01[0125][0-9]{8}$/.test(normalized);
}

// كشف شركة الاتصالات للمحافظ
export function detectCarrier(phone: string) {
  const prefix = phone.replace(/\D/g, '').slice(-10, -7);
  const carriers = {
    '010': 'vodafone',
    '011': 'etisalat',
    '012': 'orange',
    '015': 'we',
  };
  return carriers[prefix];
}

الأخطاء الشائعة في التكامل

1. انتهاء صلاحية رمز المصادقة

// ❌ سيء: الحصول على رمز جديد لكل طلب
const token = await getNewAuthToken(); // مضيعة!

// ✅ جيد: استخدام الذاكرة المؤقتة
const token = await getAuthToken(); // يستخدم الذاكرة المؤقتة

2. حقول بيانات الفوترة المفقودة

// ✅ جيد: جميع الحقول مطلوبة (استخدم 'NA' للمفقودة)
const billingData = {
  apartment: customer.apartment || 'NA',
  floor: customer.floor || 'NA',
  street: customer.street || 'NA',
  // ... جميع الحقول الأخرى
};

الخلاصة

تكامل Paymob يتطلب فهم:

1. التدفق متعدد الخطوات - مصادقة ← طلب ← مفتاح دفع ← دفع
2. تخزين الرمز مؤقتاً - إعادة استخدام رموز المصادقة (صالحة لساعة)
3. المحافظ الإلكترونية - معرف تكامل وتدفق مختلف
4. أمان HMAC - ترتيب الحقول مهم
5. خصوصيات مصر - تنسيقات الهاتف، معالجة العملة

للتجارة الإلكترونية المصرية، Paymob ضرورية. أتقن هذه الأنماط وستحصل على أساس دفع موثوق.