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

المتطلبات

PrestaShop: من 8.0 إلى 9.x.

PHP: 8.0 أو أحدث. ترفض الوحدة التثبيت على إصدارات PHP الأقدم.

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

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

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

التثبيت

1. في لوحة الإدارة، انتقل إلى Modules > Module Manager وانقر على Upload a module. اختر ملف ZIP الخاص بالوحدة.

2. عند انتهاء الرفع، انقر على Configure، أو ابحث لاحقًا عن VibeFox PayPlug Gateway في قائمة الوحدات وانقر على Configure.

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

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

5. فعّل Enable/Disable وانقر على Save. اختبر دفعة مع تفعيل Test Mode، ثم أوقفه لقبول المدفوعات الحقيقية.

عند التثبيت، تنشئ الوحدة حالة الطلب PayPlug payment on hold. تُفعّل PrestaShop وحدة الدفع الجديدة لجميع العملات والدول ومجموعات العملاء. يمكنك تقييدها في Payment > Preferences.

الإعدادات

توجد جميع الإعدادات في صفحة الوحدة: Modules > Module Manager > VibeFox PayPlug Gateway > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كاملة. وفوق الحقول، تحذّرك الصفحة عندما تكون طريقة الدفع مفعّلة لكن المفتاح السري للوضع الحالي فارغ، وعندما لا تكون العملة الافتراضية للمتجر EUR. وفي كلتا الحالتين تُخفى طريقة الدفع عند الدفع.

الدفع

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

Title: اسم طريقة الدفع الذي يراه العميل عند الدفع. وهو أيضًا اسم طريقة الدفع المحفوظ في الطلب. الافتراضي: PayPlug. حقل إلزامي.

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

مفاتيح API

تجد مفاتيحك السرية في بوابة PayPlug ضمن Developers > API keys. يحتوي القسم على رابط إلى البوابة.

Test Mode: يستخدم المفتاح السري للاختبار للدفعات الجديدة. لا تُعالج أي دفعة حقيقية. تستمر الدفعات التي تمت في الوضع الآخر في استخدام مفتاح وضعها للتحقق من الحالة والاستردادات. الافتراضي: on. وطالما هو مفعّل، يرى العملاء الرسالة Test mode: no real payment will be made. أسفل طريقة الدفع.

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

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

لا يُحفظ المفتاح ذو البادئة الخاطئة. تعرض الصفحة مثلًا Test Secret Key must start with "sk_test_". The previous value was kept. لا تُعرض المفاتيح المحفوظة مرة أخرى. يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها.

Clear saved keys: ضع علامة على مفتاح ثم انقر على Save لإزالته. الحقل الفارغ يُبقي القيمة المحفوظة.

Notification URL: العنوان الذي ترسله الوحدة إلى PayPlug مع كل دفعة. مع الروابط الودية يبدو هكذا: https://your-shop/module/wcp_payplug_gateway/webhook. لا حاجة إلى إدخال أي شيء في بوابة PayPlug. يجب أن يكون الرابط متاحًا من الإنترنت؛ وإلا فإن الطلبات تُنشأ عند عودة العميل من PayPlug.

الطلبات

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

متقدم

Logging: يسجّل استدعاءات API والإشعارات في logs/ppg_debug.log.php داخل مجلد الوحدة. لا يمكن فتح الملف من الويب. تُسجَّل الأخطاء والتحذيرات دائمًا. لا تُسجَّل المفاتيح السرية أو بيانات البطاقات أو بيانات العملاء أبدًا. الافتراضي: off.

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

Delete Data on Uninstall: عند التفعيل، تُحذف إعدادات الوحدة وسجلها عند إلغاء تثبيتها. تبقى معرّفات الدفعات في PayPlug المحفوظة مع الطلبات وحالة الطلب PayPlug payment on hold. الافتراضي: off.

الدفع

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

بعد الدفع، يعود العميل إلى متجرك. لا يُعلَّم الطلب مدفوعًا إلا بعد تأكيد PayPlug: تقرأ الوحدة الدفعة من واجهة PayPlug البرمجية عند وصول الإشعار وعند عودة العميل. ثم يُنشأ الطلب ويرى العميل صفحة تأكيد الطلب القياسية مع الرسالة Your payment with PayPlug has been received. إذا كان الطلب في حالة الانتظار، تقول الصفحة We are confirming your payment with PayPlug. The order will be updated automatically — please do not pay again. وإذا كان الطلب في حالة Payment error أو أُلغي دون دفع، تقول الصفحة Your PayPlug payment was not completed. Please contact us about this order. وإذا تعذّر الاستعلام من PayPlug عند عودة العميل، تعرض صفحة Payment confirmation النص نفسه "we are confirming" وزر Check again؛ ويُنشئ الإشعار الطلب فور وصوله.

إذا ألغى العميل في صفحة PayPlug، تُغلق صفحة الدفع لدى PayPlug، فلا يمكن دفعها لاحقًا عن طريق الخطأ. يعود العميل إلى الدفع مع رسالة: You cancelled the PayPlug payment. You can try again or choose another payment method.، أو The PayPlug payment session has expired. Please try again or choose another payment method.، أو The PayPlug payment failed. Please try again or choose another payment method.، أو، إذا بقيت الدفعة مفتوحة، Your PayPlug payment was not completed. You can try again or choose another payment method. وتبقى السلة محفوظة.

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

إذا تعذّر على PayPlug بدء الدفع، يبقى العميل في صفحة الدفع مع رسالة قصيرة، مثل PayPlug could not accept your billing details (postcode). Please check them and try again. أو The payment provider could not be reached. Please try again in a moment. ويُكتب السبب التقني في السجل.

يعمل الإشعار أثناء وضع الصيانة للمتجر، ولا يتأثر بقيود الدول في متجرك.

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

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

حالات الطلب

No order yet: أُرسل العميل إلى PayPlug ولم يدفع، أو لم تؤكد PayPlug الدفعة بعد. لا توجد سوى السلة.

Payment accepted or Delivered: تم تأكيد الدفع. تتبع الحالة Order Status After Payment. تُسجَّل الدفعة بمعرّف PayPlug (pay_...) كمعرّف للمعاملة، وتعرض ملاحظة الدفعة في PayPlug ووضعها.

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

Payment error: فشلت دفعة مُعتمدة لطلب في حالة الانتظار أو أُلغيت.

Refunded: استُرد المبلغ بالكامل عبر الوحدة.

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

كتلة الدفع في PayPlug

تعرض صفحة الطلب كتلة PayPlug payment تتضمن معرّف الدفعة في PayPlug، وحالة الدفع، والمبلغ المدفوع والمسترد، وشارة Test mode للدفعات التجريبية، وسجل الاستردادات، وملاحظات PayPlug notes الخاصة بالطلب.

الاستردادات

في كتلة PayPlug payment أدخل المبلغ (يُملأ المبلغ الذي لم يُسترد بعد)، واكتب السبب إن أردت، ثم انقر على Refund via PayPlug. أكّد السؤال Refund this amount through PayPlug? This cannot be undone. الاسترداد الكامل والجزئي مدعومان. تحتاج إلى صلاحية تعديل الطلبات؛ ولا يلزمك الوصول إلى صفحات الوحدات. تتم الاستردادات حتى المبلغ الذي حصّلته PayPlug فعليًا، لذلك بعد عدم تطابق المبالغ يمكنك استرداد ما دفعه العميل وليس إجمالي الطلب. يذهب الاسترداد إلى الدفعة التي سدّدت الطلب فعليًا، باستخدام المفتاح السري للوضع (الاختبار أو الإنتاج) الذي تمّ فيه، لذلك يجب أن يكون ذلك المفتاح مُعدًّا. إذا لم تقبل PayPlug الاسترداد، تعرض الكتلة الخطأ ولا يُسجَّل أي استرداد. ويُضاف الاسترداد الناجح إلى سجل الاستردادات والملاحظات مع معرّف الاسترداد في PayPlug والسبب. يضع الاسترداد الكامل الطلب في حالة Refunded. ولا يغيّر الاسترداد الجزئي الحالة. وتصبح الاستردادات متاحة فقط بعد أن تبلغ PayPlug بأن الدفعة مدفوعة.

لا تُنشئ الوحدة إشعارات ائتمان. أزرار الاسترداد القياسية في PrestaShop في صفحة الطلب لا ترسل المال عبر PayPlug.

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

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

تعمل الوحدة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox PayPlug Gateway هي أول كتلة في Modules > Module Manager > VibeFox PayPlug Gateway > Configure، فوق الإعدادات. الصق المفتاح في License key وانقر على Activate. بعد ذلك تعرض الكتلة المفتاح مقنّعًا، والحالة (مثلًا تاريخ انتهاء صلاحية الترخيص ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. تحتها سطر Product: presta-payment-payplug ورابط Manage licenses and domains in your account الذي يفتح حسابك في vibefox.net. لا يمكن تغيير المفتاح إلا للموظفين الذين لديهم صلاحية Configure للوحدة. تتبع نصوص الكتلة لغة لوحة الإدارة (تتضمن الإنجليزية والروسية).

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

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

بدون مفتاح نشط، لا يظهر PayPlug للعملاء عند الدفع. إذا بدأ الدفع رغم ذلك، يرى العميل This payment method is not available. Please choose another one. لا تعرف واجهة متجر PrestaShop أنك مسجّل الدخول إلى لوحة الإدارة، لذلك تُخفى طريقة الدفع عنك أيضًا: يمكنك إعداد الوحدة قبل شراء مفتاح، لكن لا يمكنك اختبارها عند الدفع. يظهر تذكير في Modules > Module Manager على علامة التبويب Alerts. الطلبات الحالية لا تتأثر: الدفعات التي بدأت ما زالت تُؤكَّد، وتعمل الاستردادات.

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

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

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

تمت الدفعة لكن لم يُنشأ الطلب: لم يصل الإشعار إلى متجرك ولم يعد العميل. تحقق من أن متجرك متاح من الإنترنت عبر Notification URL المعروض في الإعدادات، مثلًا أن جدار حماية أو حماية بكلمة مرور لا تمنعه. فعّل Logging وراجع الحقل Log للإشعارات المرفوضة.

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

يرد الإشعار بـ Temporarily unavailable.: كانت السلة تُحدَّث بطلب آخر في اللحظة نفسها، مثل عودة العميل، أو تعذّر إنشاء الطلب (مثلًا الوحدة معطّلة). ترسل PayPlug الإشعار مرة أخرى. ويعرض السجل السبب.

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

يعرض رابط الإشعار في المتصفح Method not allowed.: هذا طبيعي. يقبل الرابط الطلبات الواردة من PayPlug فقط.

يرى العميل خطأ عند اختيار PayPlug: فعّل Logging وراجع الحقل Log. المفتاح الخاطئ يعطي This payment method is temporarily unavailable. Please choose another payment method.؛ وتذكر الرسائل الأخرى حقل الفوترة الذي رفضته PayPlug.

الطلب في حالة PayPlug payment on hold بعد الدفع: اقرأ الملاحظات في كتلة PayPlug payment (انظر حالات الطلب)، ثم عالج الطلب أو استرد الدفعة.

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

يفشل الاسترداد برسالة Unexpected response from PayPlug.: ردّت PayPlug دون استرداد صالح. لم يُسجَّل شيء. تحقق من الاسترداد في بوابة PayPlug قبل إعادة المحاولة.

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

انتقل إلى Modules > Module Manager، وافتح القائمة بجانب VibeFox PayPlug Gateway، واختر Uninstall. يُزال مفتاح الترخيص وحالة الترخيص لهذه الوحدة دائمًا. إذا كان Delete Data on Uninstall مفعّلًا، تُحذف إعدادات الوحدة وسجلها. وإذا كان معطّلًا، تُحفظ جميع الإعدادات لإعادة التثبيت لاحقًا. تبقى سجلات الدفعات والاستردادات في PayPlug وحالة الطلب PayPlug payment on hold محفوظة دائمًا، لذلك يمكن استرداد الطلبات المدفوعة سابقًا بعد إعادة التثبيت. وتحتفظ الطلبات الحالية بملاحظات الدفع ومعرّفات المعاملات.

PayPlug علامة تجارية مسجّلة لمالكها. هذه الوحدة غير تابعة لـ PayPlug ولا معتمدة من قبلها.