واجهة برمجة تطبيقات الدفع في المغرب: دليل التكامل التقني 2026

مقدمة: لماذا يُحدث نهج API-first تحولا في الدفع بالمغرب

وصل سوق الدفع عبر الإنترنت في المغرب إلى نضج تقني يتطلب الآن عمليات تكامل متينة وبرمجية وقابلة للتوسع. لم يعد التجار المغاربة يكتفون بنماذج دفع عامة تعيد التوجيه إلى صفحات بنكية. يريدون تجارب مدمجة وتدفقات دفع محسنة وتحكما كاملا في مسار العميل.

يلبي نهج API-first هذا المطلب. بدلا من دمج أداة مبهمة، يتفاعل المطور مباشرة مع REST API لإنشاء المدفوعات وإدارة المبالغ المستردة وتخزين البطاقات بشكل آمن واستقبال الإشعارات في الوقت الفعلي. توفر هذه البنية مرونة كاملة: المواقع الإلكترونية وتطبيقات الهاتف المحمول وأنظمة ERP ومنصات SaaS والأسواق الإلكترونية يمكنها جميعا استهلاك نفس الواجهة البرمجية.

هذا الدليل موجه للمطورين والمهندسين المعماريين التقنيين ومديري التكنولوجيا الذين يرغبون في دمج حل دفع في المغرب عبر API. سنغطي مشهد واجهات برمجة التطبيقات المتاحة والبنية التقنية ونقاط النهاية الأساسية وتدفق 3D Secure وwebhooks والترميز وبيئة الاختبار وأفضل ممارسات الأمان. إذا كنت تقيم بوابة دفع في المغرب، فسيمنحك هذا الدليل المفاتيح التقنية لاتخاذ القرار الصحيح.

مشهد واجهات برمجة تطبيقات الدفع في المغرب

يقدم السوق المغربي عدة مقاربات لتكامل الدفع، لكل منها مستوى مختلف من التحكم والتعقيد.

إعادة التوجيه (صفحة الدفع المستضافة)

يعيد التاجر توجيه العميل إلى صفحة دفع يستضيفها المزود. هذا هو النهج التقليدي المستخدم من قبل CMI في المغرب. يرسل المطور معلمات المعاملة عبر نموذج POST، يدخل العميل بيانات بطاقته على صفحة المزود، ثم يُعاد توجيهه إلى موقع التاجر مع النتيجة. الميزة هي البساطة والامتثال لمعايير PCI (التاجر لا يلمس بيانات البطاقة أبدا). العيب هو عدم التحكم في تجربة المستخدم ومعدل التخلي المرتبط بإعادة التوجيه.

النموذج المدمج (حقول مستضافة / إطار مضمن)

يوفر المزود حقول إدخال آمنة (hosted fields) تندمج بصريا في نموذج التاجر. لا يغادر العميل الموقع أبدا. تُرسل بيانات البطاقة مباشرة إلى المزود عبر إطار مضمن آمن. يحتفظ التاجر بالتحكم في التصميم مع البقاء خارج نطاق PCI DSS لتخزين البيانات الحساسة.

API المباشرة (خادم إلى خادم)

يجمع التاجر بيانات البطاقة من جانب العميل (عبر SDK جافاسكريبت آمن)، يرمزها، ثم يرسل الرمز إلى خادمه الذي يستدعي API المزود. هذا هو النهج الأكثر مرونة لكنه يتطلب امتثال PCI SAQ A-EP أو أعلى. يقدم Chari Pay هذا النهج مع SDK عميل يرمز البيانات قبل أي إرسال إلى خادم التاجر.

مقارنة سريعة

بنية API: المبادئ الأساسية

تعتمد واجهة برمجة تطبيقات الدفع المصممة جيدا على اتفاقيات تقنية موحدة. فيما يلي المبادئ التي يجب إتقانها قبل بدء التكامل.

REST والموارد

تتبع واجهات برمجة تطبيقات الدفع الحديثة نموذج REST. كل كيان (دفع، استرداد، عميل، بطاقة) هو مورد يمكن الوصول إليه عبر نقطة نهاية مخصصة. تستخدم العمليات القياسية أفعال HTTP: POST للإنشاء، GET للقراءة، PUT/PATCH للتعديل، DELETE للحذف.

المصادقة

تعتمد المصادقة عادة على مفاتيح API. يتم توفير زوج من المفاتيح: مفتاح عام (قابل للاستخدام من جانب العميل للترميز) ومفتاح سري (قابل للاستخدام فقط من جانب الخادم للعمليات الحساسة). تُنقل المفاتيح عبر رأس HTTP Authorization: Bearer {secret_key}. تقدم بعض الواجهات البرمجية أيضا OAuth 2.0 للبنيات متعددة المستأجرين أو منصات السوق الإلكتروني.

إدارة الإصدارات

تستخدم واجهات برمجة التطبيقات الجادة إصدارات صريحة، إما في عنوان URL (/v1/payments) أو في رأس (API-Version: 2026-01). تضمن إدارة الإصدارات أن تكاملك لن ينقطع عند تحديث الواجهة البرمجية. تحقق من سياسة الإيقاف التدريجي لمزودك قبل البدء.

تحديد معدل الطلبات

تفرض واجهات برمجة التطبيقات حدودا على الطلبات لحماية البنية التحتية. تتراوح الحدود النموذجية بين 100 و1000 طلب في الدقيقة حسب نقطة النهاية. تتيح لك رؤوس الاستجابة (X-RateLimit-Remaining، X-RateLimit-Reset) إدارة التحكم في المعدل من جانب العميل. نفذ آلية إعادة المحاولة مع تراجع أسي للتعامل مع استجابات 429 (طلبات كثيرة جدا).

تنسيق الاستجابات

الاستجابات بتنسيق JSON. تتضمن كل استجابة رمز HTTP قياسي (200 للنجاح، 201 للإنشاء، 400 لخطأ التحقق، 401 لفشل المصادقة، 404 لمورد غير موجود، 500 لخطأ الخادم). يحتوي جسم الاستجابة على الكائن المنشأ أو المعدل، مع معرف فريد وحالة وبيانات وصفية.

نقاط النهاية الأساسية: دورة حياة الدفع

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

إنشاء دفعة

تنشئ نقطة النهاية POST /v1/payments نية دفع. يحتوي جسم الطلب على المبلغ (بالسنتيمات)، العملة (MAD)، مرجع فريد من جانب التاجر، عنوان URL لإرجاع العميل وعنوان URL لإشعار webhook. ترجع الاستجابة كائن دفع بمعرف فريد وحالة pending، وحسب وضع التكامل، عنوان URL لإعادة التوجيه أو client_secret لـ SDK جافاسكريبت.

التقاط دفعة

إذا كنت تستخدم وضع الالتقاط المؤجل (تفويض ثم التقاط)، فإن نقطة النهاية POST /v1/payments/{id}/capture تطلق الخصم الفعلي بعد التفويض. هذا الوضع مفيد للتجار الذين يريدون التحقق من توفر المخزون أو التحقق من صحة الطلب قبل خصم المبلغ من العميل.

استرداد دفعة

تنشئ نقطة النهاية POST /v1/payments/{id}/refunds استردادا كليا أو جزئيا. يحتوي جسم الطلب على المبلغ المراد استرداده (اختياري للاسترداد الكلي). يُسمح بعدة استردادات جزئية طالما أن المبلغ التراكمي لا يتجاوز المبلغ الأصلي. يعتمد الجدول الزمني لإيداع المبلغ في حساب العميل على البنك المصدر (عادة 5 إلى 10 أيام عمل في المغرب).

التحقق من الحالة

ترجع نقطة النهاية GET /v1/payments/{id} الحالة الكاملة للمعاملة: الحالة (pending، authorized، captured، refunded، failed)، المبلغ، العملة، طريقة الدفع، الطابع الزمني وسجل الأحداث. استخدم نقطة النهاية هذه للمطابقة وتتبع المعاملات في مكتبك الخلفي.

سرد المعاملات

ترجع نقطة النهاية GET /v1/payments قائمة مرقمة من المعاملات مع فلاتر متاحة: التاريخ، الحالة، المبلغ، المرجع. يستخدم الترقيم عادة مؤشرا أو زوج offset/limit. تغذي نقطة النهاية هذه لوحات المعلومات وصادرات المحاسبة وأدوات إعداد التقارير.

تدفق 3D Secure: التنفيذ التقني

3D Secure إلزامي في المغرب للمدفوعات بالبطاقة عبر الإنترنت. يتبع التنفيذ التقني تدفقا من ثلاث خطوات.

الخطوة 1: البدء

عند إنشاء الدفعة، تكتشف الواجهة البرمجية تلقائيا أن البطاقة تتطلب مصادقة 3D Secure. تحتوي الاستجابة على حالة requires_action وكائن next_action بنوع redirect_to_3ds وعنوان URL للمصادقة.

الخطوة 2: المصادقة

يُعاد توجيه العميل إلى صفحة المصادقة الخاصة ببنكه (أو إطار مضمن في 3DS 2.0). يدخل رمز OTP المستلم عبر الرسائل القصيرة أو يصادق عبر البيومترية. في 3D Secure 2.0، يمكن لتحليل المخاطر تفعيل تدفق بدون احتكاك (بدون تدخل العميل) للمعاملات منخفضة المخاطر.

الخطوة 3: الاستدعاء الراجع والإنهاء

بعد المصادقة، يُعاد توجيه العميل إلى عنوان URL للإرجاع الخاص بك. في الوقت نفسه، يُعلم webhook خادمك بالنتيجة. لا تعتمد أبدا على إعادة توجيه العميل فقط للتحقق من صحة الدفع. webhook هو مصدر الحقيقة. تحقق دائما من حالة الدفع عبر نقطة النهاية GET قبل تأكيد الطلب.

Webhooks: الإشعارات في الوقت الفعلي

Webhooks هي آلية الإشعار من خادم إلى خادم التي تُعلم تطبيقك بأحداث الدفع في الوقت الفعلي. إنها لا غنى عنها لتكامل موثوق.

التكوين

سجل عنوان URL لـ webhook في لوحة التحكم أو عبر الواجهة البرمجية. يجب أن يكون العنوان متاحا علنيا عبر HTTPS. حدد الأحداث التي تريد استقبالها: payment.completed، payment.failed، payment.refunded، payment.disputed.

التحقق من التوقيع

يتم توقيع كل webhook بمفتاحك السري. يضمن المزود توقيعا في رأس X-Webhook-Signature. يجب على خادمك إعادة حساب توقيع HMAC-SHA256 لجسم الطلب ومقارنته بالتوقيع المستلم. لا تعالج أبدا webhook بدون التحقق من التوقيع -- هذه ثغرة أمنية حرجة.

منطق إعادة المحاولة

إذا لم يستجب خادمك برمز 2xx خلال مهلة محددة (عادة 5 إلى 30 ثانية)، يعيد المزود إرسال webhook. تتبع إعادة المحاولات تراجعا أسيا: دقيقة واحدة، 5 دقائق، 30 دقيقة، ساعتان، 24 ساعة. بعد عدد أقصى من المحاولات (عادة 5 إلى 10)، يُعلم webhook كفاشل.

التكرارية

قد يُرسل نفس الحدث عدة مرات (إعادة محاولات، تكرارات الشبكة). يجب أن يكون معالجك تكراريا: عالج كل حدث مرة واحدة فقط بتخزين معرف الحدث والتحقق مما إذا كان قد تمت معالجته بالفعل قبل تنفيذ المنطق التجاري. بدون التكرارية، تخاطر بتأكيد طلب مرتين أو إرسال رسائل تأكيد مكررة.

الترميز: تخزين البطاقات بشكل آمن

يتيح الترميز تخزين مرجع آمن (رمز) لبطاقة بنكية دون التعامل مع البيانات الحساسة. إنه أساس الدفع بنقرة واحدة والاشتراكات المتكررة.

إنشاء رمز

يجمع SDK جافاسكريبت من جانب العميل معلومات البطاقة ويرسلها مباشرة إلى خادم المزود. في المقابل، يستقبل رمزا فريدا (tok_xxxx) يمثل البطاقة. يُنقل هذا الرمز إلى خادمك لإنشاء الدفعة. لا يرى التاجر أبدا رقم البطاقة الكامل.

ربط رمز بعميل

تربط نقطة النهاية POST /v1/customers/{id}/payment-methods رمزا بملف عميل. يمكن للعميل بعد ذلك العثور على بطاقاته المحفوظة في مشترياته المستقبلية. يقتصر العرض على الأرقام الأربعة الأخيرة والشبكة (Visa، Mastercard).

الدفع بالرمز (متكرر)

لخصم بطاقة محفوظة، استدعِ POST /v1/payments مع payment_method_id بدلا من رمز جديد. هذه هي الآلية المستخدمة للاشتراكات والفوترة المتكررة والدفع بنقرة واحدة. قد يكون 3D Secure مطلوبا عند الدفع الأول لكن معفى للمدفوعات اللاحقة إذا تمت مصادقة البطاقة ويملك التاجر تفويض خصم مباشر.

بيئة الاختبار والتجريب

لا يجب أن ينتقل أي تكامل إلى الإنتاج بدون مرحلة اختبار شاملة. تُكرر بيئة الاختبار سلوك واجهة برمجة تطبيقات الإنتاج ببيانات وهمية.

الوصول إلى بيئة الاختبار

يمكن الوصول إلى بيئة الاختبار عادة عبر نطاق فرعي مخصص (sandbox-api.example.com) أو عنوان URL أساسي مختلف. مفاتيح API التجريبية منفصلة عن مفاتيح الإنتاج. جميع المعاملات في بيئة الاختبار محاكاة ولا تولد أي حركة مالية حقيقية.

بطاقات الاختبار

يوفر المزود أرقام بطاقات اختبار لمحاكاة سيناريوهات مختلفة:

• دفع ناجح: بطاقة اختبار قياسية، ترجع حالة captured
• دفع مرفوض: بطاقة مكونة لتفعيل الرفض (أموال غير كافية، بطاقة منتهية الصلاحية)
• تحدي 3D Secure: بطاقة تفعل منهجيا مصادقة 3D Secure
• 3D Secure بدون احتكاك: بطاقة تمر في وضع بدون احتكاك دون تدخل
• مهلة زمنية: بطاقة تحاكي تجاوز مهلة الاستجابة

السيناريوهات المطلوب اختبارها

قبل الانتقال إلى الإنتاج، تحقق من كل سيناريو: دفع ناجح، دفع مرفوض، استرداد كلي، استرداد جزئي، مهلة الشبكة، webhook مستلم، webhook مفقود، تقديم مزدوج، مبلغ غير صالح، عملة غير صحيحة وانتهاء صلاحية الجلسة. الاختبار الدقيق في بيئة الاختبار يقلل بشكل كبير من الحوادث في الإنتاج.

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

الأمان ليس اختياريا في مجال الدفع. فيما يلي الممارسات الأساسية التي يجب تنفيذها.

HTTPS إلزامي

يجب أن تمر جميع الاتصالات مع الواجهة البرمجية عبر HTTPS مع TLS 1.2 كحد أدنى. ارفض أي اتصال غير مشفر. تحقق من شهادات SSL ولا تعطل أبدا التحقق من الشهادات في الكود الخاص بك، حتى في بيئة التطوير.

إدارة مفاتيح API

لا تخزن أبدا مفاتيح API في الكود المصدري. استخدم متغيرات البيئة أو مدير أسرار (Vault، AWS Secrets Manager، Azure Key Vault). فرق بين مفاتيح الاختبار والإنتاج. نفذ تدوير دوري للمفاتيح. قيد صلاحيات كل مفتاح إلى الحد الأدنى الضروري.

الامتثال لـ PCI DSS

يعتمد نطاق PCI على وضع التكامل الخاص بك. مع الترميز من جانب العميل (الحقول المستضافة أو SDK جافاسكريبت)، أنت في نطاق SAQ A أو SAQ A-EP، مما يعني أن بيانات البطاقة لا تمر أبدا عبر خوادمك. وثق وضع التكامل الخاص بك وأكمل استبيان التقييم الذاتي المقابل.

التحقق من صحة المدخلات

تحقق منهجيا من المبالغ والعملات والمراجع والمعلمات قبل إرسالها إلى الواجهة البرمجية. احمِ نقاط نهاية webhook ضد الحقن. سجل الأخطاء دون كشف البيانات الحساسة (أخفِ أرقام البطاقات، لا تسجل أبدا مفاتيح API).

أمثلة كود: تدفق دفع مبسط

فيما يلي أمثلة كود توضيحية لتدفق دفع أساسي ومعالج webhook.

إنشاء دفعة (Node.js)

const response = await fetch('https://api.charipay.ma/v1/payments', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.CHARIPAY_SECRET_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 15000,        // 150.00 درهم بالسنتيمات
    currency: 'MAD',
    reference: 'ORDER-2026-001',
    return_url: 'https://mysite.ma/payment/return',
    webhook_url: 'https://mysite.ma/api/webhooks/payment',
    payment_method: tokenId,  // رمز تم الحصول عليه عبر SDK العميل
  }),
});

const payment = await response.json();

if (payment.status === 'requires_action') {
  // إعادة توجيه العميل إلى عنوان URL لـ 3D Secure
  return redirect(payment.next_action.redirect_url);
}

معالج Webhook (Python)

import hmac
import hashlib

@app.route('/api/webhooks/payment', methods=['POST'])
def handle_webhook():
    payload = request.get_data()
    signature = request.headers.get('X-Webhook-Signature')

    # التحقق من التوقيع
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(signature, expected):
        return 'Invalid signature', 401

    event = request.get_json()

    # التحقق من التكرارية
    if event_already_processed(event['id']):
        return 'OK', 200

    # معالجة الحدث
    if event['type'] == 'payment.completed':
        order = get_order(event['data']['reference'])
        order.mark_as_paid()
        send_confirmation_email(order)

    mark_event_processed(event['id'])
    return 'OK', 200

هذه الأمثلة توضح المبادئ الأساسية. كيفها مع إطار العمل والبنية الخاصة بك. راجع وثائق واجهة برمجة تطبيقات Chari Pay للمواصفات الكاملة.

كيف يُسرع ChariBaaS تكاملك

يوفر ChariBaaS، من خلال Chari Pay، بنية تحتية للدفع مصممة للمطورين المغاربة. واجهة REST API موثقة بشكل شامل مع أمثلة بلغات متعددة. تتيح بيئة الاختبار اختبار جميع السيناريوهات دون مخاطر. تقلل حزم SDK لجافاسكريبت وPHP وPython من وقت التكامل. يرافق الدعم التقني فرق التطوير أثناء التكامل وما بعده.

سواء كنت تبني متجر Shopify أو متجر WooCommerce أو تطبيقا مخصصا، توفر واجهة برمجة تطبيقات Chari Pay المرونة والموثوقية اللازمة لقبول المدفوعات عبر الإنترنت والتحويلات البنكية في المغرب.

لبدء تكاملك، راجع الوثائق التقنية أو تواصل مع فريقنا للحصول على دعم مخصص.

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

ما هي واجهات برمجة تطبيقات الدفع المتاحة في المغرب؟

واجهات برمجة التطبيقات الرئيسية: Chari Pay (REST API حديثة، بيئة اختبار، وثائق كاملة)، CMI (API للتجارة الإلكترونية، إعادة توجيه)، Payzone (API متعددة القنوات). يقدم Chari Pay أكثر واجهة برمجة تطبيقات شمولا مع نقاط نهاية للمدفوعات والمبالغ المستردة والترميز والدفعات المتكررة وwebhooks.

كيف يمكنني اختبار تكامل الدفع في المغرب؟

استخدم بيئة الاختبار الخاصة بالمزود. يوفر Chari Pay بيئة اختبار كاملة مع بطاقات اختبار ومحاكاة 3D Secure وwebhooks تجريبية. اختبر جميع السيناريوهات: دفع ناجح، مرفوض، 3D Secure، استرداد، ومهلة زمنية.

هل webhooks ضرورية لتكامل الدفع؟

نعم، webhooks أساسية. تُعلمك في الوقت الفعلي بنتائج المعاملات (نجاح، فشل، استرداد). لا تعتمد أبدا على إعادة التوجيه من جانب العميل فقط -- webhook هو مصدر الحقيقة من جانب الخادم.

كم من الوقت يستغرق تكامل واجهة برمجة تطبيقات الدفع في المغرب؟

مع واجهة برمجة تطبيقات حديثة مثل Chari Pay: 2-5 أيام للتكامل الأساسي (دفع بسيط)، 1-2 أسابيع للتكامل الكامل (الدفعات المتكررة، الترميز، webhooks). تُسرع الوثائق وبيئة الاختبار العملية بشكل كبير.