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

المتطلبات

WordPress: 6.0 أو أحدث.

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

PHP: 8.0 أو أحدث.

العملة والمبالغ: اليورو (EUR)، من 0.99 إلى 20,000.00 لكل دفعة، وهي القيم الافتراضية لـ PayPlug. وبعملة أخرى أو خارج هذه الحدود تُخفى وسيلة الدفع.

حساب PayPlug: تحتاج إلى المفاتيح السرية لحساب PayPlug الخاص بك: مفتاح الاختبار (sk_test_...) و/أو مفتاح الإنتاج (sk_live_...). لا تحتاج إلى مفاتيح أخرى، ولا إلى إعداد أي إشعار في PayPlug. ويجب أن يكون موقعك متاحًا من الإنترنت لاستقبال الإشعارات؛ وإلا فستُحدَّث الطلبات عند عودة العميل من PayPlug.

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

التثبيت

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

2. انقر على Activate.

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

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

5. الصق مفاتيحك السرية من بوابة PayPlug (انظر الإعدادات).

6. فعّل Enable/Disable واحفظ. اختبر دفعة مع تفعيل Test Mode، ثم ألغِ تفعيله لقبول المدفوعات الحقيقية.

الإعدادات

توجد جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > PayPlug. وفوق الحقول تحذرك الصفحة عند تفعيل وسيلة الدفع مع كون المفتاح السري للوضع الحالي فارغًا، وعندما لا تكون عملة المتجر EUR. وفي الحالتين تُخفى وسيلة الدفع في صفحة الدفع. وفي قائمة وسائل الدفع تعرض PayPlug شارة وضع الاختبار في وضع الاختبار، وتُعلَّم على أنها تحتاج إلى إعداد إلى أن يكون للوضع الحالي مفتاح سري.

الدفع

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

Title: اسم وسيلة الدفع الذي يراه العملاء في صفحة الدفع. الافتراضي: PayPlug.

Description: النص الذي يظهر أسفل وسيلة الدفع في صفحة الدفع. الافتراضي: Pay securely by card via PayPlug.

مفاتيح API

تجد مفاتيحك السرية في بوابة PayPlug ضمن Developers > API keys. يعرض القسم أيضًا عنوان الإشعار الذي ترسله الإضافة مع كل دفعة، وهو بهذا الشكل: https://your-site/wc-api/ppg_payplug_webhook/. لا حاجة إلى إعداد أي إشعار في PayPlug.

Test Mode: Enable test mode يستخدم المفتاح السري للاختبار للمدفوعات الجديدة. لا تُعالَج أي مدفوعة حقيقية. وتستمر المدفوعات التي تمت في الوضع الآخر في استخدام مفتاح وضعها للتحقق من الحالة والاستردادات. الافتراضي: on.

Test Secret Key: مفتاحك السري للاختبار في PayPlug. يبدأ بـ sk_test_.

Live Secret Key: مفتاحك السري للإنتاج في PayPlug. يبدأ بـ sk_live_.

لا يُحفظ المفتاح ذو البادئة الخاطئة. تعرض الصفحة مثلًا الرسالة يجب أن يبدأ Test Secret Key بالعبارة "sk_test_". تم الإبقاء على القيمة السابقة.

الطلبات

Order Status After Payment: حالة الطلب التي تُعيَّن بعد دفعة ناجحة. تُعيَّن الحالة فورًا دون تغيير ثانٍ للحالة.

متقدم

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

Delete Data on Uninstall: Remove all plugin data when uninstalling. عند تحديده تُحذف إعدادات الإضافة وسجلاتها عند حذف الإضافة. وتُحتفظ معرّفات دفعات PayPlug المخزنة في الطلبات. الافتراضي: off.

الدفع

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

بعد الدفع يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد تأكيد PayPlug: تقرأ الإضافة الدفعة من واجهة PayPlug البرمجية عند وصول الإشعار وعند عودة العميل. وتقود الدفعة الناجحة العميل إلى صفحة استلام الطلب.

إذا ألغى العميل في صفحة PayPlug، تُغلَق صفحة الدفع في PayPlug حتى لا يمكن دفعها لاحقًا بالخطأ. يعود العميل إلى صفحة Pay for order برسالة، مثل لقد ألغيت دفعة PayPlug. يمكنك المحاولة مرة أخرى أو اختيار وسيلة دفع أخرى.، أو انتهت جلسة دفع PayPlug. يُرجى المحاولة مرة أخرى أو اختيار وسيلة دفع أخرى.، أو فشلت دفعة PayPlug. يُرجى المحاولة مرة أخرى أو اختيار وسيلة دفع أخرى.

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

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

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

تُحصَّل المدفوعات فورًا. لا تتضمن الإضافة تقسيط Oney أو Bancontact أو Apple Pay أو American Express، ولا بطاقات محفوظة بنقرة واحدة، ولا نموذج دفع مضمّن، ولا اشتراكات، ولا تحصيلًا مؤجلًا.

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

Order statuses

Pending payment: أُرسل العميل إلى PayPlug ولم يدفع بعد، أو لم تؤكد PayPlug الدفعة بعد.

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

On hold: المبلغ أو العملة المدفوعان يختلفان عن الطلب (ملاحظة amount/currency mismatch)؛ أو أُجريت دفعة اختبارية والمتجر في وضع الإنتاج، فلم تُستلم أي أموال؛ أو وصلت الدفعة لطلب كان قد أُلغي؛ أو أن الدفعة مُفوَّضة لكنها غير محصّلة (حصّلها في بوابة PayPlug؛ يُعلَّم الطلب مدفوعًا عندما تبلغ PayPlug بأن الدفعة مدفوعة). وتشرح ملاحظة الطلب ما يجب التحقق منه.

Failed: فشلت آخر محاولة دفع لطلب معلّق أو أُلغيت. ولا يغيّر فشل محاولة أقدم الطلب. ويمكن للعميل الدفع مرة أخرى.

إذا دُفعت أيضًا محاولة ثانية لطلب مدفوع بالفعل، فلا يتغير الطلب. وتطلب ملاحظة منك استرداد الدفعة المكررة في بوابة PayPlug.

الاستردادات

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

تصل الاستردادات التي تتم في بوابة PayPlug عبر الإشعارات، وتُضاف إلى ملاحظات الطلب. ولا تُنشأ تلقائيًا في WooCommerce. سجّلها يدويًا عند الحاجة.

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

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

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

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

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

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

لا يظهر PayPlug في صفحة الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن الوضع الحالي لديه مفتاح سري (Test Secret Key في وضع الاختبار، وLive Secret Key في وضع الإنتاج)، وأن عملة المتجر EUR، وأن إجمالي الطلب بين 0.99 و20,000.00 EUR. ويمكن للحسابات ذات الحدود الأخرى تغييرها بالفلتر ppg_amount_limits (القيم بالسنت).

تمت الدفعة لكن الطلب بقي في حالة «بانتظار الدفع»: لم يصل الإشعار إلى متجرك ولم يعد العميل. تحقق من أن موقعك متاح من الإنترنت عبر عنوان الإشعار المعروض في الإعدادات، مثلًا ألا يمنعه وضع الصيانة أو جدار الحماية أو الحماية بكلمة مرور. وراجع WooCommerce > Status > Logs، بالمصدر wcp_payplug_gateway، لمعرفة الإشعارات المرفوضة.

يرد الإشعار بـ Verification failed: تعذّرت قراءة الدفعة من واجهة PayPlug البرمجية، مثلًا لأن PayPlug لم تستجب. لا يتغير الطلب، وسترسل PayPlug الإشعار مرة أخرى.

يرد الإشعار بـ Busy, retry: كان الطلب يُحدَّث بطلب آخر في الوقت نفسه، مثل عودة العميل. ستعيد PayPlug إرسال الإشعار.

يرد الإشعار بـ Unknown payment أو Payment does not belong to the order: لم تُنشئ هذه الدفعة هذا المتجر أو لم تكن لهذا الطلب، مثل دفعة من متجر آخر على الحساب نفسه في PayPlug. وتُتجاهل.

يرى العميل Payment could not be initiated: محاولة الدفع السابقة للطلب تُؤكَّد في هذه اللحظة، أو رفضت PayPlug الطلب. انتظر لحظة وحاول مرة أخرى؛ وتعرض ملاحظات الطلب خطأ PayPlug.

الطلب في حالة «قيد الانتظار» بعد الدفع: اقرأ ملاحظة الطلب. لم يتطابق المبلغ أو العملة المدفوعان مع الطلب، أو أُجريت دفعة اختبارية والمتجر في وضع الإنتاج، أو وصلت الدفعة بعد إلغاء الطلب. عالج الطلب أو استرد الدفعة.

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

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

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

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

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