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

المتطلبات

WordPress: 6.0 أو أحدث.

WooCommerce: 7.0 أو أحدث، مثبّت ومفعّل. لا تُفعَّل الإضافة بدونه.

PHP: 8.0 أو أحدث.

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

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

التثبيت

1. في WordPress، انتقل إلى Plugins > Add New > Upload Plugin، واختر ملف ZIP للإضافة، ثم انقر على Install Now. يمكنك أيضًا رفع مجلد wcp_worldline_gateway إلى /wp-content/plugins/ عبر FTP.

2. انقر على Activate.

3. افتح الإعدادات: WooCommerce > Settings > Payments > Worldline (Ingenico) > Manage، أو انقر على Settings أسفل اسم الإضافة في صفحة الإضافات.

4. أدخل مفتاح ترخيص VibeFox في كتلة الترخيص أعلى الصفحة، ثم انقر على Activate.

5. أدخل بيانات اعتماد الاختبار، واحفظ الإعدادات، ثم انقر على Test credentials.

6. أضف عنوان URL الخاص بـ webhook في Merchant Portal لحساب الاختبار، وأدخل مفتاح webhook والسر (راجع «Configuration»).

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

Configuration

جميع الإعدادات موجودة في صفحة واحدة: WooCommerce > Settings > Payments > Worldline (Ingenico). في قائمة طرق الدفع، يظهر Worldline على أنه يحتاج إلى إعداد حتى يحتوي الوضع الحالي على Merchant ID وAPI Key ID وSecret API Key. وفي صفحة الإعدادات، تظهر حقول بيانات الاعتماد الخاصة بالوضع غير المستخدم باهتة.

General

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

Title: اسم طريقة الدفع الذي يراه العملاء عند الدفع. الافتراضي: Worldline.

Description: النص الذي يظهر أسفل طريقة الدفع عند الدفع. الافتراضي: Pay securely via 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: Enable test mode (pre-production environment, no real money) يبدّل نقطة نهاية API وبيانات الاعتماد معًا. يستخدم وضع الاختبار بيئة ما قبل الإنتاج وبيانات الاعتماد الخاصة بالاختبار، ويستخدم الوضع الفعلي بيئة الإنتاج وبيانات الاعتماد الفعلية. الافتراضي: مفعّل. ألغِ التحديد لاستقبال مدفوعات حقيقية. وطالما وضع الاختبار مفعّل، يرى العملاء عبارة Test mode — no real money is charged. أسفل طريقة الدفع.

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

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 للحساب الفعلي.

التحقق من بيانات الاعتماد

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

Webhooks

يُبلغ webhook متجرك بالمدفوعات حتى عندما لا يعود العميل إلى المتجر، مثل إغلاق المتصفح أو عندما يُؤكَّد الدفع لاحقًا. في Merchant Portal لحساب الاختبار، افتح Developer > Webhooks وأضف عنوان نقطة النهاية المعروض في هذا القسم من الإعدادات. يبدو هكذا: https://your-site/wc-api/wlg_worldline_webhook/. انسخ العنوان تمامًا كما تعرضه الإعدادات: يجب أن يستجيب دون عمليات إعادة توجيه، لذا تحقق من بادئات اللغة وإعادات التوجيه الإجبارية إلى www أو https. ثم أدخل معرّف مفتاح webhook والسر في Test Webhook Key ID وTest Webhook Secret. افعل الأمر نفسه في الحساب الفعلي باستخدام الحقول الفعلية.

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

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

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

Order Status After Payment: حالة الطلب بعد أن تؤكد Worldline الدفعة المُحصَّلة. تُضبط الحالة فورًا دون الحاجة إلى تغيير ثانٍ. تُطلب المدفوعات دائمًا كعملية بيع مباشرة (تفويض وتحصيل).

Logging: Enable debug logging يكتب جميع طلبات API وwebhooks في WooCommerce > Status > Logs، بالمصدر wcp_worldline_gateway. تُسجَّل الأخطاء والتحذيرات دائمًا، حتى عند إيقاف هذا الخيار. تُخفى المفاتيح وبيانات البطاقة والبيانات الشخصية. الافتراضي: معطّل.

Delete Data: Delete the plugin settings and logs when the plugin is deleted. إلغاء تفعيل الإضافة لا يحذف أي شيء أبدًا. تبقى بيانات الدفع المخزنة في الطلبات محفوظة، لأنها ضرورية للاستردادات. الافتراضي: معطّل.

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

الدفع

يختار العميل طريقة الدفع (افتراضيًا Worldline) ويقدّم الطلب. تنشئ الإضافة صفحة دفع مستضافة من Worldline بإجمالي الطلب وبعملة الطلب، وتنقل العميل إلى صفحة الدفع الخاصة بـ Worldline. هناك يدفع العميل بالبطاقة أو بمحفظة إلكترونية أو بوسيلة دفع أخرى مفعّلة في حسابك لدى Worldline. تُرسل بيانات الفوترة من الاسم والعنوان والبريد الإلكتروني والهاتف إلى Worldline، وتُفتح صفحة الدفع بلغة متجرك عندما تدعمها Worldline. يحصل كل محاولة دفع على مرجع خاص بها، يتكون من معرّف الطلب وجزء عشوائي.

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

إذا لم يكتمل الدفع، يُنقل العميل إلى صفحة Pay for order مع رسالة:

يمكن للعميل دفع طلب غير مدفوع مرة أخرى من صفحة Pay for order. فإذا كانت المحاولة السابقة قد دُفعت في الأثناء، ينتقل العميل مباشرة إلى صفحة استلام الطلب ولا يُخصم منه المبلغ مرتين. وإذا كانت صفحة الدفع السابقة ما زالت مفتوحة بنفس المبلغ والوضع، وأُنشئت منذ أقل من 30 دقيقة، يُعاد العميل إليها.

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

تعمل طريقة الدفع في الدفع الكلاسيكي وفي كتلة Checkout وفي صفحة Pay for order. وهي متوافقة مع WooCommerce High-Performance Order Storage (HPOS).

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

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

Order statuses

Pending payment: أُرسل العميل إلى Worldline ولم يدفع بعد، أو لم تؤكد Worldline الدفع بعد. تعرض ملاحظة معرّف صفحة الدفع المستضافة والمرجع والوضع (اختبار أو فعلي).

Processing or Completed: تم تحصيل الدفعة. تتبع الحالة Order Status After Payment. تعرض ملاحظة الطلب المبلغ ومعرّف دفعة Worldline وطريقة التأكيد (webhook موقّع أو فحص الحالة). معرّف المعاملة للطلب هو معرّف دفعة Worldline.

On hold, waiting for capture: تُبلغ Worldline بأن الدفعة مفوّضة أو أن التحصيل مطلوب، لكنه لم يتم بعد. تشرح ملاحظة الطلب ذلك. يُعلَّم الطلب كمدفوع تلقائيًا عندما يؤكد webhook التحصيل. وإذا ذكرت الملاحظة أن الدفعة غير مُحصَّلة، فحصّلها في Worldline Merchant Portal.

On hold, held for manual review: لا تتطابق الدفعة مع الطلب، مثل اختلاف المبلغ أو العملة (تم تعديل الطلب بعد بدء الدفع)، أو لأن الدفعة تنتمي إلى محاولة أخرى. تعرض الملاحظة المبلغ المدفوع وإجمالي الطلب والمرجع. تحقق من الطلب ثم أتمّه أو استرد الدفعة.

Failed: رفضت Worldline دفعة آخر محاولة أو ألغتها، أو لم يكن العميل مؤهلًا لطريقة الدفع المختارة.

Cancelled: أُلغي الطلب من قِبلك أو بسبب انتهاء مهلة حجز المخزون في WooCommerce. وإذا وصلت دفعة لطلب ملغى أو مسترد، لا يُعاد فتح الطلب. تطلب منك ملاحظة استرداد الدفعة أو إلغاءها في 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.

الاستردادات

افتح الطلب، وانقر على Refund، وأدخل المبلغ، ثم انقر على Refund via Worldline (Ingenico). الاستردادات الكاملة والجزئية مدعومة. يجب أن تكون الدفعة قد حُصِّلت. يُرسل الاسترداد دائمًا إلى بيئة الدفعة الأصلية (اختبار أو فعلية) باستخدام بيانات اعتماد ذلك الحساب، لذا يجب أن تكون مُعدّة. لا يُنفَّذ الاسترداد المعاد محاولته بعد انتهاء المهلة مرتين. وإذا رفضت Worldline الاسترداد، يعرض WooCommerce الخطأ ولا يُسجَّل أي استرداد. يُضاف الاسترداد المقبول إلى ملاحظات الطلب مع معرّف الاسترداد لدى Worldline وحالته.

تصل تغييرات حالة الاسترداد من Worldline عبر webhook، وتُضاف إلى ملاحظات الطلب. الاستردادات التي تتم في Merchant Portal لا تُسجَّل تلقائيًا كاستردادات في WooCommerce. وإذا لزم الأمر، فأنشئ استردادًا يدويًا في WooCommerce دون استخدام Refund via Worldline (Ingenico).

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

تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. تقع كتلة الترخيص أعلى WooCommerce > Settings > Payments > Worldline (Ingenico). الصق المفتاح في License key وانقر على Activate. تعرض الكتلة الحالة، مثل التاريخ الذي يكون فيه الترخيص فعالًا حتى، ونطاقك. استخدم Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالته من هذا الموقع. يفتح الرابط Manage licenses and domains in your account حسابك على vibefox.net.

يعمل المفتاح الواحد على نطاق واحد فقط. وإزالة المفتاح من موقع لا تحرر خانة النطاق الخاصة به. حرّرها من حسابك على vibefox.net.

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

عند انتهاء صلاحية الترخيص، تستمر الإضافة في العمل، لكن التحديثات والدعم تتطلب التجديد. تُعاد مراجعة الحالة تلقائيًا في الخلفية.

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

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

تم الدفع، لكن الطلب ما زال في Pending payment: لا يعمل webhook. في Merchant Portal للحساب الذي تستخدمه (اختبار أو فعلي)، تحقق من وجود نقطة النهاية وأن عنوانها مطابق تمامًا للعنوان المعروض في الإعدادات دون إعادة توجيه. تحقق من أن سر webhook لذلك الحساب موجود في الحقل المناسب (Test Webhook Secret أو Live Webhook Secret) وأن Webhook Key ID فارغ أو يطابق المفتاح. يُؤكَّد الطلب أيضًا عندما يعود العميل إلى المتجر بعد الدفع.

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

يرد webhook بالرسالة Invalid signature: سر webhook يخص حسابًا آخر أو مفتاحًا آخر، أو أن Webhook Key ID لا يطابق المفتاح الذي أرسل webhook.

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

يرد webhook بالرسالة Ignored: جاء webhook من Merchant ID غير المعرّف في إعدادات ذلك الوضع. تحقق من Test Merchant ID (PSPID) أو Live Merchant ID (PSPID).

يرد webhook بالرسالة Retry later: كان الطلب يُحدَّث بطلب آخر في اللحظة نفسها. تعيد Worldline محاولة إرسال webhook.

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

يرى العميل خطأً عند إتمام الطلب: افتح ملاحظات الطلب أو WooCommerce > Status > Logs، بالمصدر wcp_worldline_gateway. تُسجَّل الأخطاء حتى عند إيقاف تسجيل التصحيح. ولرؤية التفاصيل الكاملة للطلبات، فعّل Logging وأعد المحاولة.

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

الطلب في حالة On hold بعد الدفع: اقرأ ملاحظة الطلب. إما أن Worldline لم تؤكد التحصيل بعد (وسيُكمل webhook الطلب)، أو أن المبلغ أو العملة المدفوعة لم تتطابق مع الطلب.

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

للمطورين: يعدّل الفلتر wlg_hosted_checkout_data طلب صفحة الدفع المستضافة، مثل تقييد طرق الدفع المعروضة، ويغيّر wlg_gateway_icon أيقونة طريقة الدفع.

تعرض كتلة الترخيص خطأً: اتبع الرسالة في الكتلة. فعلى سبيل المثال، إذا كان المفتاح مستخدمًا بالفعل في نطاق آخر، فحرّر خانة في حسابك على vibefox.net ثم انقر على Check now. وإذا تغير عنوان الموقع، فانقر على Check now لتفعيل المفتاح للنطاق الجديد. وإذا تعذر الوصول إلى خادم الترخيص، تستمر الإضافة بالعمل بآخر حالة معروفة.

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

إلغاء تفعيل الإضافة يحفظ جميع البيانات. لإزالتها، ألغِ تفعيلها واحذفها من صفحة Plugins. يُحذف مفتاح الترخيص وحالة الترخيص لهذه الإضافة دائمًا. أما إعدادات البوابة والسجلات فلا تُحذف إلا إذا كان Delete Data مفعّلًا. وإلا تبقى محفوظة لإعادة التثبيت لاحقًا. تبقى بيانات دفع Worldline المخزنة في الطلبات محفوظة دائمًا، لأنها ضرورية للاستردادات. وتحتفظ الطلبات الحالية بملاحظات الدفع ومعرّفات المعاملات.

Worldline علامة تجارية مملوكة لصاحبها. هذه الإضافة غير تابعة لـ Worldline ولا تحظى بتأييدها.