تكامل HyperPay للدفع في السعودية والخليج: دليل المطور الكامل

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

1. لماذا تهيمن HyperPay على مدفوعات الخليج
2. بنية التكامل
3. إعداد الدفع من جانب الخادم
4. تكامل Copy and Pay
5. معالجة بطاقات مدى
6. تكامل STC Pay
7. إدارة Webhooks والمعاملات
8. اعتبارات الامتثال لـ SAMA

لماذا تهيمن HyperPay على مدفوعات الخليج

HyperPay هي بوابة الدفع الرائدة في المملكة العربية السعودية ومنطقة الخليج الأوسع. بعد دمج HyperPay لعدة منصات تجارة إلكترونية سعودية، إليك لماذا هي مهمة:

• دعم مدى - الطريقة الوحيدة لقبول بطاقات الخصم السعودية (أكثر من 70% من المعاملات)
• STC Pay - أشهر محفظة إلكترونية في السعودية
• مرخصة من SAMA - امتثال تنظيمي كامل في السعودية
• الاستحواذ المحلي - اتصالات مباشرة مع البنوك السعودية

إذا كنت تبني للسعودية، HyperPay ليست اختيارية - إنها إلزامية لقبول بطاقات مدى.

بنية التكامل

تستخدم HyperPay عملية من خطوتين:

الخطوة 1: إعداد الدفع (جانب الخادم) → الحصول على checkoutId
الخطوة 2: عرض نموذج الدفع (جانب العميل) → Copy and Pay Widget
الخطوة 3: التحقق من النتيجة → GET /checkouts/{id}/payment

إعداد الدفع من جانب الخادم

التكوين

export const HYPERPAY_CONFIG = {
  baseUrl: process.env.NODE_ENV === 'production'
    ? 'https://oppwa.com'
    : 'https://eu-test.oppwa.com',
  entityId: process.env.HYPERPAY_ENTITY_ID!,
  accessToken: process.env.HYPERPAY_ACCESS_TOKEN!,
  // معرفات كيان منفصلة لطرق الدفع المختلفة
  madaEntityId: process.env.HYPERPAY_MADA_ENTITY_ID!,
  stcPayEntityId: process.env.HYPERPAY_STC_PAY_ENTITY_ID!,
};

خدمة إعداد الدفع

async prepareCheckout(params: PrepareCheckoutParams) {
  const entityId = this.getEntityId(params.paymentBrands);

  const requestBody = new URLSearchParams({
    entityId,
    amount: params.amount.toFixed(2),
    currency: params.currency,
    paymentType: params.paymentType,
    'customer.email': params.customer.email,
    merchantTransactionId: params.orderId,
  });

  const response = await fetch(
    `${HYPERPAY_CONFIG.baseUrl}/v1/checkouts`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${HYPERPAY_CONFIG.accessToken}`,
        'Content-Type': 'application/x-www-form-urlencoded',
      },
      body: requestBody.toString(),
    }
  );

  const data = await response.json();
  return { checkoutId: data.id, entityId };
}

معالجة بطاقات مدى

بطاقات مدى تتطلب معالجة خاصة:

كشف BIN لتوجيه البطاقات

const MADA_BINS = [
  '440647', '440795', '446404', '457865', '458456',
  // ... المزيد من أرقام BIN
];

export function isMadaCard(cardNumber: string): boolean {
  const bin = cardNumber.replace(/\s/g, '').slice(0, 6);
  return MADA_BINS.includes(bin);
}

اعتبارات الامتثال لـ SAMA

مؤسسة النقد العربي السعودي (SAMA) لديها متطلبات محددة:

1. توطين البيانات - يجب تخزين بيانات المعاملات في السعودية
2. مدى إلزامي - يجب دعم مدى للمعاملات المحلية
3. متطلبات الإيصال - حقول محددة يجب عرضها على الإيصالات
4. مهل الاسترداد - أطر زمنية محددة لمعالجة الاستردادات

الخلاصة

تكامل HyperPay يتطلب:

1. معرفات كيان متعددة - معرفات مختلفة لـ mada و STC Pay و Apple Pay
2. كشف BIN - توجيه بطاقات مدى بشكل صحيح
3. تدفق من خطوتين - إعداد الدفع ← عرض الـ widget
4. امتثال SAMA - اتباع المتطلبات التنظيمية السعودية

للتجارة الإلكترونية السعودية، HyperPay ضرورية. انجز تكامل مدى بشكل صحيح، وستخدم أكثر من 70% من عملائك.