الدليل التفاعلي للتكامل بين Intaleq و MTN

دليلك الكامل لفهم واختبار آلية الدفع عبر MTN. تم تصميم هذا الدليل لتسهيل عملية التطوير وضمان تكامل سلس وفعال.

آلية عمل دورة الدفع

1

إنشاء الفاتورة

يبدأ المستخدم (سائق/راكب) عملية الدفع من تطبيق Intaleq، فيقوم نظامنا بإنشاء فاتورة داخلية بحالة "انتظار".

2

استعلام MTN

عندما يقوم المستخدم بفتح تطبيق MTN Cash Mobile للدفع، يقوم سيرفر MTN بإرسال طلب استعلام إلى سيرفرنا باستخدام رقم هاتف المستخدم للتحقق من وجود فاتورة معلقة وقيمتها.

3

تأكيد الدفع

بعد أن يكمل المستخدم عملية الدفع بنجاح في تطبيق MTN، يقوم سيرفر MTN بإرسال طلب تأكيد (Webhook) إلى سيرفرنا يحتوي على تفاصيل العملية الناجحة.

4

إتمام العملية

يتحقق سيرفرنا من صحة طلب التأكيد، ويقوم بتحديث حالة الفاتورة إلى "مكتملة"، ثم يضيف الرصيد تلقائياً إلى محفظة المستخدم في تطبيق Intaleq.

آلية الحماية والتوثيق

لضمان أن جميع الطلبات تأتي من مصدر موثوق (سيرفرات MTN حصراً)، نعتمد على آلية المفتاح السري المشترك (Shared Secret Key). يجب على سيرفراتكم إرسال هذا المفتاح في كل طلب يتم إرساله إلى نقاط النهاية الخاصة بنا.

الهيدر المطلوب: X-AUTH-TOKEN

سيتم تزويدكم بالمفتاح السري (Secret Key) بشكل آمن عبر قنوات التواصل الرسمية.

زيادة مستوى الأمان: القائمة البيضاء (IP Whitelisting)

للوصول إلى أعلى مستويات الأمان وحماية التكامل، نعتمد آلية القائمة البيضاء لعناوين IP. هذه الآلية تضمن أن سيرفراتنا لن تقبل الطلبات إلا من سيرفرات MTN المصرح بها حصراً.

الإجراء المطلوب:

نرجو منكم تزويدنا بقائمة ثابتة وكاملة لجميع عناوين IP العامة (Public IPs) التي تستخدمونها لإرسال الطلبات إلى نقاط النهاية الخاصة بنا، ليقوم فريقنا بإضافتها إلى جدار الحماية.

نقاط النهاية (API Endpoints)

نقطة النهاية: الاستعلام عن فاتورة

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

تفاصيل الطلب:

Method: GET

URL:

https://walletintaleq.intaleq.xyz/v1/main/ride/mtn_new/query_mtn_invoice.php

Header: X-AUTH-TOKEN: [المفتاح السري]

Query Parameter:

  • phone_number (إلزامي): رقم هاتف المستخدم.

جرّب الآن:

الاستجابات المتوقعة:

// The response from the server will appear here...

نقطة النهاية: تأكيد الدفع (Webhook)

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

تفاصيل الطلب:

Method: POST

URL:

https://walletintaleq.intaleq.xyz/v1/main/ride/mtn_new/mtn_webhook_handler.php

Header: X-AUTH-TOKEN: [المفتاح السري]

Body (JSON): انظر هيكل البيانات أدناه.

جرّب الآن:

هيكل JSON Body والاستجابات المتوقعة:

// The response from the server will appear here...

// Example Request Body:
{
    "invoice_number": "MTN-FAKE-12345",
    "transaction_id": "MTN_TRX_ABC123456",
    "amount_paid": 50000.00,
    "status": "success",
    "payment_timestamp": "2023-03-15T12:00:00Z"
}