دمج مدفوعات Wave وOrange Money وStripe في QloApps: درس 2026

📍 المقالة الرئيسية للمجموعة: نظام حجز فندقي 2026.

60-70% من زبائنك المحليين يفضلون mobile money: Wave في السنغال، Orange Money في كوت ديفوار، Free Money في السنغال، MTN MoMo، CMI/CIB في المغرب. Booking.com يقبل فقط البطاقات الدولية، ما يستثني هذه القاعدة الكبيرة. دمج passerelles دفع محلية في QloApps يفتح هذه السوق ويزيد التحويل بـ 30-50%. هذا الدرس يفصل التكامل الكامل المُختبَر عند فنادق المغرب والسنغال وكوت ديفوار.

المتطلبات

QloApps في الإنتاج (راجع درس النشر). حسابات تاجر: Wave Business، Orange Money Business، CMI/CIB merchant، Stripe. المستوى المتوقع: متوسط/متقدم (PHP، REST APIs، webhooks). الوقت المقدر: 4 إلى 6 ساعات لجميع التكاملات.

استراتيجية متعددة passerelles

هدف: عرض كل طريقة دفع للزبون حسب موقعه. الزبائن المغاربة: CMI، CIB، Stripe (للبطاقات الدولية)، Cash on Arrival. الزبائن السنغاليون: Wave، Orange Money، Free Money، Stripe. الزبائن الإيفواريون: Orange Money، Wave، MTN MoMo، Stripe. الزبائن الدوليون: Stripe (Visa، Mastercard، Apple Pay)، PayPal. هذه الاستراتيجية المتعددة تزيد التحويل بـ 30-50%.

1. تكامل Wave

Wave Business يقدم API REST بسيط. تسجيل: business.wave.com → API access. تستلم API_KEY و SECRET. التكامل عبر webhook custom في QloApps.

إنشاء مديول QloApps: /var/www/qloapps/modules/wave_payment/. ملف wave_payment.php:

<?php
class WavePayment extends PaymentModule {
  public function __construct() {
    $this->name = 'wave_payment';
    $this->displayName = 'Wave Mobile Money';
    parent::__construct();
  }
  
  public function hookPaymentOptions($params) {
    $option = new PaymentOption();
    $option->setCallToActionText('Payer avec Wave')
           ->setAction($this->context->link->getModuleLink($this->name, 'redirect'))
           ->setLogo('/modules/wave_payment/wave-logo.png');
    return [$option];
  }
}

صفحة redirect.php تنشئ checkout session عبر Wave API:

$response = Tools::file_get_contents('https://api.wave.com/v1/checkout/sessions', [
  'http' => [
    'method' => 'POST',
    'header' => 'Authorization: Bearer ' . Configuration::get('WAVE_API_KEY'),
    'content' => json_encode([
      'amount' => $cart_total,
      'currency' => 'XOF',
      'success_url' => $success_url,
      'error_url' => $error_url
    ])
  ]
]);
$wave_session = json_decode($response);
Tools::redirect($wave_session->wave_launch_url);

Webhook callback عند الدفع:

// /modules/wave_payment/webhook.php
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_WAVE_SIGNATURE'];

// تحقق signature HMAC-SHA256
if (!hash_equals(hash_hmac('sha256', $payload, $secret), $signature)) {
  http_response_code(403);
  die('Invalid signature');
}

$event = json_decode($payload);
if ($event->type === 'checkout.session.completed') {
  // تأكيد الطلب في QloApps
  $order = new Order($event->data->client_reference);
  $order->setCurrentState(Configuration::get('PS_OS_PAYMENT'));
  $order->save();
}

2. تكامل Orange Money

Orange Money Business API متاح في السنغال وكوت ديفوار وكاميرون ومالي. تسجيل: developer.orange.com → Orange Money API. تحقق KYC يأخذ 5-10 أيام.

// 1. الحصول على access token
$token_response = file_get_contents('https://api.orange.com/oauth/v3/token', false, stream_context_create([
  'http' => [
    'method' => 'POST',
    'header' => "Authorization: Basic " . base64_encode($client_id.':'.$client_secret) . "\r\nContent-Type: application/x-www-form-urlencoded",
    'content' => 'grant_type=client_credentials'
  ]
]));
$token = json_decode($token_response)->access_token;

// 2. إنشاء transaction
$payment = file_get_contents('https://api.orange.com/orange-money-webpay/dev/v1/webpayment', false, stream_context_create([
  'http' => [
    'method' => 'POST',
    'header' => "Authorization: Bearer $token\r\nContent-Type: application/json",
    'content' => json_encode([
      'merchant_key' => $merchant_key,
      'currency' => 'XOF',
      'order_id' => $cart_id,
      'amount' => $amount,
      'return_url' => $return_url,
      'cancel_url' => $cancel_url,
      'notif_url' => $notif_url,
      'lang' => 'fr'
    ])
  ]
]));
$payment_data = json_decode($payment);
Tools::redirect($payment_data->payment_url);

3. تكامل CMI Maroc

CMI (Centre Monétique Interbancaire) هو passerelle المغربية للبطاقات. مديول مجتمعي مجاني لـ QloApps موجود.

cd /var/www/qloapps/modules
git clone https://github.com/community/cmi_qloapps cmi
chown -R www-data:www-data cmi/

Admin → Modules → CMI → Install. تكوين: Store ID (من CMI)، Store Key، Mode (test/production). CMI يستخدم 3D Secure إجباري للأمان.

4. تكامل Stripe

Stripe رسمي لـ QloApps. Admin → Modules → Stripe Payment → Install. أدخل: Publishable Key، Secret Key. اختبر مع البطاقة 4242 4242 4242 4242 (وضع test). Stripe يقبل: Visa، Mastercard، Apple Pay، Google Pay.

5. عرض ديناميكي حسب اللغة/البلد

عرض طرق الدفع المناسبة لزبون كل بلد. تحقق من $context->customer->country أو IP geolocation.

public function hookPaymentOptions($params) {
  $country = $params['cart']->id_country;
  $options = [];
  
  if (in_array($country, [SENEGAL, COTE_IVOIRE])) {
    $options[] = $this->getWaveOption();
    $options[] = $this->getOrangeMoneyOption();
  }
  if ($country == MAROC) {
    $options[] = $this->getCMIOption();
  }
  $options[] = $this->getStripeOption();  // دائماً
  
  return $options;
}

الأخطاء الشائعة

التكيف مع السياق

أربع توضيحات. الزمن الحقيقي vs Async. Wave وOrange Money غير متزامنان: الزبون يدفع، تستلم confirmation عبر webhook بعد 30-120 ثانية. أعرض «الدفع قيد المعالجة» قبل التأكيد. الـ refunds. Wave وOrange Money يدعمان refunds API لكن KYC إضافي. اخطط 5 أيام لتفعيل refund. الفواتير ضريبياً. المغرب TVA 10% على الفنادق. السنغال TVA 18%. كوّن في QloApps Localization. تجربة Apple Pay/Google Pay. شائعة عند الزبائن الدوليين. Stripe يدعم native. تكامل سهل بـ JS Stripe Elements.

دروس الإخوة

• نشر QloApps
• Channel manager

الأسئلة المتكررة

عمولة Wave مقابل Stripe؟ Wave: 1% (السنغال). Orange Money: 1.5%. Stripe: 2.9% + 0.30 USD. mobile money أرخص بكثير.

3DS إجباري؟ EU نعم (PSD2). إفريقيا اختياري لكن موصى به للأمان.

Refunds عبر Wave؟ نعم API، لكن KYC تاجر إجباري.

Cash on arrival؟ مدمج QloApps. غالباً 20-30% من الحجوزات في غرب إفريقيا.

السلسلة الفندقية؟ نفس API keys، تكوين مديول مرة واحدة.

للاستزادة

• 🔝 المرجع: نظام حجز 2026
• Wave docs: docs.wave.com
• Orange Money docs: developer.orange.com