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

المتطلبات

OpenCart: الإصدار 3.0.x (تم الاختبار على 3.0.5.0) أو الإصدار 4.0.2 والإصدارات الأحدث (تم الاختبار على 4.1.0.3).

PHP: الإصدار 8.0 أو أحدث.

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

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

Reachable store: يجب أن يكون عنوان URL لإشعار الدفع متاحًا من الإنترنت، دون مصادقة أساسية (basic auth) ودون حظر من جدار الحماية.

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

التثبيت

التنزيل ملف zip واحد يحتوي على الحزم لكلا إصداري OpenCart. فكّ ضغطه على جهازك. يحتوي على README.txt، وحزمة OpenCart 3 وهي wcp_payfast_pay-oc3-(version).ocmod.zip، وحزمة OpenCart 4 وهي wcp_payfast_pay.ocmod.zip. ثبّت فقط الحزمة الخاصة بإصدار OpenCart لديك. مفتاح الترخيص واحد لكلا الإصدارين.

OpenCart 3

1. في لوحة الإدارة، انتقل إلى Extensions > Installer، ثم انقر على Upload واختر الملف wcp_payfast_pay-oc3-(version).ocmod.zip. لا تحتوي الإضافة على تعديلات OCMOD، لذلك لا حاجة إلى تحديث Extensions > Modifications. وبدلًا من أداة التثبيت يمكنك نسخ محتويات المجلد upload الموجود في هذه الحزمة إلى المجلد الجذر لمتجرك.

2. انتقل إلى Extensions > Extensions واختر النوع Payments. ابحث عن VibeFox PayFast Pay Gateway وانقر على Install (زر + الأخضر).

3. انقر على Edit (زر القلم) لفتح صفحة الإعدادات. الصق مفتاح ترخيص VibeFox الخاص بك في License key ضمن كتلة الترخيص في أعلى الصفحة، ثم انقر على Activate (راجع قسم مفتاح الترخيص).

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

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

OpenCart 4

1. في لوحة الإدارة، انتقل إلى Extensions > Installer، وانقر على Upload، ثم اختر الملف wcp_payfast_pay.ocmod.zip. لا تُغيّر اسم الملف: يأخذ OpenCart 4 رمز الإضافة من اسم الملف، ولا تعمل الحزمة التي غُيّر اسمها.

2. تظهر الحزمة في قائمة الإضافات المثبتة في الصفحة نفسها. انقر على Install (زر + الأخضر) بجوارها.

3. انتقل إلى Extensions > Extensions واختر النوع Payments. ابحث عن VibeFox PayFast Pay Gateway، وانقر على Install (زر + الأخضر)، ثم على Edit (زر القلم).

4. أدخل مفتاح الترخيص وبيانات اعتماد PayFast، واختبر الدفع كما في الخطوات من 3 إلى 5 الخاصة بـ OpenCart 3. صفحة الإعدادات وحقولها متطابقة في الإصدارين. الاختلاف الوحيد هو عنوان Notification URL (انظر Notification URL)، وهو أيضًا يُرسل إلى PayFast مع كل دفعة.

تبدأ التثبيتات الجديدة بطريقة الدفع معطّلة ووضع الاختبار مفعّلًا.

الإعدادات

جميع الإعدادات موجودة في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox PayFast Pay Gateway > Edit. تُعرض الأقسام في الجهة اليسرى؛ وزر Save أسفل القائمة يحفظ الصفحة كاملة. وفوق الإعدادات تحذّرك الصفحة عندما تكون بيانات اعتماد الوضع الحالي فارغة (فيُخفى PayFast عندئذٍ في صفحة الدفع)، وعندما لا تكون العملة الافتراضية للمتجر ZAR، وعندما يستخدم الوضع الفعلي معرّف التاجر العام لبيئة Sandbox ‏10000100، وعندما لا تكون هناك عبارة مرور مُعدّة. وما دام وضع الاختبار مفعّلًا فإنها تعرض Test mode is on: orders are paid in the PayFast sandbox, no real money is charged.

عند الحفظ، لا يمكن أن يكون Title فارغًا (حتى 128 حرفًا)، ويجب أن يكون Sort Order عددًا صحيحًا (الأعداد السالبة مسموحة)، ويجب أن يكون Total رقمًا أكبر من أو يساوي 0، ويجب أن تكون المنطقة الجغرافية وحالات الطلب المختارة موجودة؛ وإلا فلن يُحفظ شيء وستُشير الصفحة إلى الحقل المعني. وإذا فعّلت طريقة الدفع دون بيانات اعتماد الوضع الحالي، تُحفظ الإعدادات مع تحذير.

PayFast

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

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

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

Sort Order: موضع PayFast بين طرق الدفع عند الدفع. اتركه فارغًا أو أدخل عددًا صحيحًا.

Geo Zone: اعرض PayFast فقط لعناوين الدفع الواقعة ضمن المنطقة الجغرافية المختارة. الافتراضي: All zones. تُعدّ المناطق الجغرافية في System > Localisation > Geo Zones. وفي OpenCart 4، عندما لا يطلب المتجر عنوان الدفع، يُستخدم عنوان الشحن.

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

حساب 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. عند تفعيله يرى العميل في خطوة Confirm Order النص TEST MODE: payments go to the PayFast sandbox, no real money is charged. الافتراضي: مفعّل.

Sandbox Merchant ID: الـ Merchant ID الخاص بحساب Sandbox لديك.

Sandbox Merchant Key: الـ Merchant Key الخاص بحساب Sandbox لديك.

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

لا تُعرض عبارات المرور المحفوظة مرة أخرى. يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها. ولحذف عبارة مرور محفوظة، ضع علامة على Clear the saved passphrase on save أسفل الحقل، ثم انقر على Save.

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

Notification URL: يؤكد PayFast كل عملية دفع عبر إشعار من الخادم إلى الخادم يُرسل إلى عنوان URL المعروض هنا. في OpenCart 3 يبدو على النحو التالي https://your-store/index.php?route=extension/payment/wcp_payfast_pay/itn، وفي OpenCart 4 على النحو التالي https://your-store/index.php?route=extension/wcp_payfast_pay/payment/wcp_payfast_pay.itn. ويُبنى من عنوان واجهة متجرك في تثبيت OpenCart. يُرسل هذا العنوان مع كل عملية دفع، فلا حاجة إلى إعداد أي شيء في PayFast، لكن يجب أن يكون متاحًا من الإنترنت. لا تحصل الطلبات على حالتها إلا من هذه الإشعارات الموثّقة؛ ولا يؤدي عودة العميل إلى المتجر إلى تغيير الطلب.

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

الطلبات

ينشئ OpenCart الطلب في خطوة Confirm Order دون حالة (طلب مفقود). ولا يحصل الطلب على حالة إلا من إشعار PayFast موثّق. وأي دفعة ملغاة أو فاشلة أو متروكة تُبقي الطلب دون حالة، ويمكن للعميل أن يدفع مرة أخرى. يسرد كل حقل أدناه حالات الطلب في OpenCart لديك.

Order Status (paid): الحالة بعد أن يؤكد PayFast الدفع وتتطابق القيمة والعملة. الافتراضي: قيد المعالجة.

Awaiting PayFast payment: أبلغ PayFast عن الدفعة بأنها قيد الانتظار (مثل Instant EFT). تتحول إلى حالة الدفع المكتمل عندما يُنجزها PayFast. الافتراضي: قيد الانتظار.

PayFast payment on hold: دفعة تحتاج إلى مراجعتك (راجع قسم حالات الطلب). لا يُعلَّم هذا الطلب كمدفوع؛ وتشرح ملاحظة السبب. الافتراضي: قيد الانتظار، لأن OpenCart لا يملك حالة On hold. يمكنك إنشاء حالتك الخاصة في System > Localisation > Order Statuses واختيارها هنا.

Payment failed: فشلت دفعة كانت قيد الانتظار. وإذا أنجزها PayFast لاحقًا، يتحول الطلب إلى حالة الدفع المكتمل. الافتراضي: فشل.

خيارات متقدمة

Debug log: يسجل خطوات الدفع في payfast_p_debug.log.php داخل مجلد السجلات في OpenCart (storage/logs). لا يمكن فتح الملف من الويب، وعند بلوغه 5 ميغابايت يُنقل إلى payfast_p_debug.old.log.php. تُسجَّل الأخطاء والتحذيرات دائمًا، حتى عندما يكون المفتاح معطّلًا. لا تُكتب أي عبارات مرور أو مفاتيح أو بيانات عملاء. الافتراضي: معطّل.

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

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

الاستيراد / التصدير

Export: Download JSON يحفظ الإعدادات في ملف JSON. لا تُصدَّر عبارات المرور.

Import: الصق ملف JSON صُدِّر سابقًا وانقر على Import لاستعادة الإعدادات. تبقى عبارات المرور المحفوظة كما هي.

الدفع

في خطوة Payment Method يختار العميل طريقة الدفع (افتراضيًا PayFast). وفي خطوة Confirm Order يرى العميل وصفك والملاحظة Thank you for your order. You will be redirected to PayFast to complete the payment. ينشئ OpenCart الطلب في هذه الخطوة، ولا يزال بلا حالة. في OpenCart 4 يختار العميل طريقة الدفع بزر Choose في كتلة طريقة الدفع، في النافذة Payment method options، وينقر على Confirm Order في أسفل صفحة الدفع. عندما ينقر العميل على Confirm Order ترسل الإضافة نموذج الدفع الموقّع إلى PayFast. يتضمن النموذج قيمة الطلب بعملة ZAR، وOrder # مع رقم الطلب، واسم العميل وبريده الإلكتروني، ومرجع الدفع (رقم الطلب ومحاولة الدفع)، ورمزًا عشوائيًا (token) لمحاولة الدفع. تحصل كل محاولة جديدة على مرجع ورمز جديدين.

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

ثم يحصل الطلب على حالته بالطريقة المعيارية في OpenCart، مع رسائل البريد الإلكتروني المعتادة للطلب وتحديث المخزون. تُعالج الإشعارات الخاصة بسلة واحدة واحدًا تلو الآخر؛ فإذا كان إشعار آخر لنفس السلة قيد المعالجة، يتلقى PayFast ردًّا بخطأ ويعيد إرسال الإشعار. يعمل عنوان URL للإشعارات أيضًا عندما يكون المتجر في وضع الصيانة: يسمح OpenCart 3 بمرور طلبات إضافات الدفع، وتضيف الإضافة على OpenCart 4 إجراء بدء تشغيل (startup action) يسمح بمرور الإشعار وعودة العميل من PayFast.

عندما يعود العميل ويكون للطلب حالة، تُعرض صفحة نجاح الطلب في OpenCart. وإذا أبلغ PayFast عن الدفعة بأنها قيد الانتظار، تُعرض أيضًا الرسالة PayFast is confirming your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. وإذا كان الطلب معلّقًا تُعرض Your payment is being reviewed. We will contact you if anything else is needed. وإذا فشلت دفعة كانت قيد الانتظار لاحقًا تُعرض Your PayFast payment was not completed. Please contact us about this order. (في OpenCart 4 يُعاد العميل إلى صفحة الدفع بدلًا من ذلك، انظر أدناه). وإذا لم يصل الإشعار بعد، فستعرض صفحة Payment confirmation أن PayFast يؤكد الدفع، مع الزرين Check again وBack to checkout.

إذا ألغى العميل في صفحة PayFast يعود إلى صفحة الدفع مع الرسالة The PayFast payment was cancelled. You can try again or choose another payment method. وإذا أبلغ PayFast عن فشل الدفعة، تكون الرسالة The payment was not completed. You can try again or choose another payment method. تُحفظ السلة ويمكن دفعها مرة أخرى. في OpenCart 4 تُعرض هذه الرسائل فوق صفحة الدفع. يُنشئ OpenCart 3 طلبًا جديدًا في كل مرة تُعرض فيها خطوة Confirm Order، ويحتفظ OpenCart 4 بطلب واحد للدفع ويحدّثه، لذلك بعد دفعة ملغاة أو فاشلة يدفع العميل الطلب نفسه بمحاولة جديدة. وإذا كان طلب آخر من السلة نفسها قد عالجه PayFast بالفعل (مثلًا في تبويب متصفح ثانٍ)، ينتقل العميل إلى صفحة النجاح بدلًا من الدفع مرة أخرى.

يحتفظ OpenCart 4 بالطلب في عملية الدفع حتى تُعرض صفحة النجاح. وإذا أُغلق ذلك الطلب دون دفعة في هذه الأثناء (مثلًا فشلت دفعته المعلّقة أو ألغيته)، يعود العميل إلى صفحة الدفع مع Your previous order was cancelled or its payment failed. Please confirm the order again.، وفي Confirm Order التالي يُدفع طلب جديد. وإذا كان لذلك الطلب حالة بالفعل وتغيّرت محتويات السلة إلى منتجات أو كميات أخرى، تكون الرسالة Your previous order has already been placed for other cart contents. Please confirm the order of your current cart again.

تُخفى طريقة الدفع عندما تكون بيانات اعتماد الوضع الحالي مفقودة، أو عندما لا تكون عملة الدفع ZAR، أو عندما يكون الإجمالي أقل من R5.00. وإذا وصل العميل إلى الدفع رغم ذلك، فإن رسالة قصيرة فوق الزر تشرح السبب، مثل PayFast accepts payments from R5.00. Please choose another payment method.

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

الطلبات

حالات الطلب

No status (missing order): أُرسل العميل إلى PayFast ولم يصل إشعار الدفع بعد، أو أبلغ PayFast عن فشل الدفعة. في Sales > Orders لا تظهر مثل هذه الطلبات إلا عند ضبط الفلتر Order Status على Missing Orders.

في OpenCart 4 قد يحصل طلب غير مدفوع من عملية الدفع على الحالة Voided، التي يعيّنها OpenCart 4 عندما يعود العميل إلى خطوة Confirm Order. تعامل الإضافة هذا الطلب كطلب دون حالة، ويؤكده أي دفع لاحق.

Order Status (paid) (default Processing): أكّد PayFast الدفع. تعرض ملاحظة معرّف الدفع في PayFast. تحصل دفعة Sandbox على ملاحظة تفيد بأنه لم يُخصم أي مبلغ حقيقي.

Awaiting PayFast payment (default Pending): أبلغ PayFast عن الدفعة بأنها قيد الانتظار. ينتقل الطلب إلى حالة الدفع المكتمل عندما يُنجز PayFast الدفع، أو إلى Payment failed عندما تفشل الدفعة؛ ويُبلَّغ العميل بهذه التغييرات عبر البريد الإلكتروني.

Payment failed (default Failed): فشلت دفعة كانت قيد الانتظار. وإذا أنجزها PayFast لاحقًا، يتحول الطلب إلى حالة الدفع المكتمل.

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

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

الملاحظات هي إدخالات في History الطلب، ولا يراها العميل.

علامة تبويب VibeFox PayFast Pay Gateway

في Sales > Orders افتح طلبًا مدفوعًا عبر PayFast. في أسفل صفحة الطلب، بجوار History وAdditional، تعرض علامة التبويب VibeFox PayFast Pay Gateway الحقول Payment reference (m_payment_id) وPayFast payment ID وEnvironment (فعلي أو Sandbox) والمبلغ المطلوب والحالة والمبالغ الإجمالية والرسوم والصافية بعملة ZAR، إضافة إلى PayFast notes. وبالنسبة إلى طلب معلّق، تعرض تذكيرًا بمراجعة الدفعة. تُعرض علامة التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة.

الاستردادات

الاستردادات من صفحة الطلب غير مدعومة. استرد الدفعة من لوحة PayFast، ثم حدّث الطلب يدويًا في OpenCart.

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

تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox PayFast Pay Gateway هي أول كتلة في Extensions > Extensions > Payments > VibeFox PayFast Pay Gateway > Edit، فوق الإعدادات. الصق المفتاح في License key وانقر على Activate. بعد ذلك تعرض الكتلة المفتاح بشكل مُخفى، والحالة (مثل تاريخ انتهاء صلاحية الترخيص ونطاقك)، وأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وأسفلها سطر Product: opencart-payment-payfast ورابط Manage licenses and domains in your account الذي يفتح حسابك على vibefox.net. ولا يمكن تغيير المفتاح إلا لمستخدمي الإدارة الذين لديهم صلاحية Modify للإضافة. تتبع نصوص الكتلة لغة لوحة الإدارة (تتضمن الإنجليزية والروسية).

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

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

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

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

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

PayFast does not appear at checkout: تحقّق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن الـ Merchant ID والـ Merchant Key للوضع الحالي مُدخلان، وأن عملة الدفع ZAR، وأن إجمالي الطلب 5.00 راند على الأقل. تعرض صفحة الإعدادات تحذيرًا عندما يكون شيء ما مفقودًا. وتحقّق أيضًا من أن عنوان الدفع ضمن Geo Zone المختارة، وأن الطلب يبلغ Total المحدد في الإعدادات.

The payment went through, but the order stays without a status: لم يتمكن PayFast من تسليم إشعار الدفع، أو رُفض الإشعار. انظر إلى الحقل Log في صفحة الإضافة؛ فالأخطاء والإشعارات المرفوضة تُسجَّل دائمًا، وDebug log يضيف كل خطوة. الأسباب الشائعة: المتجر غير متاح من الإنترنت (مصادقة أساسية، جدار حماية)، أو عبارة مرور مختلفة في PayFast والإضافة، أو في الوضع الفعلي خلف وكيل أو CDN فيفشل فحص المصدر. وفي هذه الحالة عطّل Source check.

The notification answers Invalid signature: عبارة المرور في الإضافة ليست العبارة المُعدّة في PayFast للوضع الذي تمت فيه عملية الدفع.

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

The notification answers Merchant mismatch or Order mismatch: تمت عملية الدفع إلى حساب PayFast آخر، أو أنها لا تنتمي إلى محاولة الدفع هذه. لا يتغير شيء.

The notification answers Order not found: مرجع الدفع غير معروف لهذا المتجر. لا يتغير شيء.

The notification answers Confirmation unavailable, Busy or Temporary error: تعذّر الوصول إلى PayFast للتأكيد من الخادم، أو كان إشعار آخر لنفس السلة قيد المعالجة في اللحظة نفسها، أو تعذّر ضبط حالة الطلب. يعيد PayFast محاولة الإشعار. ويعرض السجل السبب.

The notification answers Not configured: بيانات اعتماد الوضع الذي بدأت فيه عملية الدفع مفقودة. أعد إدخالها، مثل بيانات اعتماد Sandbox لعملية دفع تجريبية.

The customer sees PayFast accepts payments in South African rand (ZAR) only: الطلب بعملة أخرى. اجعل العميل يدفع بالراند أو يختر طريقة دفع أخرى.

The customer sees This payment method is not available. Please reload the checkout page. جلسة الدفع لم تعد تتطابق مع الطلب، أو أُوقفت طريقة الدفع في هذه الأثناء. على العميل إعادة تحميل صفحة الدفع.

Order is in the on-hold status: اقرأ الملاحظات في علامة التبويب VibeFox PayFast Pay Gateway (راجع قسم حالات الطلب) ولوحة PayFast، ثم اضبط حالة الدفع المكتمل أو استرد الدفعة.

A sandbox payment did not pay the order: البوابة في الوضع الفعلي. لا تدفع دفعات Sandbox أي طلب في الوضع الفعلي؛ وتشير ملاحظة على الطلب إلى ذلك.

للمطوّرين: قبل توقيع نموذج الدفع، تُطلق الإضافة حدث OpenCart باسم payfast_p_payment_data مع حقول النموذج والطلب. ولا يمكن تغيير بيانات اعتماد التاجر أو عناوين URL أو مرجع الدفع أو المبلغ أو الرمز عبره.

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

انتقل إلى Extensions > Extensions، واختر النوع Payments، ثم انقر على Uninstall (الزر الأحمر −) بجوار VibeFox PayFast Pay Gateway. تُحذف دائمًا بيانات مفتاح الترخيص وحالته لهذه الإضافة. ويحذف OpenCart دائمًا إعدادات الإضافة الخاصة به: Enable/Disable وSort Order وGeo Zone وTotal وحالات الطلب في قسم Orders، والتي تعود إلى قيمها الافتراضية عند إعادة التثبيت. ويُحذف أيضًا حدث OpenCart الخاص بالإضافة (وفي OpenCart 4 أحداثها وإجراء بدء التشغيل الخاص بها، الذي يسمح بمرور الإشعار وعودة العميل في وضع الصيانة). وإذا كان Delete the gateway settings when the extension is uninstalled مفعّلًا، فستُحذف بقية إعدادات البوابة (العنوان والوصف وبيانات الاعتماد وعبارات المرور ووضع الاختبار و Source check والتسجيل) وعناوين PayFast المخزّنة مؤقتًا والسجل. أما إذا كان معطّلًا فتُحفظ لإعادة التثبيت لاحقًا. تُحفظ سجلات مدفوعات PayFast والطلبات دائمًا. وتحتفظ الطلبات الحالية بملاحظات الدفع الخاصة بها.

في OpenCart 4، ولإزالة ملفات الإضافة أيضًا، انتقل إلى Extensions > Installer بعد إلغاء التثبيت وانقر على Uninstall (الزر البرتقالي −) بجوار VibeFox PayFast Pay Gateway في قائمة الإضافات المثبتة، ثم على Delete (زر سلة المهملات الأحمر) لإزالة الحزمة المرفوعة.

PayFast علامة تجارية مسجلة لمالكها. هذه الإضافة غير تابعة لـ PayFast ولا معتمدة منها.