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

المتطلبات

WordPress: 6.2 أو أحدث.

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

PHP: 8.0 أو أحدث.

العملة: الراند الجنوب أفريقي (ZAR)، ويُضبط في WooCommerce > Settings > General. تُسوّي PayFast المدفوعات بالراند فقط. الحد الأدنى لمبلغ الطلب هو R5.00.

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

موقع متاح: يجب أن يكون عنوان URL لإشعارات الدفع متاحًا من الإنترنت، دون وضع الصيانة أو المصادقة الأساسية أو حجب من جدار الحماية.

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

التثبيت

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

2. انقر على Activate.

3. اضبط عملة المتجر على الراند الجنوب أفريقي في WooCommerce > Settings > General.

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

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

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

7. فعّل Enable/Disable واحفظ. أجرِ دفعة تجريبية، ثم عطّل وضع الاختبار لقبول المدفوعات الحقيقية.

الإعدادات

جميع الإعدادات موجودة في صفحة واحدة: WooCommerce > Settings > Payments > PayFast. وتعرض الصفحة فوق الحقول تحذيرًا عندما تكون بيانات اعتماد الوضع الحالي فارغة (فيُخفى PayFast عند الدفع)، أو عندما لا تكون عملة المتجر ZAR، أو عندما يستخدم الوضع الحي معرّف التاجر التجريبي العام 10000100، أو عندما لا تكون عبارة المرور معيّنة. كما تعرض Test mode is on: orders are paid in the PayFast sandbox, no real money is charged. طالما كان وضع الاختبار مفعّلًا. وفي قائمة طرق الدفع يُعرض PayFast على أنه بحاجة إلى إعداد إلى أن يُدخل Merchant ID وMerchant Key للوضع الحالي.

عام

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. يرى العميل عند الدفع TEST MODE: payments go to the PayFast sandbox, no real money is charged. الافتراضي: مفعّل.

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

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

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

عند التحديث من الإصدار 1.0 في وضع الاختبار، تُنسخ بيانات الاعتماد الحالية إلى حقول sandbox. تحقق من بيانات الاعتماد الحية قبل تعطيل وضع الاختبار.

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

تؤكد PayFast كل دفعة عبر إشعار من الخادم إلى الخادم يُرسل إلى العنوان المعروض في هذا القسم. وهو بالشكل التالي: https://your-site/wc-api/payfast_pay/. يُرسل العنوان مع كل دفعة، لذلك لا يلزم إعداد شيء في PayFast، لكن يجب أن يكون متاحًا من الإنترنت.

التحقق من المصدر: Accept live notifications only from PayFast servers. تأتي العناوين من سجلات DNS الخاصة بـ PayFast. عطّل هذا الخيار فقط إذا كان موقعك خلف وكيل (proxy) أو شبكة CDN تُخفي عنوان الزائر. يُتحقق دائمًا من التوقيع والتأكيد من الخادم. لا تُتحقق إشعارات sandbox بالعنوان. الافتراضي: مفعّل.

متقدم

Debug log: Log payment steps يكتب الخطوات في WooCommerce > Status > Logs، بمصدر wcp_payfast_pay. تُسجَّل الأخطاء دائمًا. لا تُكتب عبارات المرور أو تفاصيل العملاء. الافتراضي: معطّل.

Uninstall: Delete the gateway settings and logs when the plugin is deleted. الافتراضي: معطّل.

الدفع

يختار العميل طريقة الدفع (افتراضيًا PayFast) ويُكمل طلبه. ينتقل العميل إلى صفحة Pay for order الخاصة بالطلب، وتعرض Thank you for your order. You are being redirected to PayFast to complete the payment. وتُرسل استمارة الدفع الموقعة إلى PayFast تلقائيًا. إذا لم يتابع المتصفح وحده، ينقر العميل على Pay with PayFast؛ وCancel order يلغي الطلب. يتضمن النموذج إجمالي الطلب بالراند (ZAR)، وOrder # مع رقم الطلب، واسم العميل وبريده الإلكتروني، ومفتاح الطلب. يُعاد إنشاؤه في كل مرة تُفتح فيها الصفحة، لذلك يمكن للعميل إعادة فتحها بعد العودة من PayFast.

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

لا تغيّر عودة العميل إلى صفحة استلام الطلب الطلبَ نفسه. وطالما لم يصل الإشعار، تعرض الصفحة 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.

إذا ألغى العميل في صفحة PayFast، يُلغى الطلب بالطريقة القياسية في WooCommerce. وإذا غادر العميل دون الدفع، يبقى الطلب غير مدفوع ويمكن دفعه من صفحة Pay for order.

تعمل طريقة الدفع في الدفع الكلاسيكي، وفي كتلة Checkout، وفي صفحة Pay for order. وتُخفى عند غياب بيانات اعتماد الوضع الحالي، أو عندما لا تكون عملة المتجر أو الطلب ZAR، أو عندما يقل الإجمالي عن R5.00. وهي متوافقة مع تخزين الطلبات عالي الأداء (HPOS) في WooCommerce.

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

الطلبات

حالات الطلب

Pending payment: أُرسل العميل إلى PayFast، ولم يصل إشعار الدفع بعد.

Processing: أكدت PayFast الدفعة. وهذه هي الحالة القياسية في WooCommerce بعد الدفع؛ وتصبح الطلبات التي تحتوي على منتجات افتراضية قابلة للتنزيل فقط مكتملة. تُظهر ملاحظة الطلب معرّف دفعة PayFast، وهو أيضًا معرّف المعاملة للطلب. تحصل الدفعة التجريبية على ملاحظة تفيد بأنه لم يُخصم أي مبلغ حقيقي. وتُحفظ رسوم PayFast والمبلغ الصافي في الطلب.

On hold: أبلغت PayFast بأن الدفعة معلّقة؛ أو أن المبلغ المدفوع يختلف عن إجمالي الطلب، أو أن الطلب ليس بالراند (ZAR)؛ أو وصلت دفعة لطلب كان قد أُلغي. تشرح ملاحظة الطلب السبب. تحقق من الطلب ومن لوحة PayFast، ثم اشحن الطلب أو استرد الدفعة في PayFast.

Failed: أبلغت PayFast بأن الدفعة فشلت بينما كان الطلب غير مدفوع. يمكن للعميل إعادة الدفع.

Cancelled: ألغى العميل الدفع في صفحة PayFast، أو ألغيت أنت الطلب، أو ألغاه انتهاء مهلة حجز المخزون في WooCommerce.

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

الاسترداد

لا يُدعم الاسترداد من WooCommerce. استرد الدفعة من لوحة PayFast، ثم أنشئ استردادًا يدويًا في WooCommerce.

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

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

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

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

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

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

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

تم الدفع لكن الطلب بقي في حالة «في انتظار الدفع»: تعذّر على PayFast تسليم إشعار الدفع، أو رُفض الإشعار. فعّل Debug log وراجع WooCommerce > Status > Logs، بمصدر wcp_payfast_pay. الأسباب المعتادة: أن الموقع غير متاح من الإنترنت (وضع الصيانة، أو المصادقة الأساسية، أو جدار الحماية)، أو وجود عبارة مرور مختلفة في PayFast والإضافة، أو، في الوضع الحي خلف وكيل أو CDN، التحقق من المصدر. في هذه الحالة، عطّل Source check.

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

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

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

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

يرد الإشعار بـ Not configured: بيانات اعتماد الوضع الذي دُفع به الطلب مفقودة.

يرى العميل PayFast accepts payments from R5.00: إجمالي الطلب أقل من الحد الأدنى لـ PayFast.

الطلب في حالة On hold: أكدت PayFast دفعة لا تطابق الطلب (مبلغ مختلف، أو عملة غير ZAR)، أو وصلت دفعة لطلب كان قد أُلغي. تحقق من ملاحظات الطلب ومن لوحة PayFast.

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

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

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

يُبقي تعطيل الإضافة جميع البيانات كما هي. لإزالتها، عطّلها واحذفها من صفحة Plugins. يُحذف مفتاح الترخيص وحالة الترخيص الخاصان بهذه الإضافة دائمًا. أما إعدادات البوابة وخياراتها الأخرى والعناوين المخزّنة لـ PayFast وسجلاتها فلا تُحذف إلا إذا كان Delete the gateway settings and logs when the plugin is deleted مفعّلًا؛ وإلا تبقى لإعادة التثبيت لاحقًا. وتحتفظ الطلبات الحالية بملاحظات الدفع ومعرّفات المعاملات.

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