كيفية إنشاء Callback Endpoint

هذا الدليل يشرح ما الذي يحتاجه endpoint في موقعك ليستقبل طلبات الإكمال من نظامنا.

ما هو Callback Endpoint؟

هو رابط داخل موقعك/نظامك نستدعيه نحن (بطريقة GET) بعد نجاح المطابقة وتحويل العملية إلى completed.

وظيفته الأساسية: استقبال بيانات العملية وتنفيذ الإجراء المطلوب في قاعدة بياناتك (مثل شحن رصيد أو إكمال طلب).

أين أضع هذا endpoint؟

ضعه داخل backend موقعك (وليس في الواجهة الأمامية).

مثال أسماء مناسبة:

• /payment/callback
• /api/vfc/callback
• /wallet/topup/callback

مع WordPress وإضافتنا غالبًا يكون المسار /wp-json/vodafoncash/v1/callback على موقعك؛ خيار نوع الموقع «WordPress» في لوحة المستأجر يساعد على تعبئة هذا الرابط مسبقًا — راجع تكامل WordPress.

شكل الطلب المتوقع (مثال عام)

قد تختلف الأسماء الدقيقة للحقول حسب إعدادات المتجر/الإصدار، لكن هذا مثال عملي شائع.

GET https://your-site.com/payment/callback?transaction_id=123&phone=01000000000&amount=100&currency=EGP&store_id=2&user_name=customer_001&status=completed

ماذا يجب أن يفعل endpoint؟

عند استقبال الطلب:

1. اقرأ القيم من query parameters.
2. تحقّق أن الحالة مناسبة (مثل status=completed).
3. نفّذ منطقك التجاري:
   • شحن رصيد
   • إكمال طلب
   • تفعيل خدمة
4. احفظ Log داخلي للطلب.
5. ارجع استجابة 200 OK.

التحقق والأمان (مهم)

• لا تعتمد على الواجهة الأمامية في تنفيذ هذا المنطق.
• نفّذ التحقق داخل السيرفر فقط.
• اربط التنفيذ بمعرّف عملية فريد (transaction_id) لتجنب التكرار.
• اجعل العملية idempotent (إذا جاء نفس الطلب مرتين لا يتم التكرار في الرصيد/الطلب).

اختبار endpoint بسرعة

قبل ربطه في إعدادات المتجر:

1. جرّب endpoint يدويًا في المتصفح/Postman بنفس شكل query.
2. تأكد أن DB تتحدث كما تتوقع.
3. تأكد أن endpoint يرجع 200 OK.

بعد ذلك ضعه في إعدادات المتجر كـ callback endpoint.