كيفية استخدام API آي-باي (iPay) لتكامل الدفع في 2026؟

خلاصة

تُمكن واجهة برمجة تطبيقات iPay (API) المطورين من دمج معالجة المدفوعات والفواتير والمعاملات المالية برمجيًا. تستخدم مصادقة OAuth 2.0 ومفتاح API، ونقاط نهاية RESTful للمدفوعات، والاسترداد، والمعاملات، والتسوية، مع متطلبات الامتثال لمعيار PCI DSS وحدود المعدل القياسية في الصناعة. يغطي هذا الدليل إعداد المصادقة، ومعالجة المدفوعات، ودمج الويب هوك، والامتثال الأمني، واستراتيجيات النشر للإنتاج.

مقدمة

تتجاوز معالجة المدفوعات الرقمية 8 تريليونات دولار سنويًا على مستوى العالم. بالنسبة للمطورين الذين يبنون منصات التجارة الإلكترونية، أو تطبيقات SaaS، أو حلول الأسواق، فإن دمج واجهة برمجة تطبيقات الدفع ليس اختياريًا - إنه ضروري لقبول مدفوعات العملاء بشكل آمن ومتوافق.

إليك الحقيقة: تخسر الشركات 5-10% من إيراداتها بسبب المدفوعات الفاشلة، والتسوية اليدوية، والاحتيال في الدفع. يؤدي دمج واجهة برمجة تطبيقات الدفع القوية إلى أتمتة معالجة المدفوعات، ويقلل من حالات الفشل باستخدام منطق إعادة المحاولة الذكي، ويمكّن التسوية التلقائية، وينفذ الكشف عن الاحتيال.

يرشدك هذا الدليل خلال عملية دمج واجهة برمجة تطبيقات الدفع الكاملة. ستتعلم إعداد المصادقة، ومعالجة المدفوعات، وإدارة الاسترداد، والتعامل مع الويب هوك، والامتثال لمعيار PCI DSS، وأفضل ممارسات الأمان، واستراتيجيات النشر للإنتاج. بحلول النهاية، سيكون لديك دمج دفع جاهز للإنتاج.

ملاحظة: يغطي هذا الدليل أنماط دمج واجهة برمجة تطبيقات الدفع العامة التي تنطبق على iPay ومعالجات الدفع المماثلة. قد تختلف عناوين URL لنقطة النهاية وتفاصيل المصادقة - ارجع دائمًا إلى وثائق iPay الرسمية للحصول على تفاصيل التنفيذ.

ما هي واجهة برمجة تطبيقات iPay؟

توفر واجهات برمجة تطبيقات الدفع مثل iPay واجهات RESTful لمعالجة المعاملات المالية. تتعامل واجهة برمجة التطبيقات مع:

• تفويض الدفع والتقاطه
• المبالغ المستردة وعمليات رد المبالغ المدفوعة
• سجل المعاملات والتقارير
• ترميز العملاء (الخزنة)
• الاشتراكات والفواتير المتكررة
• إنشاء الفواتير وإدارتها
• المصالحة والتسوية
• الكشف عن الاحتيال ومنعه

الميزات الرئيسية

نظرة عامة على سير عمل الدفع

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   Customer  │───▶│   Merchant  │───▶│  Payment    │
│   (Browser) │    │   (Server)  │    │  Gateway    │
└─────────────┘    └─────────────┘    └─────────────┘
     │                    │                    │
     │  1. Enter Card     │                    │
     │───────────────────▶│                    │
     │                    │                    │
     │  2. Tokenize       │                    │
     │───────────────────▶│  3. Create Intent  │
     │                    │───────────────────▶│
     │                    │                    │
     │                    │  4. Confirm Payment│
     │                    │───────────────────▶│
     │                    │                    │
     │                    │  5. Result         │
     │                    │◀───────────────────│
     │                    │                    │
     │  6. Receipt        │                    │
     │◀───────────────────│                    │

بيئة واجهة برمجة التطبيقات

البدء: إعداد المصادقة

الخطوة 1: إنشاء حساب iPay

قبل الوصول إلى واجهة برمجة التطبيقات:

1. تفضل بزيارة صفحة تسجيل التجار في iPay
2. أكمل التحقق التجاري (KYB)
3. قدم المستندات المطلوبة:

• تسجيل النشاط التجاري
• تفاصيل الحساب المصرفي
• وثيقة هوية حكومية

1. انتظر الموافقة (1-3 أيام عمل)

الخطوة 2: الحصول على بيانات اعتماد واجهة برمجة التطبيقات

إنشاء بيانات اعتماد واجهة برمجة التطبيقات:

1. سجل الدخول إلى لوحة تحكم التاجر في iPay
2. انتقل إلى الإعدادات > مفاتيح API
3. أنشئ مفتاح API جديدًا
4. انسخ بيانات الاعتماد بأمان

# .env file (NEVER commit to git)
IPAY_API_KEY="live_xxxxxxxxxxxxxxxxxxxx"
IPAY_API_SECRET="secret_xxxxxxxxxxxxxxxxxxxx"
IPAY_WEBHOOK_SECRET="whsec_xxxxxxxxxxxxxxxxxxxx"

ملاحظة أمنية: استخدم مفاتيح منفصلة لبيئة الاختبار (sandbox) وبيئة الإنتاج (production).

الخطوة 3: فهم طرق المصادقة

تدعم iPay طرق مصادقة متعددة:

الخطوة 4: إجراء استدعاءات API موثقة

إنشاء عميل API قابل لإعادة الاستخدام:

const IPAY_BASE_URL = process.env.IPAY_SANDBOX
  ? 'https://sandbox.ipay.com/api'
  : 'https://api.ipay.com/api';

const ipayRequest = async (endpoint, options = {}) => {
  const apiKey = process.env.IPAY_API_KEY;
  const apiSecret = process.env.IPAY_API_SECRET;

  // Basic authentication (Base64 encoded)
  const authHeader = Buffer.from(`${apiKey}:${apiSecret}`).toString('base64');

  const response = await fetch(`${IPAY_BASE_URL}${endpoint}`, {
    ...options,
    headers: {
      'Authorization': `Basic ${authHeader}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': options.idempotencyKey || generateIdempotencyKey(),
      ...options.headers
    }
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`iPay API Error: ${error.message}`);
  }

  return response.json();
};

function generateIdempotencyKey() {
  return `req_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
}

// Usage
const account = await ipayRequest('/account');
console.log(`Merchant: ${account.business_name}`);

معالجة المدفوعات

إنشاء نية دفع

تهيئة الدفع:

const createPayment = async (paymentData) => {
  const payment = {
    amount: paymentData.amount, // In smallest currency unit (cents)
    currency: paymentData.currency || 'USD',
    customer: paymentData.customerId,
    payment_method: paymentData.paymentMethodId,
    confirm: true,
    description: paymentData.description,
    metadata: {
      orderId: paymentData.orderId,
      customerId: paymentData.customerId
    },
    capture_method: paymentData.captureMethod || 'automatic', // 'automatic' or 'manual'
    statement_descriptor: paymentData.statementDescriptor || 'MYCOMPANY'
  };

  const response = await ipayRequest('/payments', {
    method: 'POST',
    body: JSON.stringify(payment),
    idempotencyKey: paymentData.idempotencyKey
  });

  return response;
};

// Usage
const payment = await createPayment({
  amount: 2999, // $29.99
  currency: 'USD',
  customerId: 'cus_12345',
  paymentMethodId: 'pm_67890',
  description: 'Order #ORD-001',
  orderId: 'ORD-001',
  statementDescriptor: 'MYCOMPANY INC'
});

console.log(`Payment status: ${payment.status}`);
console.log(`Payment ID: ${payment.id}`);

تدفق حالة الدفع

requires_payment_method → requires_confirmation → requires_action
                         → processing → requires_capture → succeeded
                                                        → failed
                                                        → canceled

طرق الدفع

ترميز تفاصيل البطاقة

تخزين البطاقة بأمان للاستخدام المستقبلي:

const tokenizeCard = async (cardData) => {
  // NEVER send raw card data to your server
  // Use client-side tokenization instead

  // Client-side (browser/mobile)
  const response = await fetch(`${IPAY_BASE_URL}/tokens`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${CLIENT_PUBLISHABLE_KEY}`
    },
    body: JSON.stringify({
      card: {
        number: cardData.number,
        exp_month: cardData.expMonth,
        exp_year: cardData.expYear,
        cvc: cardData.cvc
      }
    })
  });

  const token = await response.json();
  return token; // Send token.id to your server
};

// Server-side: Use token to create payment method
const createPaymentMethod = async (tokenId, customerId) => {
  const response = await ipayRequest('/payment_methods', {
    method: 'POST',
    body: JSON.stringify({
      type: 'card',
      token: tokenId,
      customer: customerId
    })
  });

  return response;
};

مصادقة 3D Secure

تطبيق الامتثال لمعيار SCA:

const createPaymentWith3DS = async (paymentData) => {
  const payment = await createPayment({
    ...paymentData,
    confirmation_token: true // Return client secret for 3DS
  });

  if (payment.status === 'requires_action') {
    // Client must complete 3DS challenge
    return {
      requiresAction: true,
      clientSecret: payment.client_secret,
      nextAction: payment.next_action
    };
  }

  return { success: true, payment };
};

// Client-side: Handle 3DS challenge
// Use iPay.js or mobile SDK to present authentication challenge

إدارة المبالغ المستردة

معالجة استرداد كامل

استرداد كامل للدفع:

const refundPayment = async (paymentId, reason = null) => {
  const refund = {
    payment: paymentId,
    reason: reason || 'requested_by_customer'
  };

  const response = await ipayRequest('/refunds', {
    method: 'POST',
    body: JSON.stringify(refund),
    idempotencyKey: `refund_${paymentId}_${Date.now()}`
  });

  return response;
};

// Usage
const refund = await refundPayment('pay_12345', 'duplicate');
console.log(`Refund status: ${refund.status}`);
console.log(`Refund ID: ${refund.id}`);

معالجة استرداد جزئي

استرداد جزء من الدفع:

const partialRefund = async (paymentId, amount, reason = null) => {
  const refund = {
    payment: paymentId,
    amount: amount, // In smallest currency unit
    reason: reason || 'requested_by_customer'
  };

  const response = await ipayRequest('/refunds', {
    method: 'POST',
    body: JSON.stringify(refund),
    idempotencyKey: `refund_${paymentId}_${amount}_${Date.now()}`
  });

  return response;
};

// Usage - Refund $15.00 of $29.99 payment
const refund = await partialRefund('pay_12345', 1500, 'partial_ship');
console.log(`Refunded: $${refund.amount / 100}`);

أسباب الاسترداد

إدارة العملاء

إنشاء عميل

تخزين العميل للمدفوعات المتكررة:

const createCustomer = async (customerData) => {
  const customer = {
    email: customerData.email,
    name: customerData.name,
    phone: customerData.phone,
    metadata: {
      internalId: customerData.internalId,
      tier: customerData.tier
    }
  };

  const response = await ipayRequest('/customers', {
    method: 'POST',
    body: JSON.stringify(customer)
  });

  return response;
};

// Usage
const customer = await createCustomer({
  email: 'customer@example.com',
  name: 'John Doe',
  phone: '+1-555-0123',
  internalId: 'USR-12345',
  tier: 'premium'
});

console.log(`Customer created: ${customer.id}`);

إرفاق طريقة دفع بالعميل

حفظ البطاقة للاستخدام المستقبلي:

const attachPaymentMethod = async (paymentMethodId, customerId) => {
  const response = await ipayRequest(`/payment_methods/${paymentMethodId}/attach`, {
    method: 'POST',
    body: JSON.stringify({
      customer: customerId
    })
  });

  return response;
};

// Usage
await attachPaymentMethod('pm_67890', 'cus_12345');

إدراج طرق دفع العميل

الحصول على البطاقات المحفوظة:

const getCustomerPaymentMethods = async (customerId) => {
  const response = await ipayRequest(`/customers/${customerId}/payment_methods`);
  return response;
};

// Usage
const methods = await getCustomerPaymentMethods('cus_12345');
methods.data.forEach(method => {
  console.log(`${method.card.brand} ending in ${method.card.last4}`);
  console.log(`Expires: ${method.card.exp_month}/${method.card.exp_year}`);
});

الويب هوك (Webhooks)

تكوين الويب هوك

إعداد نقاط نهاية الويب هوك:

1. سجل الدخول إلى لوحة تحكم iPay
2. انتقل إلى المطورون > الويب هوك
3. انقر على إضافة نقطة نهاية
4. أدخل عنوان URL الخاص بك (HTTPS)
5. حدد الأحداث للاشتراك

أحداث الويب هوك

معالجة الويب هوك

const express = require('express');
const crypto = require('crypto');
const app = express();

app.post('/webhooks/ipay', express.raw({ type: 'application/json' }), async (req, res) => {
  const signature = req.headers['ipay-signature'];
  const payload = req.body;

  // Verify webhook signature
  const isValid = verifyWebhookSignature(payload, signature, process.env.IPAY_WEBHOOK_SECRET);

  if (!isValid) {
    console.error('Invalid webhook signature');
    return res.status(401).send('Unauthorized');
  }

  const event = JSON.parse(payload.toString());

  // Route to appropriate handler
  switch (event.type) {
    case 'payment.succeeded':
      await handlePaymentSucceeded(event.data);
      break;
    case 'payment.failed':
      await handlePaymentFailed(event.data);
      break;
    case 'payment.refunded':
      await handlePaymentRefunded(event.data);
      break;
    case 'payment.disputed':
      await handlePaymentDisputed(event.data);
      break;
    default:
      console.log('Unhandled event type:', event.type);
  }

  // Acknowledge receipt
  res.status(200).send('OK');
});

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}

async function handlePaymentSucceeded(data) {
  console.log(`Payment succeeded: ${data.id}`);

  // Update order status
  await db.orders.update(data.metadata.orderId, {
    status: 'paid',
    paymentId: data.id,
    paidAt: new Date()
  });

  // Send confirmation email
  await sendOrderConfirmation(data.metadata.orderId);
}

async function handlePaymentFailed(data) {
  console.log(`Payment failed: ${data.id} - ${data.failure_code}`);

  // Notify customer
  await sendPaymentFailedEmail(data.customer, data.failure_message);

  // Retry logic or mark order as failed
  await db.orders.update(data.metadata.orderId, {
    status: 'payment_failed',
    failureReason: data.failure_message
  });
}

الأمان والامتثال

متطلبات PCI DSS

يجب أن تتوافق عمليات دمج الدفع مع معيار PCI DSS:

أفضل ممارسات الأمان

// 1. Use tokenization - NEVER handle raw card data
const token = await tokenizeCard(cardData); // Client-side

// 2. Implement idempotency for all payment operations
const idempotencyKey = `pay_${orderId}_${Date.now()}`;

// 3. Validate amounts server-side
if (req.body.amount !== calculatedAmount) {
  throw new Error('Amount mismatch - possible tampering');
}

// 4. Log all payment operations (without sensitive data)
logger.info('Payment attempted', {
  orderId,
  amount,
  currency,
  customerId,
  timestamp: new Date().toISOString()
  // NEVER log: card numbers, CVV, full payment method details
});

// 5. Use environment variables for secrets
const apiKey = process.env.IPAY_API_KEY; // Not hardcoded

// 6. Implement rate limiting on payment endpoints
const paymentLimiter = rateLimit({
  windowMs: 60000,
  max: 10 // 10 payment attempts per minute
});

قائمة التحقق من نشر الإنتاج

قبل معالجة المدفوعات المباشرة:

• [ ] أكمل استبيان التقييم الذاتي لـ PCI DSS
• [ ] استخدم HTTPS لجميع نقاط النهاية
• [ ] قم بتخزين مفاتيح API في إدارة آمنة للأسرار
• [ ] نفذ التحقق من توقيع الويب هوك
• [ ] أضف خاصية عدم التكرارية (idempotency) لجميع عمليات الدفع
• [ ] أعد إعداد تسجيل شامل (بدون بيانات حساسة)
• [ ] قم بتكوين قواعد الكشف عن الاحتيال
• [ ] اختبر تدفقات الاسترداد والنزاعات
• [ ] أنشئ دليل تشغيل لإخفاقات الدفع
• [ ] أعد إعداد المراقبة والتنبيه
• [ ] طبق معالج دفع احتياطي

حالات الاستخدام في العالم الحقيقي

الدفع في التجارة الإلكترونية

يقوم بائع تجزئة عبر الإنترنت بدمج المدفوعات:

• التحدي: معالجة المدفوعات اليدوية، معدل تخلي مرتفع عن الشراء
• الحل: صفحة دفع واحدة مع بطاقات مرمزة
• النتيجة: زيادة في التحويل بنسبة 35%، مدفوعات فورية

فوترة الاشتراكات لـ SaaS

تقوم شركة برمجيات بأتمتة الفوترة:

• التحدي: إنشاء الفواتير وتحصيلها يدويًا
• الحل: مدفوعات متكررة مع إعادة محاولة تلقائية
• النتيجة: 95% دفع في الوقت المحدد، توفير 80% من وقت الإدارة

الضمان في السوق (Marketplace Escrow)

تتعامل المنصة مع مدفوعات متعددة الأطراف:

• التحدي: مدفوعات مقسمة معقدة بين البائعين
• الحل: نوايا الدفع مع جدولة التحويلات
• النتيجة: مدفوعات تلقائية للبائعين، انخفاض الاحتيال

الخاتمة

يتطلب دمج واجهة برمجة تطبيقات الدفع اهتمامًا دقيقًا بالأمان والامتثال ومعالجة الأخطاء. النقاط الرئيسية:

• لا تتعامل أبدًا مع بيانات البطاقة الخام - استخدم الترميز (tokenization)
• طبق خاصية عدم التكرارية (idempotency) لجميع عمليات الدفع
• تحقق من توقيعات الويب هوك لمنع الاحتيال
• امتثل لمتطلبات PCI DSS
• اختبر بدقة في بيئة الاختبار (sandbox) قبل الإنتاج
• يعمل Apidog على تبسيط اختبار API والتعاون الجماعي

قسم الأسئلة الشائعة

كيف أقوم بالمصادقة مع واجهة برمجة تطبيقات iPay؟

استخدم المصادقة الأساسية (Basic authentication) مع مفتاح API وسر، أو OAuth 2.0 للتطبيقات متعددة المستأجرين.

هل يمكنني تخزين تفاصيل بطاقة العميل؟

نعم، ولكن يجب أن تكون متوافقًا مع PCI DSS. استخدم الترميز (tokenization) لتخزين البطاقات بأمان في خزنة iPay.

كيف أتعامل مع المدفوعات الفاشلة؟

طبق منطق إعادة المحاولة مع التراجع الأسي (exponential backoff)، وأبلغ العملاء، ووفر طرق دفع بديلة.

ما هي خاصية عدم التكرارية (Idempotency) ولماذا هي مهمة؟

تضمن خاصية عدم التكرارية أن الطلبات المكررة بنفس المفتاح تنتج نفس النتيجة، مما يمنع رسومًا مكررة.

كيف يمكنني اختبار المدفوعات دون فرض رسوم على البطاقات؟

استخدم وضع الاختبار (sandbox) مع أرقام بطاقات الاختبار المتوفرة في وثائق iPay.

ما هي توقيعات الويب هوك؟

توقيعات تشفيرية تتحقق من أن الويب هوك جاءت من iPay، وليس من جهة خبيثة.