VibeFox Worldline for OpenCart — المساعدة

المتطلبات

OpenCart: 3.0.x (تم الاختبار على 3.0.5.0) أو 4.0.2 وما بعده (تم الاختبار على 4.1.0.3).

PHP: 8.0 أو أحدث.

حساب Worldline: حساب تاجر لدى Worldline Direct (المعروفة سابقًا باسم Ingenico Direct). حسابا الاختبار والفعلي منفصلان ولكل منهما بيانات اعتماد مختلفة. لكل حساب تحتاج إلى Merchant ID (وهو PSPID الخاص بك)، و API Key ID مع Secret API Key المرتبط به، ومفتاح webhook مع السر الخاص به. تُنشأ جميعها في Worldline Merchant Portal (انظر الإعداد).

مفتاح ترخيص VibeFox: يُشترى من vibefox.net. يعمل المفتاح الواحد على نطاق واحد.

التثبيت

التنزيل ملف zip واحد يحتوي على الحزم لكلا إصداري OpenCart. فُكّ ضغطه على حاسوبك. يحتوي على README.txt وحزمة OpenCart 3 wcp_worldline_gateway-oc3-(version).ocmod.zip وحزمة OpenCart 4 wcp_worldline_gateway.ocmod.zip. ثبّت فقط الحزمة الخاصة بإصدار OpenCart لديك. مفتاح الترخيص هو نفسه لكلا الإصدارين.

OpenCart 3

1. في لوحة الإدارة، انتقل إلى Extensions > Installer، وانقر على Upload، ثم اختر الملف wcp_worldline_gateway-oc3-(version).ocmod.zip. لا تحتوي الإضافة على تعديلات OCMOD، لذلك لا يلزم تحديث Extensions > Modifications. بدلًا من المثبّت، يمكنك نسخ محتويات المجلد upload من هذه الحزمة إلى المجلد الجذر لمتجرك.

2. انتقل إلى Extensions > Extensions واختر النوع Payments. ابحث عن VibeFox Worldline Gateway وانقر على Install (زر + الأخضر). يحتاج مستخدم الإدارة لديك إلى صلاحية تعديل قائمة إضافات الدفع.

3. انقر على Edit (زر القلم) لفتح صفحة الإعدادات. أدخل مفتاح ترخيص VibeFox في License key داخل كتلة الترخيص في أعلى الصفحة، ثم انقر على Activate (انظر مفتاح الترخيص).

4. أدخل بيانات اعتماد الاختبار، ثم انقر على Save، ثم على Test credentials.

5. أضف عنوان URL الخاص بـ webhook في Merchant Portal لحساب الاختبار، وأدخل مفتاح webhook وسره (انظر الإعداد).

6. فعّل Enable/Disable، واحفظ، ثم أجرِ دفعة اختبارية. بعد ذلك أدخل بيانات الاعتماد الفعلية، وكرر إعداد webhook في حسابك الفعلي، وانقر على Live credentials، وأوقف Test Mode.

OpenCart 4

1. في لوحة الإدارة، انتقل إلى Extensions > Installer، وانقر على Upload، ثم اختر الملف wcp_worldline_gateway.ocmod.zip. لا تُغيّر اسم الملف: يأخذ OpenCart 4 رمز الإضافة من اسم الملف، والحزمة التي يُغيَّر اسمها لا تعمل.

2. تظهر الحزمة في قائمة الإضافات المثبتة في الصفحة نفسها. انقر على Install (زر + الأخضر) بجانبها.

3. انتقل إلى Extensions > Extensions واختر النوع Payments. ابحث عن VibeFox Worldline Gateway، وانقر على Install (زر + الأخضر)، ثم على Edit (زر القلم).

4. أدخل مفتاح الترخيص وبيانات الاعتماد والـ webhook كما في الخطوات من 3 إلى 6 لـ OpenCart 3. صفحة الإعدادات وحقولها متطابقة في الإصدارين. عنوان الـ webhook هو الوحيد المختلف (انظر Webhooks).

يبدأ التثبيت الجديد بوسيلة الدفع معطّلة ووضع الاختبار مُفعّلًا.

الإعداد

جميع الإعدادات موجودة في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox Worldline Gateway > Edit. تُدرج الأقسام على اليسار؛ يحفظ الزر Save أسفل القائمة الصفحة كاملة. فوق الإعدادات تحذّرك الصفحة إذا كانت بيانات اعتماد الوضع الحالي (Merchant ID وAPI Key ID وSecret API Key) غير مكتملة، لأن وسيلة الدفع تكون مخفية عند الدفع في هذه الحالة. وأثناء تفعيل وضع الاختبار تعرض Test mode is on (pre-production environment): no real money is charged. وبدون صلاحية تعديل الإضافة تعرض الصفحة الإعدادات لكنها لا تستطيع حفظها.

عند الحفظ، لا يمكن أن يكون Title فارغًا (128 حرفًا كحد أقصى)، ويجب أن يكون Sort Order عددًا صحيحًا (الأعداد السالبة مسموحة)، ويجب أن يكون Total رقمًا أكبر من أو يساوي 0، ويجب أن توجد المنطقة الجغرافية وحالات الطلب. وإلا فلن يُحفظ شيء وتُشير الصفحة إلى الحقل. لا تمنع البيانات غير المكتملة الحفظ.

Worldline (Ingenico)

Enable/Disable: يُفعّل Enable Worldline Gateway وسيلة الدفع أو يُعطّلها. الافتراضي: معطّل.

Title: اسم وسيلة الدفع الذي يراه العملاء عند الدفع، وهو أيضًا الاسم المحفوظ في الطلب. الافتراضي: Worldline. مطلوب، ويصل إلى 128 حرفًا.

Description: النص الذي يراه العميل في خطوة Confirm Order فوق زر التأكيد. الافتراضي: Pay securely via Worldline.

Sort Order: ترتيب Worldline بين وسائل الدفع عند الدفع. اتركه فارغًا أو أدخل عددًا صحيحًا.

Geo Zone: اعرض Worldline فقط لعناوين الدفع الواقعة ضمن المنطقة الجغرافية المختارة. الافتراضي: All zones. تُضبط المناطق الجغرافية في System > Localisation > Geo Zones.

Total: إجمالي الدفع، بعملة المتجر الافتراضية، الذي يجب أن يبلغه الطلب قبل عرض Worldline. اتركه فارغًا لعرض Worldline مع أي إجمالي.

Worldline Direct API

احصل على بيانات الاعتماد من Worldline Merchant Portal لحساب الاختبار وللحساب الفعلي. PSPID الخاص بك هو Merchant ID. يُنشئ Developer > Payment API مفتاح API Key ID وSecret API Key، ويُنشئ Developer > Webhooks مفتاح webhook وسره. تتضمن هذه الصفحة روابط إلى البوابتين ووثائق Worldline.

Test Mode: يبدّل نقطة نهاية الواجهة البرمجية وبيانات الاعتماد معًا. يستخدم وضع الاختبار بيئة ما قبل الإنتاج وبيانات الاعتماد التجريبية، ويستخدم الوضع الفعلي بيئة الإنتاج وبيانات الاعتماد الفعلية. الافتراضي: مُفعّل. أوقفه لتحصيل المدفوعات الحقيقية. وأثناء تفعيل وضع الاختبار يرى العملاء Test mode — no real money is charged. في خطوة Confirm Order.

حساب الاختبار (ما قبل الإنتاج)

Test Merchant ID (PSPID): PSPID لحساب الاختبار الخاص بك.

Test API Key ID: مفتاح API Key ID الذي أُنشئ في Developer > Payment API لحساب الاختبار.

Test Secret API Key: مفتاح Secret API Key الذي ينتمي إلى مفتاح API Key ID هذا.

Test Webhook Key ID: اختياري. إذا أُدخل، تُقبل فقط webhooks المرسلة بهذا المفتاح.

Test Webhook Secret: سر webhook لحساب الاختبار. يُستخدم للتحقق من توقيع كل webhook.

الحساب الفعلي (الإنتاج)

Live Merchant ID (PSPID): PSPID لحسابك الفعلي.

Live API Key ID: مفتاح API Key ID الذي أُنشئ في Developer > Payment API للحساب الفعلي.

Live Secret API Key: مفتاح Secret API Key الذي ينتمي إلى مفتاح API Key ID هذا.

Live Webhook Key ID: اختياري. إذا أُدخل، تُقبل فقط webhooks المرسلة بهذا المفتاح.

Live Webhook Secret: سر webhook للحساب الفعلي.

لا تُعرض المفاتيح السرية وأسرار webhook المحفوظة مرة أخرى أبدًا. يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. اكتب قيمة جديدة فقط إذا أردت تغييرها. لإزالة قيمة محفوظة، فعّل Clear the saved value أسفل الحقل وانقر على Save.

التحقق من بيانات الاعتماد: تختبر الأزرار Test credentials وLive credentials بيانات الاعتماد المحفوظة لكل حساب باستدعاء اختباري إلى Worldline. احفظ تغييراتك أولًا. تظهر الإجابة أسفل الأزرار، مثل Test credentials: connection successful. أو API credentials are not configured. أو الخطأ الذي تُعيده Worldline.

Webhooks

يُخبر webhook متجرك بالمدفوعات حتى عندما لا يعود العميل إلى المتجر، مثلًا بعد إغلاق المتصفح أو عندما يُؤكَّد الدفع لاحقًا. في Merchant Portal افتح Developer > Webhooks لحساب الاختبار وأضف عنوان URL المعروض في Endpoint URL في هذا القسم. على OpenCart 3 يبدو هكذا: https://your-store/index.php?route=extension/payment/wcp_worldline_gateway/webhook، وعلى OpenCart 4 هكذا: https://your-store/index.php?route=extension/wcp_worldline_gateway/payment/wcp_worldline_gateway.webhook ويُبنى من عنوان واجهة متجرك في تثبيت OpenCart. انسخ عنوان URL تمامًا كما تعرضه الإعدادات: يجب أن يستجيب دون إعادة توجيه، وأن يكون متاحًا من الإنترنت. ثم أدخل معرّف مفتاح webhook وسره في Test Webhook Key ID وTest Webhook Secret. كرر الأمر في الحساب الفعلي باستخدام الحقول الفعلية.

تجيب الإضافة تلقائيًا على طلب التحقق من نقطة النهاية الخاصة بـ Worldline. وهي تعالج أحداث الدفع (تغييرات حالة الدفع) وأحداث الاسترداد (تغييرات حالة الاسترداد). تُقبل الأحداث الأخرى وتُتجاهل. تُرفض webhooks التي لا تحمل توقيعًا صالحًا. يجب أن يكون الحدث موقَّعًا بسر الحساب الذي تم فيه الدفع، لذلك لا يؤكد webhook الاختباري أي دفعة فعلية أبدًا. ويُتجاهل أيضًا webhook إذا جاء من Merchant ID مختلف عن Merchant ID الحساب الذي وقّع سره. وبدون webhook لا يُؤكَّد الطلب إلا عندما يعود العميل إلى المتجر بعد الدفع.

صفحة الدفع والطلبات

Payment page template: اسم اختياري لقالب صفحة الدفع المستضافة (variant) المرفوع في Merchant Portal، مثل SimplifiedCustomPaymentPage. اتركه فارغًا لصفحة Worldline الافتراضية.

Order Status After Payment: الحالة التي يضبطها الدفع المُلتقَط. تُطلب المدفوعات دائمًا كعملية بيع مباشرة (تفويض والتقاط).

ينشئ OpenCart الطلب في خطوة Confirm Order بدون حالة (طلب مفقود). ولا يحصل الطلب على حالة إلا بعد أن تؤكد Worldline الدفع. يسرد كل حقل أدناه حالات طلبات OpenCart الخاصة بك.

Paid Order Status: الحالة بعد دفع مُلتقَط بالخيار Payment accepted (processing). الافتراضي: Processing.

Complete Order Status: الحالة بعد دفع مُلتقَط بالخيار Delivered (completed). الافتراضي: Complete.

Awaiting Capture Status: الدفع مُعتمد أو طُلب الالتقاط؛ يُعلّم webhook الالتقاط الطلب كمدفوع. الافتراضي: Pending.

On Hold (Review) Status: المبلغ أو العملة المدفوعان لا يطابقان الطلب. تشرح ملاحظة السبب. الافتراضي: Pending، لأن OpenCart لا يملك حالة On hold. يمكنك إنشاء حالاتك الخاصة في System > Localisation > Order Statuses واختيارها هنا.

Payment Error Status: رفضت Worldline أو ألغت دفع طلب كان ينتظر الالتقاط. الافتراضي: Failed.

Refunded Status: تم استرداد الدفع بالكامل من صفحة الطلب. الافتراضي: Refunded.

متقدم

Logging: يكتب جميع طلبات الواجهة البرمجية وwebhooks في الملف wlg_debug.log.php داخل مجلد سجلات OpenCart (storage/logs). لا يمكن فتح الملف من الويب، وعند بلوغه 5 ميغابايت يُنقل إلى wlg_debug.old.log.php. تُسجَّل الأخطاء والتحذيرات دائمًا، حتى عند إيقاف هذا الخيار. تُخفى المفاتيح وبيانات البطاقة والبيانات الشخصية. الافتراضي: معطّل.

Log: يعرض حجم السجل وآخر إدخالاته. انقر على Clear log لتفريغه.

Delete Data: عند التفعيل، يؤدي إلغاء تثبيت الإضافة إلى حذف إعدادات البوابة والسجل. تبقى معاملات Worldline واستردادتها دائمًا، لأن الطلبات الحالية تحتاج إليها للاسترداد. الافتراضي: معطّل.

Import / Export

Export: يحفظ Download JSON الإعدادات في ملف JSON. لا تُصدَّر المفاتيح السرية وأسرار webhook.

Import: الصق ملف JSON مُصدَّرًا سابقًا وانقر على Import لاستعادة الإعدادات. تبقى الأسرار المحفوظة كما هي.

الدفع

في خطوة Payment Method يختار العميل وسيلة الدفع (افتراضيًا Worldline). في خطوة Confirm Order يرى العميل وصفك. ينشئ OpenCart الطلب في هذه الخطوة، ولا يزال بدون حالة. عندما ينقر العميل على Confirm Order، تنشئ الإضافة صفحة دفع مستضافة من Worldline بإجمالي الطلب بعملة الطلب، وترسل العميل إلى صفحة الدفع الخاصة بـ Worldline. هناك يدفع العميل ببطاقة أو محفظة إلكترونية أو وسيلة دفع أخرى مُفعّلة في حساب Worldline الخاص بك. تُمرَّر إلى Worldline بيانات الفاتورة والعنوان والبريد الإلكتروني ورقم الهاتف، وتُفتح صفحة الدفع بلغة العميل عندما تدعمها Worldline. تحصل كل محاولة دفع على مرجع خاص بها يتكون من رقم الطلب وجزء عشوائي. على OpenCart 4 يختار العميل وسيلة الدفع بزر Choose في كتلة وسيلة الدفع، في النافذة Payment method options، ثم ينقر على Confirm Order في أسفل صفحة الدفع.

بعد الدفع يعود العميل إلى متجرك. تتحقق الإضافة من العودة بمقارنتها بالمحاولة المحفوظة، وتقرأ حالة الدفع من Worldline على الخادم. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكده Worldline، إما بهذا التحقق من الحالة أو بـ webhook موقَّع. ثم يحصل الطلب على حالته بالطريقة القياسية لـ OpenCart، مع رسائل الطلب المعتادة وتحديث المخزون، ويرى العميل صفحة نجاح الطلب في OpenCart مع Your payment with Worldline has been received. إذا كان الدفع مُعتمدًا ولم يُلتقط بعد، تعرض الصفحة Your payment is authorized. The order is confirmed as soon as Worldline confirms the capture. وإذا فشل دفع مثل هذا الطلب، تعرض الصفحة Your Worldline payment was not completed. Please contact us about this order.

إذا لم يكتمل الدفع، لا يحصل الطلب على أي حالة، وتبقى السلة محفوظة، ويعود العميل إلى صفحة الدفع مع رسالة:

إذا لم يمكن التحقق من الحالة بعد، تعرض صفحة Payment confirmation الرسالة We could not confirm your payment yet. If you completed the payment, please do not pay again — you will receive a confirmation as soon as Worldline confirms it. مع الزرين Check again وBack to checkout. ويضبط webhook حالة الطلب فور وصوله.

في OpenCart 4 تظهر هذه الرسائل فوق صفحة الدفع.

ينشئ OpenCart 3 طلبًا جديدًا في كل مرة تُعرض فيها خطوة Confirm Order، ويحتفظ OpenCart 4 بطلب واحد للدفع ويحدّثه، لذلك يدفع العميل الطلب نفسه في صفحة Worldline جديدة بعد الإلغاء أو الرفض. وقبل دفع جديد تتحقق الإضافة من السلة: إذا كان طلب آخر من السلة نفسها مدفوعًا بالفعل، أو دُفعت المحاولة السابقة في هذه الأثناء، يُوجَّه العميل مباشرة إلى صفحة النجاح دون خصم مزدوج. وإذا كانت صفحة الدفع السابقة لهذا الطلب ما تزال مفتوحة بالمبلغ والوضع نفسيهما، وأُنشئت قبل أقل من 30 دقيقة، يُعاد العميل إليها.

في OpenCart 4، إذا رُفض الدفع أو أُلغي بعد التفويض لطلب في الدفع، فإن Confirm Order التالي يعيد العميل إلى صفحة الدفع برسالة الدفع المرفوض بدلًا من صفحة النجاح. وإذا أغلق المتجر ذلك الطلب (مثلًا ألغاه أو استرده)، تكون الرسالة Your previous order was closed by the shop (cancelled / refunded). Please confirm the order again to pay with a new order. وفي الحالتين يدفع Confirm Order التالي طلبًا جديدًا. وإذا كان طلب الدفع مدفوعًا بالفعل لكن السلة تغيّرت منذ ذلك الحين، بما في ذلك الكمية الجديدة، يُعاد العميل إلى صفحة الدفع وتُدفع السلة الجديدة بطلب جديد.

إذا تعذّرت Worldline في بدء الدفع، يبقى العميل في خطوة Confirm Order مع Payment error: Could not create checkout session. Please try again. فوق الزر. ويُكتب السبب في السجل. وإذا كانت بيانات اعتماد الوضع الحالي مفقودة، يرى العميل This payment method is not available at the moment. Please choose another payment method.

يعمل webhook وعودة العميل أيضًا أثناء وضع الصيانة في المتجر: يسمح OpenCart 3 بمرور طلبات إضافات الدفع، وفي OpenCart 4 تضيف الإضافة إجراء بدء تشغيل لهذه الطلبات.

تقبل الإضافة المدفوعات لمرة واحدة كعملية بيع مباشرة في صفحة Worldline. لا تتضمن ترميز البطاقات أو حفظها، ولا الاشتراكات، ولا نموذج البطاقة المدمج، ولا وضع التفويض فقط مع الالتقاط أو الإلغاء من OpenCart، ولا الرسوم الإضافية، ولا تسجيل الـ webhooks تلقائيًا.

الطلبات والاستردادات

حالات الطلب

بلا حالة (طلب مفقود): أُرسل العميل إلى Worldline ولم يدفع، أو لم تؤكد Worldline الدفع بعد. في Sales > Orders لا تظهر هذه الطلبات إلا عند ضبط فلتر Order Status على Missing Orders.

Paid Order Status أو Complete Order Status (الافتراضي Processing أو Complete): الدفع مُلتقَط. تتبع الحالة Order Status After Payment. تعرض ملاحظة المبلغ ومعرّف دفعة Worldline وكيفية التأكيد (webhook موقَّع أو التحقق من الحالة).

Awaiting Capture Status (الافتراضي Pending): تُبلغ Worldline بأن الدفع مُعتمد أو أن الالتقاط مطلوب، لكنه لم يُلتقط بعد. ينتقل الطلب إلى حالة المدفوع عندما يؤكد webhook الالتقاط. إذا قالت الملاحظة إن الدفع غير مُلتقط، فالتقطه في Worldline Merchant Portal.

On Hold (Review) Status (الافتراضي Pending): الدفع لا يطابق الطلب، مثلًا لأن المبلغ أو العملة مختلفان، أو لأن الدفع يتبع محاولة أخرى. تعرض الملاحظة المبلغ المدفوع وإجمالي الطلب والمرجع. راجع الطلب ونفّذه، أو استرد الدفعة.

Payment Error Status (الافتراضي Failed): رفضت Worldline أو ألغت دفع طلب كان ينتظر الالتقاط.

Refunded Status (الافتراضي Refunded): تم استرداد الدفع بالكامل عبر الإضافة.

إذا وصل دفع لطلب ملغى أو مُسترَد، لا يُعاد فتح الطلب. تطلب منك ملاحظة إلغاء الدفع أو استرداده في Worldline Merchant Portal، أو استعادة الطلب يدويًا. ويرى العميل العائد Your payment was received after this order had been cancelled. Please contact us — we will restore the order or refund the payment. وإذا وصل دفع ثانٍ لطلب مدفوع بالفعل، أو لطلب آخر من سلة مدفوعة بالفعل، فلا يتغير الطلب. وتطلب ملاحظة على الطلب المدفوع منك استرداد الدفع الثاني في Worldline Merchant Portal.

الملاحظات هي مدخلات في History الطلب لا يراها العميل. وتبدأ بكلمة Worldline.

تبويب VibeFox Worldline Gateway

في Sales > Orders افتح طلبًا مدفوعًا عبر Worldline. في أسفل صفحة الطلب، بجانب History وAdditional، يعرض تبويب VibeFox Worldline Gateway كتلة Worldline payment: Payment ID، وMerchant reference، وHosted checkout، وStatus للمحاولة، وAmount charged / refunded، وعلامة Test environment للمدفوعات التجريبية، ونموذج الاسترداد، وسجل الاستردادات، وPayment notes الخاصة بالطلب. يظهر التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة.

الاستردادات

في تبويب VibeFox Worldline Gateway أدخل المبلغ (يُملأ المبلغ الذي لم يُسترد بعد)، واختياريًا Reason (optional)، ثم انقر على Refund via Worldline. أكّد السؤال Refund this amount through Worldline? This cannot be undone. الاستردادات الكاملة والجزئية مدعومة. يجب أن يكون الدفع مُلتقَطًا. تحتاج إلى صلاحية تعديل الإضافة (تُضبط في System > Users > User Groups). تُنفَّذ الاستردادات بالمبلغ والعملة اللذين خصمتهما Worldline، لذلك بعد أي اختلاف في المبلغ أو العملة يمكنك الاسترداد حتى المبلغ الذي دفعه العميل فعلًا، لا إجمالي الطلب. يُرسَل الاسترداد دائمًا إلى بيئة الدفع الأصلي (الاختبار أو الفعلي) ببيانات اعتماد ذلك الحساب، لذا يجب ضبطها. لا يُنفَّذ الاسترداد المعاد محاولته بعد انتهاء المهلة مرتين، ولا يُنفَّذ إلا استرداد واحد للطلب الواحد في كل مرة. إذا رفضت Worldline الاسترداد، يعرض التبويب الخطأ ولا يُسجَّل أي استرداد. ويُضاف الاسترداد المقبول إلى سجل الاستردادات والملاحظات مع معرّف الاسترداد وحالته لدى Worldline. يضبط الاسترداد الكامل الطلب على Refunded Status دون إشعار العميل ودون إعادة المنتجات إلى المخزون، كما في التغيير اليدوي للحالة. ولا يغيّر الاسترداد الجزئي الحالة.

لا تعيد مرتجعات المنتجات في Sales > Returns الأموال عبر Worldline.

تصل تغييرات حالة الاسترداد من Worldline عبر webhook، وتحدّث سجل الاستردادات، وتُضاف إلى الملاحظات. أما الاستردادات التي تتم في Merchant Portal فلا تغيّر حالة الطلب؛ حدّثها يدويًا عند الحاجة.

مفتاح الترخيص

تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox Worldline Gateway هي الكتلة الأولى في صفحة Extensions > Extensions > Payments > VibeFox Worldline Gateway > Edit، فوق الإعدادات. أدخل المفتاح في License key وانقر على Activate. بعد ذلك تعرض الكتلة المفتاح مُخفى، والحالة (مثلًا التاريخ الذي يبقى فيه الترخيص فعالًا ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وتحتها السطر Product: opencart-payment-worldline والرابط Manage licenses and domains in your account الذي يفتح حسابك في vibefox.net. ولا يستطيع تغيير المفتاح إلا مستخدمو الإدارة الذين لديهم صلاحية Modify للإضافة. وتتبع نصوص الكتلة لغة الإدارة (وتشمل الإنجليزية والروسية).

إذا لم يُقبل المفتاح، تُظهر الكتلة السبب، مثلًا Key not found أو This key belongs to another product أو Domain limit reached أو License expired on مع تاريخ. بعد تغيير عنوان المتجر، أو بعد تحرير خانة نطاق في حسابك، انقر على Check now. إذا تعذّر الوصول إلى خادم التراخيص، تواصل الإضافة العمل بآخر حالة معروفة.

يعمل المفتاح الواحد على نطاق واحد: عنوان المتجر من إعدادات OpenCart. لا يؤدي حذف المفتاح من المتجر إلى تحرير خانة النطاق. حرّر الخانة في حسابك على vibefox.net.

بدون مفتاح نشط لا تُعرض Worldline للعملاء عند الدفع. وإذا بدأ الدفع رغم ذلك، يرى العميل This payment method is not available. Please choose another one.. ويرى مسؤول مسجَّل الدخول إلى لوحة الإدارة في المتصفح نفسه وسيلة الدفع في المتجر ما زالت ظاهرة، مع العلامة (unlicensed — visible to admins only)، حتى تتمكن من إعداد الإضافة واختبارها قبل شراء المفتاح. وفي OpenCart 4 لا تتوفر هذه المعاينة: لا يرى المتجر تسجيل دخول الإدارة، لذلك تُخفى وسيلة الدفع عن الجميع بدون مفتاح نشط. وبعد أن تفتح صفحة Edit مرة واحدة، يظهر تذكير في Dashboard الإدارة. أغلقه بالزر × ليختفي لمدة 7 أيام. ولا تتأثر الطلبات الحالية: فالمدفوعات التي بدأت بالفعل ما زالت تُؤكَّد، والاستردادات تعمل.

عند انتهاء صلاحية الترخيص تواصل الإضافة العمل، لكن التحديثات والدعم تحتاج إلى تجديد. تُعاد مراجعة الحالة تلقائيًا عند فتح Dashboard الإدارة أو صفحة Edit: مرة واحدة في اليوم خلال أول 14 يومًا بعد إدخال المفتاح، ثم مرة واحدة في الأسبوع. لا حاجة إلى مهمة cron. يؤدي إلغاء تثبيت الإضافة دائمًا إلى حذف مفتاح الترخيص وحالة الترخيص.

استكشاف الأخطاء وإصلاحها

لا تظهر Worldline عند الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مُفعّل، وأن الوضع الحالي يحتوي على Merchant ID وAPI Key ID وSecret API Key: حقول الاختبار في وضع الاختبار، والحقول الفعلية في الوضع الفعلي. تعرض صفحة الإعدادات تحذيرًا عند غيابها. وتحقق أيضًا من أن عنوان الدفع ضمن Geo Zone المختارة، وأن الطلب يبلغ Total المحدد.

تمت عملية الدفع لكن الطلب بقي بلا حالة: لا يعمل webhook. في Merchant Portal للحساب الذي تستخدمه (اختبار أو فعلي)، تحقق من أن نقطة النهاية موجودة وأن عنوان URL فيها يطابق تمامًا ما يظهر في Endpoint URL دون إعادة توجيه. وتحقق من أن سر webhook لذلك الحساب موجود في الحقل المناسب (Test Webhook Secret أو Live Webhook Secret)، وأن حقل معرّف مفتاح webhook فارغ أو يطابق المفتاح. كما سيحصل الطلب على حالته عندما يعود العميل إلى المتجر بعد الدفع.

Webhook answers Webhook secret not configured: لم يُضبط أي من سرّي webhook. أدخل سر webhook في الإعدادات. تعيد Worldline محاولة إرسال webhook.

Webhook answers Invalid signature: سر webhook يعود إلى حساب أو مفتاح آخر، أو أن معرّف مفتاح webhook لا يطابق المفتاح الذي أرسل webhook. تحقق من أن السرّين التجريبي والفعلي غير متبادلين.

Webhook answers Missing signature أو Empty body أو Invalid JSON: لم يصل الطلب من Worldline بالشكل المتوقع، أو غيّره وسيط أو إعادة توجيه. تحقق من أن عنوان URL يستجيب دون إعادة توجيه.

Webhook answers Ignored: وصل webhook من Merchant ID مختلف عن المحدد في إعدادات ذلك الوضع. تحقق من Test Merchant ID (PSPID) أو Live Merchant ID (PSPID).

Webhook answers Retry later: كان الطلب يُؤكَّد بطلب آخر في اللحظة نفسها، أو تعذّر ضبط حالة الطلب. تعيد Worldline محاولة إرسال webhook. انظر حقل Log لمعرفة السبب.

يعرض عنوان URL الخاص بـ webhook الرسالة Method not allowed في المتصفح: هذا طبيعي. يقبل العنوان الطلبات الصادرة من Worldline فقط.

يعرض Test credentials أو Live credentials خطأ: احفظ الإعدادات أولًا، ثم تحقق من أن Merchant ID وAPI Key ID وSecret API Key من الحساب نفسه، وأن القيم التجريبية في الحقول التجريبية والقيم الفعلية في الحقول الفعلية.

يرى العميل خطأ بعد Confirm Order: انظر حقل Log في صفحة الإضافة. تُسجَّل الأخطاء حتى عندما يكون Logging معطّلًا. لرؤية تفاصيل الطلبات كاملة، فعّل Logging وأعد المحاولة.

لا تؤكد المدفوعات التجريبية دفعة فعلية: الاختبار والفعلي منفصلان. بدّل Test Mode إلى الوضع الذي تريده، واستخدم بيانات اعتماد ذلك الحساب وwebhook الخاص به.

الطلب في حالة المراجعة أو انتظار الالتقاط بعد الدفع: اقرأ الملاحظات في تبويب VibeFox Worldline Gateway (انظر حالات الطلب). إما أن Worldline لم تؤكد الالتقاط بعد (يُكمل webhook الطلب)، أو أن المبلغ أو العملة المدفوعين اختلفا عن الطلب.

لا يوجد نموذج استرداد في التبويب: يذكر التبويب السبب: لا يوجد دفع مُلتقَط لدى Worldline، أو الدفع مُسترد بالكامل، أو مجموعة المستخدمين لديك لا تملك صلاحية تعديل الإضافة، أو بيانات اعتماد بيئة الدفع غير مضبوطة.

يفشل الاسترداد برسالة متعلقة بالبيئة: تم الدفع في بيئة الاختبار أو البيئة الفعلية، وبيانات اعتماد تلك البيئة غير مضبوطة. أدخلها وأعد المحاولة.

للمطورين: قبل إنشاء صفحة الدفع المستضافة، تُطلق الإضافة حدث OpenCart wlg_hosted_checkout_data مع بيانات الطلب والطلب نفسه، على سبيل المثال لتقييد وسائل الدفع المعروضة.

إلغاء التثبيت

انتقل إلى Extensions > Extensions، واختر النوع Payments، ثم انقر على Uninstall (الزر الأحمر −) بجانب VibeFox Worldline Gateway. يُحذف دائمًا مفتاح ترخيص هذه الإضافة وحالة ترخيصها. يزيل OpenCart دائمًا إعدادات الإضافة الخاصة به: Enable/Disable وSort Order وGeo Zone وTotal وحالات الطلبات في قسم Payment page and orders، وتعود هذه إلى قيمها الافتراضية عند إعادة التثبيت. كما يُزال حدث OpenCart الخاص بالإضافة (وفي OpenCart 4 أحداثها وإجراء بدء التشغيل الخاص بها، الذي يسمح بمرور webhook وعودة العميل في وضع الصيانة). إذا كان Delete Data مُفعّلًا، تُحذف إعدادات البوابة الأخرى (العنوان والوصف ووضع الاختبار وبيانات الاعتماد وأسرار webhook وقالب الصفحة والتسجيل) والسجل. وإذا كان معطّلًا، تُحفظ لإعادة التثبيت لاحقًا. تبقى معاملات Worldline واستردادتها دائمًا، لذلك يمكن استرداد الطلبات المدفوعة سابقًا بعد إعادة التثبيت. تحتفظ الطلبات الحالية بملاحظات الدفع الخاصة بها.

في OpenCart 4، لإزالة ملفات الإضافة أيضًا، انتقل بعد إلغاء التثبيت إلى Extensions > Installer وانقر على Uninstall (الزر البرتقالي −) بجوار VibeFox Worldline Gateway في قائمة الإضافات المثبتة، ثم على Delete (زر سلة المهملات الأحمر) لحذف الحزمة المرفوعة.

Worldline علامة تجارية مسجلة لمالكها. هذه الإضافة غير تابعة لـ Worldline ولا معتمدة من قِبلها.