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

المتطلبات

WordPress: 6.0 أو أحدث.

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

PHP: 8.0 أو أحدث.

HTTPS: يجب أن يستخدم موقعك HTTPS لتلقي المدفوعات الحقيقية.

حساب PayPal: حساب PayPal Business مع تطبيق REST API في PayPal Developer Dashboard. تحتاج إلى Client ID وSecret الخاصين بالتطبيق. لتطبيقات sandbox وتطبيقات الإنتاج بيانات اعتماد مختلفة. لا حاجة إلى webhook: تؤكد الإضافة كل دفعة على خادمك أثناء وجود العميل في صفحة الدفع.

العملة: إحدى العملات التي تدعمها PayPal: AUD وBRL وCAD وCHF وCNY وCZK وDKK وEUR وGBP وHKD وHUF وILS وJPY وMXN وMYR وNOK وNZD وPHP وPLN وSEK وSGD وTHB وTWD أو USD.

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

التثبيت

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

2. انقر على Activate.

3. في PayPal Developer Dashboard، أنشئ تطبيق REST API (sandbox و/أو الإنتاج) وانسخ Client ID وSecret الخاصين به.

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

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

6. أدخل بيانات اعتماد الوضع الذي تستخدمه، واختر Capture أو Authorize، وفعّل Enable/Disable، ثم احفظ.

7. اختبر باستخدام حساب مشترٍ في sandbox من PayPal، ثم ألغِ تحديد Sandbox mode وأدخل بيانات اعتماد الإنتاج.

الإعدادات

توجد جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > PayPal (Smart Buttons). وفوق الحقول تحذرك الصفحة عند تفعيل وسيلة الدفع مع كون Client ID أو Secret للوضع المحدد فارغًا، وعندما لا تدعم PayPal عملة المتجر. وفي الحالتين تُخفى وسيلة الدفع في صفحة الدفع. وفي قائمة وسائل الدفع تعرض PayPal شارة Test mode في وضع sandbox، وتُعلَّم على أنها تحتاج إلى إعداد إلى أن تُملأ بيانات اعتماد الوضع المحدد.

عام

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

Title: اسم وسيلة الدفع الذي يراه العملاء في صفحة الدفع. الافتراضي: PayPal.

Description: النص الذي يظهر أسفل وسيلة الدفع في صفحة الدفع. الافتراضي: Pay with your PayPal account or a card via PayPal.

بيانات اعتماد API

أنشئ تطبيق REST API في PayPal Developer Dashboard وانسخ Client ID وSecret الخاصين به. يحتوي القسم على روابط لتطبيقات sandbox وتطبيقات الإنتاج. ولا تظهر إلا حقول الوضع المحدد.

Sandbox mode: Enable sandbox (test) mode. تُرسل المدفوعات إلى بيئة sandbox في PayPal باستخدام بيانات اعتماد sandbox، ولا تُنقل أي أموال حقيقية. الافتراضي: on. ألغِ تحديده لقبول المدفوعات الحقيقية.

Sandbox Client ID: معرّف Client ID لتطبيق REST API الخاص ببيئة sandbox.

Sandbox Secret: Secret لتطبيق REST API الخاص ببيئة sandbox.

Live Client ID: معرّف Client ID لتطبيق REST API الخاص بالإنتاج.

Live Secret: Secret لتطبيق REST API الخاص بالإنتاج.

الدفع

Payment action: ما يحدث عندما يوافق العميل على الدفعة. الافتراضي: Capture.

Capture: يُخصم المبلغ من العميل فورًا، ويصبح الطلب قيد المعالجة.

Authorize: تُحجز الأموال فقط ويوضع الطلب في حالة الانتظار. حصّل الدفعة أو ألغِها من شاشة الطلب عبر القائمة Order actions. يمكن تحصيل تفويضات PayPal خلال 29 يومًا.

متقدم

Debug log: Log API requests (errors are always logged). تُحفظ الإدخالات في WooCommerce > Status > Logs بالمصدر wcp_paypal_gateway. لا تُسجَّل بيانات الاعتماد وبيانات المشترين أبدًا. الافتراضي: off.

Delete data on uninstall: Delete the gateway settings when the plugin is deleted. تُحفظ بيانات دفع الطلبات (معرّفات PayPal المخزنة في الطلبات) دائمًا. الافتراضي: off.

الدفع

عندما يختار العميل PayPal (وهو PayPal افتراضيًا)، يحل زر PayPal محل Place order. وفي وضع sandbox تعرض صفحة الدفع الرسالة وضع sandbox: ادفع باستخدام حساب مشترٍ في sandbox من PayPal، ولن يُخصم أي مبلغ حقيقي. ينشئ النقر على الزر على خادمك طلب PayPal بإجمالي السلة (أو بإجمالي الطلب في صفحة Pay for order). ويُحسب المبلغ دائمًا على الخادم، وليس في المتصفح أبدًا.

يوافق العميل على الدفعة في نافذة PayPal باستخدام حساب PayPal أو مصدر تمويل آخر تقدمه PayPal. ثم تعرض صفحة الدفع الرسالة تمت الموافقة على دفعة PayPal. جارٍ إكمال طلبك… وتُرسل الطلب. يقرأ خادمك طلب PayPal ويتحقق من أنه موافَق عليه، وأنه أُنشئ في عملية الدفع هذه، وأنه غير مستخدم في طلب آخر، وأن مبلغه وعملته يطابقان الطلب. وعندها فقط يُحصَّل الدفع (أو يُفوَّض)، وينتقل العميل إلى صفحة استلام الطلب.

إذا تغير إجمالي السلة بعد الموافقة، فلا يُحصَّل أي مبلغ. ويرى العميل الرسالة تغير إجمالي الطلب بعد موافقتك على الدفعة في PayPal. يُرجى النقر على زر PayPal مرة أخرى للموافقة على الإجمالي الجديد. وإذا كان هناك حقل ناقص في الدفع، تُحفظ الموافقة: بعد التصحيح ينقر العميل على Place order لإكمال الدفع. وإذا رفضت PayPal الدفعة، يُطلب من العميل النقر على زر PayPal واختيار طريقة دفع أخرى. وإذا أغلق العميل نافذة PayPal، تعرض صفحة الدفع الرسالة لقد ألغيت دفعة PayPal.

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

تعمل وسيلة الدفع في صفحة الدفع الكلاسيكية، وكتلة Checkout، وصفحة Pay for order. يُحمَّل برنامج PayPal النصي في فضاء أسماء خاص به، فلا يتعارض مع أي إضافة PayPal أخرى في الصفحة. وهي متوافقة مع High-Performance Order Storage (HPOS) في WooCommerce.

لا تتضمن الإضافة webhooks من PayPal، ولا رسائل Pay Later، ولا حقول بطاقات، ولا إعدادات Venmo أو Apple Pay أو Google Pay أو Fastlane، ولا وسائل دفع محفوظة أو اشتراكات، ولا أزرار في صفحات المنتجات أو السلة. ويُستخدم عنوان الشحن الذي أدخله العميل في صفحة الدفع في WooCommerce، وليس عنوانًا من PayPal.

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

Order statuses

Pending payment: أُنشئ الطلب، لكن الدفعة لم تُحصَّل بعد، على سبيل المثال بعد رد غير معروف من PayPal.

Processing: اكتمل التحصيل. تنتقل الطلبات التي تحتوي على منتجات افتراضية قابلة للتنزيل فقط إلى حالة مكتمل، وهي الحالة الافتراضية في WooCommerce. تعرض ملاحظة الطلب المبلغ وطلب PayPal والتحصيل. ومعرّف المعاملة هو معرّف تحصيل PayPal، وهو في شاشة الطلب يرتبط بالدفعة في حساب PayPal الخاص بك (sandbox أو الإنتاج).

On hold: الدفعة مُفوَّضة وتنتظر التحصيل (إجراء الدفع Authorize)؛ أو التحصيل في حالة PENDING لدى PayPal، مثلًا أثناء مراجعة الدفع؛ أو المبلغ أو العملة المدفوعة يختلفان عن الطلب؛ أو تعذرت قراءة الدفعة من رد PayPal. وتوضح ملاحظة الطلب السبب.

Failed: رفضت PayPal التحصيل أو التفويض.

Cancelled: أُلغي التفويض باستخدام Void PayPal authorization.

إجراءات الطلب

افتح الطلب، واختر إجراءً من Order actions، ثم انقر على السهم.

Capture PayPal payment: يحصّل دفعة مُفوَّضة بقيمة إجمالي الطلب. ويضع التحصيل المكتمل الطلب في حالة قيد المعالجة. ويظهر طالما لم يُحصَّل التفويض.

Void PayPal authorization: يحرر الأموال المحجوزة ويلغي الطلب.

Check PayPal payment status: يعيد قراءة تحصيل في حالة PENDING. تضع حالة COMPLETED الطلب في حالة قيد المعالجة، وتضعه حالتا DECLINED أو FAILED في حالة «فشل». ويُبقي التحصيل المكتمل بمبلغ أو عملة مختلفة الطلب في حالة «قيد الانتظار» مع ملاحظة بوجود تعارض.

الاستردادات

افتح الطلب، وانقر على Refund، وأدخل المبلغ، ثم انقر على Refund via PayPal (يعرض الزر عنوان وسيلة الدفع الخاصة بك). تُدعم الاستردادات الكاملة والجزئية. يُرسل الاسترداد إلى بيئة PayPal التي تمت فيها الدفعة (sandbox أو الإنتاج)، لذلك يجب ضبط بيانات اعتماد تلك البيئة. ويُمرَّر السبب إلى PayPal كملاحظة للمشتري. وإذا لم تقبل PayPal الاسترداد، يعرض WooCommerce الخطأ ولا يُسجَّل أي استرداد. ويُضاف الاسترداد الناجح إلى ملاحظات الطلب مع معرّف الاسترداد في PayPal وحالته؛ أما الاسترداد في حالة PENDING فتكمله PayPal لاحقًا.

لا يمكن استرداد الدفعة المُفوَّضة فقط: استخدم Void PayPal authorization بدلًا من ذلك. ولا تُزامن الاستردادات والنزاعات والعكوسات التي تُجرى في حساب PayPal الخاص بك مع WooCommerce.

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

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

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

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

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

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

لا يظهر PayPal في صفحة الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن Client ID وSecret للوضع المحدد مملوءان، وأن عملة المتجر تدعمها PayPal، وأن إجمالي السلة أكبر من صفر. تعرض صفحة الإعدادات تحذيرًا عندما تكون بيانات الاعتماد أو العملة هي المشكلة. كما يخفي الزر أي إضافة للمتصفح تحجب www.paypal.com.

اكتملت الدفعة لكن الطلب بقي في حالة «بانتظار الدفع»: لا تحتوي الإضافة على webhook، لذلك لا تُؤكَّد الدفعة إلا أثناء الدفع. ويحدث هذا عندما لا ترد PayPal أثناء التحصيل. اقرأ ملاحظة الطلب، وتحقق من الدفعة في حساب PayPal الخاص بك، وأكمل الطلب يدويًا، أو اترك العميل يعيد المحاولة: فإعادة المحاولة لا تخصم المبلغ مرتين أبدًا.

PayPal غير متاح حاليًا: بيانات الاعتماد غير صحيحة أو تنتمي إلى الوضع الآخر. انسخ Client ID وSecret للتطبيق الصحيح مرة أخرى.

تعذرت مطابقة موافقة PayPal مع عملية الدفع هذه: لم يُنشأ طلب PayPal في جلسة الدفع هذه، مثلًا بعد انتهاء الجلسة. يعيد العميل النقر على زر PayPal.

الطلب في حالة «قيد الانتظار» بعد الدفع: اقرأ ملاحظة الطلب. تم تفويض الدفعة (حصّلها عبر Capture PayPal payment)، أو التحصيل في حالة PENDING لدى PayPal (استخدم لاحقًا Check PayPal payment status)، أو أن المبلغ أو العملة المدفوعين لم يتطابقا مع الطلب.

يفشل تحصيل تفويض: قد يكون التفويض أقدم من 29 يومًا أو أُلغي مسبقًا. تعرض ملاحظة الطلب خطأ PayPal.

يفشل الاسترداد: ليس للطلب تحصيل في PayPal (تفويض فقط)، أو بيانات اعتماد بيئة الدفعة مفقودة. يمكن للمطورين تغيير قائمة العملات بالفلتر wc_plg_supported_currencies.

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

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

يحتفظ تعطيل الإضافة بكل البيانات. للإزالة، عطّلها واحذفها من صفحة Plugins. يُحذف مفتاح الترخيص وحالة الترخيص لهذه الإضافة دائمًا. أما إعدادات البوابة ورموز وصول PayPal المخزنة مؤقتًا فلا تُحذف إلا إذا كان Delete data on uninstall مفعّلًا. وإلا فستبقى لإعادة التثبيت لاحقًا. تحتفظ الطلبات الحالية بملاحظات الدفع ومعرّفات المعاملات ومعرّفات PayPal.

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