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

المتطلبات

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

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

عملة المتجر: HUF أو EUR أو USD. لا تقبل SimplePay العملات الأخرى، ولا تُعرض طريقة الدفع لسلال التسوق بتلك العملات.

حسابات تاجر SimplePay: تمنح SimplePay حساب تاجر منفصلًا لكل عملة، وحسابات منفصلة للإنتاج والاختبار (sandbox). لكل حساب تحتاج إلى MERCHANT وSECRET KEY الخاصين به من لوحة تاجر SimplePay (admin.simplepay.hu للإنتاج، وsandbox.simplepay.hu للاختبار)، من account > Technical data. إذا كنت تبيع بعملة HUF فقط، فحساب HUF يكفي. لا تحتاج إلى أي مفاتيح أخرى.

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

التثبيت

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

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

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

4. أدخل MERCHANT وSECRET KEY لحسابات SimplePay لكل عملة تبيع بها: حسابات sandbox للاختبار، وحسابات الإنتاج للمدفوعات الحقيقية (انظر الإعدادات).

5. انسخ IPN URL المعروض في صفحة Configure إلى كل حساب تاجر (الإنتاج والاختبار) في لوحة تاجر SimplePay.

6. فعّل Enable/Disable وانقر على Save. اختبر دفعة واحدة مع تفعيل Sandbox mode، ثم أوقف Sandbox mode لقبول المدفوعات الحقيقية.

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

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox SimplePay Gateway > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كاملة. فوق الحقول، تحذّرك الصفحة إذا كانت العملة الافتراضية للمتجر غير مدعومة من SimplePay، أو إذا لم يكن لها حساب تاجر في الوضع الحالي. وفي الحالتين لا تُعرض طريقة الدفع لسلال التسوق بتلك العملة. وأثناء تفعيل وضع الاختبار، تعرض الصفحة الرسالة Sandbox mode is on: payments go to the SimplePay sandbox, no real money is charged.

SimplePay (OTP)

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

Title: اسم طريقة الدفع الذي يراه العملاء عند الدفع. وهو أيضًا اسم طريقة الدفع المحفوظ في الطلب. الافتراضي: SimplePay (Card Payment). حقل مطلوب.

Description: النص الذي يظهر أسفل طريقة الدفع عند الدفع. الافتراضي: Pay securely with your credit or debit card via SimplePay. يمكن للتجار المجريين وضع إعلان نقل البيانات الخاص بـ SimplePay هنا (مع رابطه).

Sandbox mode: يستخدم بيئة الاختبار (sandbox) الخاصة بـ SimplePay للمدفوعات التجريبية مع حسابات sandbox. ويغيّر هذا الخيار عنوان API وحسابات التاجر معًا. لا يُخصم أي مال حقيقي. الافتراضي: مُفعّل. أوقفه لقبول المدفوعات الحقيقية بحسابات الإنتاج. وطالما هو مفعّل، يرى العملاء الرسالة Sandbox mode: no real payment is taken. أسفل طريقة الدفع. تُسترد الطلبات التي بدأت في بيئة الاختبار دائمًا في بيئة الاختبار.

حسابات تاجر الإنتاج

الحسابات المستخدمة عندما يكون Sandbox mode مُعطّلًا. املأ حسابات العملات التي يبيع بها متجرك. توجد قيم MERCHANT وSECRET KEY في لوحة تاجر SimplePay (admin.simplepay.hu)، ضمن account > Technical data. لا يُستخدم الحساب إلا عندما يكون الحقلان مملوءين.

HUF account — Merchant ID: قيمة MERCHANT لحساب HUF الخاص بالإنتاج.

HUF account — Secret key: قيمة SECRET KEY لحساب HUF الخاص بالإنتاج.

EUR account — Merchant ID وEUR account — Secret key: الشيء نفسه لحساب EUR الخاص بالإنتاج.

USD account — Merchant ID وUSD account — Secret key: الشيء نفسه لحساب USD الخاص بالإنتاج.

حسابات تاجر الاختبار (sandbox)

الحسابات المستخدمة عندما يكون Sandbox mode مُفعّلًا. الحقول هي نفسها الموجودة في حسابات الإنتاج: HUF account — Merchant ID، وHUF account — Secret key، والأزواج نفسها لعملتي EUR وUSD. خذ القيم من لوحة تاجر sandbox الخاصة بـ SimplePay (sandbox.simplepay.hu)، ضمن account > Technical data.

لا تُعرض المفاتيح السرية المحفوظة مرة أخرى. يبقى الحقل فارغًا ويعرض الرسالة Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها.

IPN URL

إشعار IPN هو الرسالة التي ترسلها SimplePay إلى متجرك عند تغيّر حالة الدفع. وهو الطريقة المعتادة لإنشاء الطلب. يعرض هذا القسم عنوان IPN URL لمتجرك. ومع الروابط الودية، يبدو هكذا: https://your-shop/module/wcp_simplepay_gateway/ipn، وقد يتضمن رمز لغة مثل /en/. اضبط هذا العنوان لكل حساب تاجر، الإنتاج والاختبار، في لوحة تاجر SimplePay. انسخ العنوان تمامًا كما تعرضه الإعدادات، لأن إشعار IPN الذي يُعاد توجيهه يُفقد.

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

تُسجَّل حالات الرفض والإلغاء وانتهاء المهلة فقط لآخر محاولة دفع لسلة تسوق لم يُنشأ لها طلب بعد. أما الحالات الأخرى فتُسجَّل في السجل ولا تغيّر شيئًا. وبدون إشعار IPN، لا يُنشأ الطلب إلا عندما يعود العميل إلى المتجر بعد دفع ناجح.

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

الطلبات

Order Status After Payment: حالة الطلب التي تُعيَّن بعد الدفع الناجح.

أي دفعة بمبلغ أو عملة مختلفين عن الطلب تنتقل دائمًا إلى SimplePay payment on hold.

متقدم

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

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

Delete Data on Uninstall: عند التفعيل، يؤدي إلغاء تثبيت الوحدة إلى حذف إعدادات البوابة والسجل. أما بيانات الطلبات (معاملات SimplePay واستردادها) فتُحفظ دائمًا. الافتراضي: مُعطّل.

الدفع

في خطوة الدفع، يختار العميل طريقة الدفع (افتراضيًا SimplePay (Card Payment)) ويرى الملاحظة You will be redirected to the SimplePay payment page to pay by card. بعد التأكيد، تبدأ الوحدة عملية دفع بالبطاقة عبر SimplePay بمبلغ إجمالي سلة التسوق بعملة السلة، مع حساب التاجر لتلك العملة في الوضع الحالي، وتُرسل العميل إلى صفحة الدفع الخاصة بـ SimplePay. يُمرَّر بريد العميل، وعنوان الفوترة عندما يكون مكتملًا، إلى SimplePay. تستخدم صفحة الدفع لغة المتجر عندما تدعمها SimplePay، وإلا فالإنجليزية. ويمكن إكمال عملية دفع بدأت خلال 30 دقيقة. لا يوجد طلب في هذه المرحلة.

بعد الدفع الناجح، يعود العميل إلى متجرك. ولا تكفي العودة وحدها لاعتماد الطلب: تطلب الوحدة من SimplePay حالة المعاملة بطلب موقَّع، فيُنشأ الطلب حتى لو تأخر إشعار IPN. ولا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكده SimplePay. ثم يرى العميل صفحة تأكيد الطلب القياسية مع Successful transaction. SimplePay transaction ID: والمعرّف. وإذا لم تؤكد SimplePay الدفع بعد، تعرض صفحة Payment confirmation الرسالة Your payment is being confirmed by SimplePay. SimplePay transaction ID: مع المعرّف وزر Check again؛ وينشئ إشعار IPN الطلب فور وصوله.

إذا فشل الدفع، أو أُلغي، أو انتهت مهلته، يعود العميل إلى الدفع مع رسالة SimplePay ومعرّف المعاملة، مثل Cancelled payment. You cancelled the payment أو Timeout. The time allowed to complete the payment has expired. عند فشل الدفع، يُطلب من العميل التحقق من البيانات التي أدخلها والتواصل مع البنك المُصدِر للبطاقة. تُحفظ سلة التسوق ويمكن للعميل المحاولة مرة أخرى. ويحصل كل محاولة جديدة على مرجع SimplePay خاص بها: PS ورقم السلة ورقم المحاولة، مثل PS123-1 وPS123-2.

إذا تعذّر على SimplePay بدء الدفع، يرى العميل الرسالة The SimplePay payment could not be started. Please try again or choose another payment method. إذا لم يكن لعملة السلة حساب تاجر، فالرسالة هي SimplePay is not available for the currency of this order. Please choose another payment method. ويُكتب السبب الفني في السجل.

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

تقبل الوحدة مدفوعات البطاقات لمرة واحدة فقط، تُحصَّل في صفحة SimplePay. لا تتضمن البطاقات المحفوظة أو الدفع بنقرة واحدة، ولا الاشتراكات أو المدفوعات المتكررة، ولا التفويض والتحصيل المنفصلان.

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

حالات الطلب

لا يوجد طلب بعد: أُرسل العميل إلى SimplePay ولم يدفع، أو فشل الدفع، أو أُلغي، أو انتهت مهلته، أو لم تؤكد SimplePay الدفع بعد. لا توجد سوى سلة التسوق.

Payment accepted or Delivered: تم تأكيد الدفع. تتبع الحالة Order Status After Payment. يُسجَّل الدفع بمعرّف معاملة SimplePay، وتعرض ملاحظة معرّف المعاملة وما إذا كان إشعار IPN أو طلب الحالة هو من أكّده.

SimplePay payment on hold: تغيّر إجمالي سلة التسوق أو عملتها بعد بدء الدفع، لذلك يختلف المبلغ المدفوع عن الطلب. لا يُسجَّل أي دفع. تعرض الملاحظة المبلغين. تحقق من الطلب ونفّذه، أو استرد الدفع من لوحة تاجر SimplePay. وإذا دُفعت لاحقًا محاولة أخرى لنفس السلة بالمبلغ الصحيح، ينتقل الطلب إلى حالة مدفوع.

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

لا يُعاد فتح طلب مدفوع أو مسترد أو مُسلَّم بسبب إشعار IPN متأخر. وإذا نجحت دفعة ثانية لطلب مدفوع بالفعل، فلا يتغيّر الطلب. وتطلب منك ملاحظة التحقق من ذلك في لوحة SimplePay واسترداده إذا كان مكررًا.

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

تعرض صفحة الطلب كتلة SimplePay payment تتضمن معرّف المعاملة، ومرجع الطلب (orderRef)، وحساب التاجر والوضع، وحالة SimplePay، والمبالغ المدفوعة والمستردة، وشارة Sandbox للمدفوعات التجريبية، ومحاولات دفع سلة التسوق (عندما تكون أكثر من واحدة)، وسجل الاستردادات، وملاحظات SimplePay notes الخاصة بالطلب.

الاستردادات

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

لا تُنشئ الوحدة إشعارات دائن (credit slips). ولا ترسل أزرار الاسترداد القياسية في PrestaShop في صفحة الطلب أي أموال عبر SimplePay. ولا تُزامَن الاستردادات التي تُجرى من لوحة تاجر SimplePay مع PrestaShop. سجّلها يدويًا.

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

تعمل الوحدة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox SimplePay Gateway هي أول كتلة في Modules > Module Manager > VibeFox SimplePay Gateway > Configure، فوق الإعدادات. الصق المفتاح في License key وانقر Activate. بعد ذلك تعرض الكتلة المفتاح مخفيًا، والحالة (مثل تاريخ انتهاء الترخيص ونطاقك)، وأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وتحتها سطر Product: presta-payment-simplepay ورابط 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.

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

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

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

لا تظهر SimplePay عند الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مُفعّل، وأن عملة السلة هي HUF أو EUR أو USD، وأن تلك العملة لديها Merchant ID وSecret key في الوضع الحالي: حسابات sandbox عندما يكون Sandbox mode مُفعّلًا، وحسابات الإنتاج عندما يكون مُعطّلًا. وفي Payment > Preferences تحقق من أن الوحدة مسموح بها لعملة السلة ولدولة العميل ولمجموعة العميل.

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

يرد IPN بـ Invalid signature: يسمّي إشعار IPN حساب تاجر غير موجود في الإعدادات، أو أن Secret key الخاص به غير صحيح، أو أنه وُقّع بحساب من وضع آخر غير وضع الدفعة. أدخل MERCHANT وSECRET KEY تمامًا كما تعرضهما لوحة تاجر SimplePay. وتعيد SimplePay إرسال الإشعارات غير المؤكدة.

يرد IPN بـ Order not found أو Unknown transaction: الإشعار يخص دفعة لم يبدأها هذا المتجر. لا يتغيّر شيء.

يرد IPN بـ Busy, retry: كانت سلة التسوق تُعالَج بطلب آخر في اللحظة نفسها، أو تعذّر إنشاء الطلب (مثلًا لأن الوحدة مُعطّلة). تعيد SimplePay محاولة إرسال IPN. ويُكتب السبب في السجل.

يرى العميل الرسالة The SimplePay payment could not be started: انظر حقل Log في صفحة الوحدة. يؤدي المفتاح السري الخاطئ إلى ظهور Invalid response signature from SimplePay. Check the secret key of the merchant account. وتُسجَّل أخطاء SimplePay مع رموزها.

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

الطلب في حالة SimplePay payment on hold بعد الدفع: اقرأ الملاحظات في كتلة SimplePay payment. تغيّر إجمالي سلة التسوق أو عملتها بعد بدء الدفع. نفّذ الطلب أو استرد الدفع من لوحة تاجر SimplePay.

فشل الاسترداد: اقرأ الرسالة في الكتلة. تعني SimplePay refunds in HUF must be whole amounts. أن مبلغ HUF كان يحتوي على كسور عشرية. وإذا قالت الرسالة إن حساب التاجر لهذه الدفعة غير مُعدّ، فأدخل الحساب (العملة والوضع) الذي تمت به الدفعة مرة أخرى. وإذا استردّت SimplePay مبلغًا مختلفًا، فتطلب منك الرسالة التحقق من الاسترداد في لوحة SimplePay.

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

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

SimplePay علامة تجارية مسجّلة لمالكها. هذه الوحدة غير تابعة لـ SimplePay ولا تحظى بتأييدها.