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

المتطلبات

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

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

حساب 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. في الواجهة الخلفية، انتقل إلى Modules > Module Manager وانقر على Upload a module. اختر ملف ZIP الخاص بالوحدة.

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

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

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

5. أدخل بيانات اعتماد الوضع الذي تستخدمه، واختر Capture أو Authorize، وفعّل Enable/Disable، ثم انقر على Save.

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

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

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox PayPal Gateway > Configure. لكل قسم زر Save الخاص به، وهو يحفظ الصفحة كاملة. فوق الحقول، تحذرك الصفحة عندما تكون وسيلة الدفع مفعّلة لكن Client ID أو Secret للوضع المحدد فارغ، وعندما لا تدعم PayPal العملة الافتراضية للمتجر. وفي الحالتين تُخفى وسيلة الدفع في صفحة الدفع. وعند تفعيل وضع sandbox تعرض الصفحة الرسالة Sandbox mode is on: payments go to the PayPal sandbox, no real money is moved. يؤدي حفظ الإعدادات إلى حذف رموز الوصول المخزنة مؤقتًا لـ PayPal، لذلك تُستخدم بيانات الاعتماد الجديدة فورًا.

General

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

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: تُرسل المدفوعات إلى PayPal sandbox باستخدام بيانات اعتماد sandbox؛ ولا تُنقل أي أموال حقيقية. الافتراضي: مفعّل. عطّله لقبول المدفوعات الحقيقية. تستخدم التحصيلات والإلغاءات والاستردادات دائمًا البيئة التي دُفع فيها الطلب. وعند تفعيله يرى العملاء أسفل وسيلة الدفع الرسالة Sandbox mode: pay with a PayPal sandbox buyer account — no real money is charged.

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 الخاص بالإنتاج.

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

Clear saved secrets: حدد سرًّا وانقر على Save لحذفه. الحقل الفارغ يُبقي القيمة المحفوظة.

الدفع

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

متقدم

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

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

Delete data on uninstall: عند التفعيل، يؤدي إلغاء تثبيت الوحدة إلى حذف إعدادات البوابة والرموز المخزنة مؤقتًا والسجل. تبقى بيانات الدفع للطلبات (معرّفات PayPal للطلبات، والاستردادات) وحالات الطلبات محفوظة دائمًا. الافتراضي: معطّل.

صفحة الدفع

في خطوة الدفع يختار العميل وسيلة الدفع (افتراضيًا PayPal)، ويظهر زر PayPal بدلًا من نموذج الدفع. وعند النقر على الزر ينشئ خادمك طلب PayPal بإجمالي السلة بعملة السلة. يُحسب المبلغ دائمًا على الخادم، وليس في المتصفح. لا يوجد طلب بعد في هذه المرحلة.

يوافق العميل على الدفعة في نافذة PayPal باستخدام حساب PayPal أو مصدر تمويل آخر تقدمه PayPal. ثم تعرض صفحة الدفع الرسالة PayPal payment approved. Completing your order… وتنشئ الطلب. إذا لم تُقبل شروط الخدمة بعد، تعرض صفحة الدفع الرسالة PayPal payment approved. Click "Place order" to complete it. وإذا نقر العميل على Place order دون الموافقة على دفعة، تكون الرسالة Please click the PayPal button and approve the payment first.

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

إذا تغير إجمالي السلة بعد الموافقة، فلا يُحصَّل أي مبلغ. يرى العميل الرسالة The order total changed after you approved the payment in PayPal. Please click the PayPal button again to approve the new total. وإذا رفضت PayPal الدفعة، يعود العميل إلى خطوة الدفع ويُطلب منه النقر على زر PayPal واختيار طريقة دفع أخرى. لا يُنشأ أي طلب. وإذا أغلق العميل نافذة PayPal، تعرض صفحة الدفع You cancelled the PayPal payment.

إذا لم ترد PayPal أثناء التحصيل، يرى العميل We could not confirm your PayPal payment yet. Please try again in a moment — you will not be charged twice. وتبقى الموافقة محفوظة، حتى بعد إعادة تحميل الصفحة، ويعيد Place order استخدامها. وإذا كانت PayPal قد أكملت المحاولة السابقة، فإن تلك الدفعة هي المستخدمة ولا تُحصَّل موافقة جديدة. وإذا تم خصم الدفعة ولم يتمكن النظام من إنشاء الطلب، يرى العميل الرسالة Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. وتنشئ المحاولة التالية الطلب من الدفعة المحفوظة دون خصم جديد.

يُحمَّل نص PayPal البرمجي في صفحة الدفع فقط، وضمن مساحة أسماء خاصة به، حتى لا يتعارض مع وحدة PayPal أخرى في الصفحة. تعمل الوحدة مع القالبين Classic وHummingbird.

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

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

حالات الطلب

No order yet: لم يوافق العميل على الدفعة، أو رفضتها PayPal. لا توجد سوى السلة.

Payment accepted: اكتمل التحصيل. لا يُعلَّم الطلب مدفوعًا إلا بعد تأكيد PayPal. تُسجَّل الدفعة بمعرّف تحصيل PayPal كمعرّف للمعاملة، وتعرض ملاحظة المبلغ وطلب PayPal والتحصيل.

PayPal payment authorized: الدفعة مفوَّضة وتنتظر التحصيل (إجراء الدفع Authorize).

Awaiting PayPal payment: التحصيل في حالة PENDING لدى PayPal، مثلًا أثناء مراجعة الدفعة.

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

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

Payment error: رُفض تحصيل معلّق أو فشل.

Refunded: استُرد المبلغ بالكامل من خلال الوحدة.

إذا وصلت دفعة ثانية لسلة لها طلب بالفعل، فلا يتغير الطلب. وتطلب منك ملاحظة التحقق من ذلك في حساب PayPal الخاص بك، ثم استرداده.

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

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

الاستردادات

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

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

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

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

بدون مفتاح نشط لا تُعرض PayPal للعملاء في صفحة الدفع. وإذا بدأت دفعة على أي حال، يرفض المتجر إنشاء طلب PayPal، ويرى العميل الرسالة An error occurred during PayPal checkout. Please try again. واجهة متجر PrestaShop لا تعرف أنك مسجل الدخول إلى الواجهة الخلفية، لذلك تُخفى طريقة الدفع عنك أيضًا: يمكنك إعداد الوحدة قبل شراء مفتاح، لكن لا يمكنك اختبارها في الدفع. يظهر تذكير في Modules > Module Manager على تبويب Alerts. الطلبات الحالية لا تتأثر: تستمر الاستردادات وإجراءات كتلة PayPal في العمل.

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

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

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

The payment went through, but no order was created: لا تملك الوحدة webhook، لذلك لا تُؤكَّد الدفعة إلا أثناء الدفع. ويحدث ذلك عندما لا ترد PayPal أثناء التحصيل، أو عندما يتعذر إنشاء الطلب. فعّل Debug log وراجع حقل Log، وتحقّق من الدفعة في حساب PayPal الخاص بك، أو دع العميل يحاول مرة أخرى: إعادة المحاولة لا تخصم مرتين أبدًا، وتُنشئ الطلب من الدفعة المحفوظة.

PayPal could not be loaded: لم يُحمَّل نص PayPal البرمجي في المتصفح، مثلًا بسبب أداة حجب أو مشكلة في الشبكة.

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

Your PayPal approval could not be matched to this checkout: لم يُنشأ طلب PayPal لهذه السلة، مثلًا بعد انتهاء الجلسة. يعيد العميل النقر على زر PayPal.

This payment is already being processed: أُرسلت السلة نفسها مرتين في اللحظة نفسها. ينتظر العميل لحظة ويتحقق من البريد الإلكتروني قبل المحاولة مرة أخرى.

The order is on hold after payment: اقرأ الملاحظات في كتلة PayPal payment. إما أن الدفعة مفوَّضة (حصّلها باستخدام Capture PayPal payment)، أو أن التحصيل في حالة PENDING لدى PayPal (استخدم Check PayPal payment status لاحقًا)، أو أن المبلغ المدفوع أو العملة لم يتطابقا مع الطلب (أنجز الطلب أو استرد ما دُفع).

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

Refund fails: لا يملك الطلب تحصيلًا لدى PayPal (تفويض فقط)، أو المبلغ يتجاوز ما تبقّى للاسترداد، أو بيانات اعتماد البيئة التي دُفع فيها المبلغ غير موجودة. تحدد الكتلة السبب.

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

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

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