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

المتطلبات

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

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

العملة: الراند الجنوب أفريقي (ZAR). تُسوّي PayFast المدفوعات بالراند فقط، لذلك يجب أن تكون السلة بالراند. أضف العملة في International > Localization > Currencies إذا لم تكن متوفرة في متجرك بعد. الحد الأدنى لإجمالي الطلب هو R5.00.

حساب PayFast: Merchant ID وMerchant Key لحساب PayFast الخاص بك، ويمكن العثور عليهما في Settings > Developer Settings في لوحة PayFast. يُنصح بشدة بتعيين عبارة مرور؛ فإذا كانت معيّنة في PayFast، يجب إدخال العبارة نفسها في الوحدة. للاختبارات تحتاج إلى بيانات اعتماد sandbox الخاصة بـ PayFast.

متجر متاح: يجب أن يكون عنوان إشعار الدفع متاحًا من الإنترنت، دون basic auth أو حجب من جدار الحماية.

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

التثبيت

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

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

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

4. أدخل Merchant ID وMerchant Key وعبارة المرور. للاختبار، أبقِ Test mode مفعّلًا وأدخل بيانات اعتماد sandbox.

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

عند التثبيت تُنشئ الوحدة حالتين للطلب: Awaiting PayFast payment وPayFast payment on hold. يوفّر PrestaShop وحدة دفع جديدة لجميع العملات والدول ومجموعات العملاء. يمكنك تقييدها من Payment > Preferences؛ وتأكد من أن الوحدة تبقى مسموحًا بها للراند.

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox PayFast Pay Gateway > Configure. لكل قسم زر Save الخاص به، ويحفظ الصفحة بأكملها. تظهر فوق الحقول تحذيرات عندما تكون بيانات اعتماد الوضع الحالي فارغة (عندها يُخفى PayFast عند الدفع)، وعندما لا تكون عملة المتجر الافتراضية ZAR، وعندما يستخدم الوضع الحي معرّف التاجر العام لـ sandbox وهو 10000100، وعندما لا تكون عبارة المرور معيّنة. وأثناء تفعيل وضع الاختبار والوحدة مفعّلة تظهر الرسالة: وضع الاختبار مفعّل: تُدفع الطلبات في sandbox الخاص بـ PayFast ولا يُخصم أي مبلغ حقيقي. وعند ترك حقل Title فارغًا يُرفض الحفظ مع الرسالة أدخل عنوانًا لطريقة الدفع.

PayFast

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

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

Description: النص الذي يظهر أسفل طريقة الدفع عند الدفع. الافتراضي: Pay securely by card, Instant EFT and other methods on the PayFast payment page.

حساب PayFast (الوضع الحي)

يمكنك العثور على Merchant ID وMerchant Key في لوحة PayFast ضمن Settings > Developer Settings. إذا عيّنت عبارة مرور هناك، فأدخل العبارة نفسها تمامًا هنا.

Merchant ID: معرّف التاجر الحي الخاص بك في PayFast.

Merchant Key: مفتاح التاجر الحي الخاص بك في PayFast. يُرسل إلى PayFast مع كل نموذج دفع، لذلك هو حقل نصي عادي.

Passphrase: عبارة المرور الملحية (salt) من PayFast، ضمن Settings > Developer Settings. يُنصح بشدة بها: فهي توقّع المدفوعات والإشعارات.

Sandbox (وضع الاختبار)

في وضع الاختبار تُرسل المدفوعات إلى sandbox الخاص بـ PayFast ولا يُخصم أي مبلغ حقيقي. تظهر بيانات اعتماد sandbox بعد تسجيل الدخول إلى sandbox الخاص بـ PayFast (التاجر العام للاختبار هو 10000100 / 46f0cd694581a).

Test mode: Use the PayFast sandbox and the sandbox credentials below. عند تفعيله يرى العميل أسفل طريقة الدفع: وضع الاختبار: تُرسل المدفوعات إلى sandbox الخاص بـ PayFast ولا يُخصم أي مبلغ حقيقي. الافتراضي: مفعّل.

Sandbox Merchant ID: معرّف التاجر لحساب sandbox الخاص بك.

Sandbox Merchant Key: مفتاح التاجر لحساب sandbox الخاص بك.

Sandbox Passphrase: فقط إذا كانت عبارة المرور معيّنة في حساب sandbox الخاص بك.

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

Clear saved passphrases: ضع علامة على Passphrase أو Sandbox Passphrase وانقر على Save لحذفها. يُبقي الحقل الفارغ القيمة المحفوظة.

إشعارات الدفع (ITN)

Notification URL: تؤكد PayFast كل دفعة بإشعار من الخادم إلى الخادم يُرسل إلى العنوان المعروض هنا. مع الروابط الودية يبدو هكذا: https://your-shop/module/wcp_payfast_pay/itn، وقد يتضمن رمز اللغة الافتراضية. يُرسل العنوان مع كل دفعة، لذلك لا يلزم ضبط شيء في PayFast، لكن يجب أن يكون متاحًا من الإنترنت. لا تُنشأ الطلبات إلا بهذه الإشعارات الموثّقة؛ فعودة العميل إلى المتجر لا تُنشئ الطلب ولا تدفعه.

Source check: اقبل إشعارات الوضع الحي من خوادم PayFast فقط. تأتي العناوين من سجلات DNS الخاصة بـ PayFast (مخزّنة مؤقتًا لمدة 6 ساعات) ومن نطاقات العناوين الموثّقة لدى PayFast. عطّله فقط إذا كان متجرك خلف proxy أو CDN يُخفي عنوان الزائر. يُتحقق دائمًا من التوقيع والتأكيد من الخادم. لا تُفحص إشعارات sandbox بحسب العنوان. الافتراضي: مفعّل.

متقدم

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

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

Uninstall: Delete the gateway settings when the module is uninstalled (الإعدادات، وعناوين PayFast المخزّنة، والسجل). تُحفظ دائمًا سجلات مدفوعات PayFast والطلبات وحالات الطلبات. الافتراضي: إيقاف.

الدفع

في خطوة الدفع يختار العميل طريقة الدفع (افتراضيًا PayFast) ويؤكد. تعرض صفحة شكرًا لطلبك. يجري تحويلك إلى PayFast لإتمام الدفع. وترسل نموذج الدفع الموقّع إلى PayFast تلقائيًا. إذا لم يتابع المتصفح وحده، ينقر العميل على Pay with PayFast؛ وCancel يعيده إلى صفحة الدفع. يحمل النموذج إجمالي السلة بالراند (ZAR)، وCart # مع رقم السلة، واسم العميل وبريده الإلكتروني، ومرجع الدفعة (رقم السلة والمحاولة)، ورمزًا عشوائيًا (token) لتلك المحاولة. لا يوجد طلب بعد في هذه المرحلة. تحصل كل محاولة جديدة على مرجع ورمز جديدين.

في صفحة PayFast يدفع العميل بالبطاقة أو Instant EFT أو بطريقة أخرى في حساب PayFast الخاص بك. ثم ترسل PayFast إشعار الدفع (ITN) إلى متجرك. لا يُعلَّم الطلب مدفوعًا إلا بعد أن تؤكد PayFast الدفعة بإشعار يجتاز جميع عمليات التحقق:

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

عندما يعود العميل ويكون الطلب موجودًا تُعرض صفحة تأكيد الطلب المعتادة. إذا أبلغت PayFast بأن الدفعة معلّقة، تظهر الرسالة: تؤكد PayFast دفعتك. ستتلقى بريدًا إلكترونيًا فور تأكيدها — لا حاجة لإعادة الدفع. وإذا كان الطلب قيد المراجعة تظهر: دفعتك قيد المراجعة. سنتواصل معك إذا لزم أي شيء آخر. وإذا فشلت الدفعة المعلّقة لاحقًا تظهر: لم تكتمل دفعتك عبر PayFast. يُرجى التواصل معنا بشأن هذا الطلب. وإذا لم يصل الإشعار بعد، تظهر صفحة Payment confirmation توضح أن PayFast تؤكد الدفعة وأن الطلب سيُنشأ فور تأكيدها، مع الزرّين Check again وBack to checkout.

إذا ألغى العميل الدفع في صفحة PayFast يعود إلى الدفع مع الرسالة تم إلغاء دفعة PayFast. يمكنك المحاولة مرة أخرى أو اختيار طريقة دفع أخرى. وإذا أبلغت PayFast بفشل الدفعة تكون الرسالة لم تكتمل الدفعة. يمكنك المحاولة مرة أخرى أو اختيار طريقة دفع أخرى. تُحفظ السلة ويمكن دفعها مرة أخرى.

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

تقبل الوحدة المدفوعات الفردية بالراند (ZAR) فقط. لا تدعم استردادًا من صفحة الطلب، ولا اشتراكات، ولا بطاقات محفوظة (مرمّزة)، ولا مدفوعات مقسّمة.

الطلبات

حالات الطلب

No order yet: أُرسل العميل إلى PayFast ولم يصل إشعار الدفع بعد، أو أبلغت PayFast بفشل الدفعة. لا توجد إلا السلة.

Payment accepted: أكدت PayFast الدفعة. تُسجَّل الدفعة بمعرّف دفعة PayFast بوصفه معرّف المعاملة، وتعرض ملاحظة معرّف الدفعة. تحصل دفعة sandbox على ملاحظة تفيد بأنه لم يُخصم أي مبلغ حقيقي.

Awaiting PayFast payment: أبلغت PayFast بأن الدفعة معلّقة. ينتقل الطلب إلى Payment accepted عندما تكملها PayFast.

Payment error: فشلت دفعة معلّقة. إذا أكملتها PayFast لاحقًا يصبح الطلب Payment accepted.

PayFast payment on hold: المبلغ المدفوع يختلف عن إجمالي السلة، أو أن السلة ليست بالراند (ZAR)؛ أو وصلت دفعة لطلب أُلغي أو لم تعد طريقة دفعه PayFast؛ أو وصلت دفعة sandbox بينما البوابة في الوضع الحي. يُسجَّل المبلغ الذي تلقّته PayFast على الطلب (ليس في حالة دفعة sandbox)، وتشرح الملاحظة السبب. تحقّق من الطلب ولوحة PayFast، ثم اضبط الطلب على Payment accepted، أو ألغِ الطلب واسترد الدفعة في PayFast.

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

كتلة دفع PayFast

تعرض صفحة الطلب كتلة PayFast payment تتضمن مرجع الدفعة (m_payment_id)، ومعرّف دفعة PayFast، والبيئة (live أو sandbox)، والحالة، والمبالغ الإجمالية والرسوم والصافية بالراند (ZAR)، وملاحظات الوحدة. وبالنسبة للطلب المعلّق تعرض تذكيرًا بمراجعة الدفعة.

الاسترداد

لا يُدعم الاسترداد من صفحة الطلب. استرد الدفعة من لوحة PayFast الخاصة بك، ثم حدّث الطلب في PrestaShop يدويًا.

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

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

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

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

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

PayFast لا يظهر عند الدفع: تحقّق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن Merchant ID وMerchant Key للوضع الحالي مُدخلان، وأن السلة بالراند (ZAR)، وأن إجمالي الطلب R5.00 على الأقل. تعرض صفحة الإعدادات تحذيرًا عند نقص أي شيء. وفي Payment > Preferences تحقّق من أن الوحدة مسموح بها للراند، ولدولة العميل، ولمجموعة العميل.

اكتملت الدفعة لكن لم يُنشأ أي طلب: تعذّر على PayFast تسليم إشعار الدفع، أو رُفض الإشعار. انظر إلى حقل Log في صفحة الوحدة؛ تُسجَّل الأخطاء والإشعارات المرفوضة دائمًا، وDebug log يضيف كل خطوة. الأسباب الشائعة: أن المتجر غير متاح من الإنترنت (basic auth، جدار حماية)، أو عبارة مرور مختلفة في PayFast والوحدة، أو في الوضع الحي خلف proxy أو CDN فتُفعَّل فحص المصدر. في هذه الحالة عطّل Source check.

يرد الإشعار بـ Invalid signature: عبارة المرور في الوحدة ليست العبارة المعيّنة في PayFast للوضع الذي تمت فيه الدفعة.

يرد الإشعار بـ Invalid source: الإشعار لم يأتِ من عنوان PayFast، أو أن proxy أو CDN يُخفي العنوان الحقيقي. عطّل Source check إذا كان متجرك خلف proxy أو CDN.

يرد الإشعار بـ Merchant mismatch أو Order mismatch: دُفعت الدفعة إلى حساب PayFast آخر أو لا تنتمي إلى محاولة الدفع هذه. لا يتغيّر شيء.

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

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

يرد الإشعار بـ Not configured: بيانات اعتماد الوضع الذي بدأت فيه الدفعة مفقودة. أعد إدخالها، مثل بيانات sandbox لدفعة اختبارية.

يرى العميل الرسالة PayFast تقبل المدفوعات بالراند الجنوب أفريقي (ZAR) فقط: السلة بعملة أخرى. اطلب من العميل الدفع بالراند أو اختيار طريقة دفع أخرى.

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

لم تدفع دفعة sandbox الطلب: البوابة في الوضع الحي. لا تدفع دفعات sandbox أي طلب في الوضع الحي؛ وتوضح ملاحظة على الطلب ذلك.

للمطوّرين: يمكن للخطاف actionPayfastPPaymentData تغيير حقول نموذج الدفع قبل توقيعها. لا يمكن تغيير بيانات اعتماد التاجر والعناوين ومرجع الدفعة والمبلغ والرمز المميز عبره.

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

انتقل إلى Modules > Module Manager، وافتح القائمة بجوار VibeFox PayFast Pay Gateway واختر Uninstall. تُحذف دائمًا مفتاح الترخيص وحالة الترخيص الخاصتان بهذه الوحدة. إذا كان Delete the gateway settings when the module is uninstalled مفعّلًا تُحذف إعدادات البوابة وعناوين PayFast المخزّنة والسجل. وإذا كان متوقفًا تُحفظ جميع الإعدادات لإعادة التثبيت لاحقًا. تُحفظ دائمًا سجلات مدفوعات PayFast والطلبات وحالتا الطلب Awaiting PayFast payment وPayFast payment on hold. تحتفظ الطلبات الحالية بملاحظات الدفع ومعرّفات المعاملات.

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