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

المتطلبات

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

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

حساب Braintree: تحتاج إلى Merchant ID وPublic Key وPrivate Key الخاصة بحساب Braintree. تجدها في لوحة تحكم Braintree (بيئة الاختبار: sandbox.braintreegateway.com، بيئة الإنتاج: www.braintreegateway.com) تحت أيقونة الترس، ثم API، ثم API Keys. لحسابات sandbox وlive مفاتيح مختلفة. يجب تفعيل 3-D Secure لحساب التاجر الخاص بك في Braintree، ما لم تضبط 3-D Secure على Disabled. لا حاجة إلى webhook: تُؤكَّد مدفوعات البطاقات فورًا.

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

التثبيت

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

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

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

4. انسخ Merchant ID وPublic Key وPrivate Key من لوحة تحكم Braintree إلى حقول sandbox أو live.

5. فعّل Enable/Disable وانقر على Save. أبقِ Sandbox mode مفعّلًا، ونفّذ طلبًا تجريبيًا ببطاقة اختبار من Braintree sandbox. ثم أوقف Sandbox mode لقبول مدفوعات حقيقية ببيانات الاعتماد الحية.

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

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Braintree Gateway > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة بأكملها. عندما تكون طريقة الدفع مفعّلة لكن Merchant ID أو Public Key أو Private Key للبيئة المحددة غير مُعبّأة، تحذّرك الصفحة بأن طريقة الدفع مخفية في صفحة الدفع إلى أن تُملأ. وأثناء تفعيل وضع sandbox، تعرض الصفحة Sandbox mode is on: test payments, no real money.

Braintree

Enable/Disable: Enable Braintree card payments يفعّل طريقة الدفع أو يعطّلها. الافتراضي: off.

Title: اسم طريقة الدفع الذي يراه العميل في صفحة الدفع. وهو أيضًا اسم طريقة الدفع المحفوظ في الطلب. الافتراضي: Credit / debit card. مطلوب.

Description: النص الذي يظهر أسفل طريقة الدفع في صفحة الدفع. الافتراضي: Pay securely with your credit or debit card via Braintree.

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

سجّل الدخول إلى لوحة تحكم Braintree (sandbox أو live)، وانقر على أيقونة الترس، ثم على API وAPI Keys. تُدرج هناك Public Key وPrivate Key، ويظهر Merchant ID في الصفحة نفسها. تعرض الصفحة حقول بيانات الاعتماد الخاصة بالبيئة المحددة فقط؛ وتبقى المجموعتان محفوظتين.

Sandbox mode: يستخدم بيئة sandbox الخاصة بـ Braintree (مدفوعات تجريبية، دون أموال حقيقية). الافتراضي: on. أوقفه لقبول مدفوعات حقيقية ببيانات الاعتماد الحية. تُنفَّذ الاستردادات والتحصيل والإلغاء دائمًا في البيئة التي دُفع فيها الطلب. وأثناء تفعيله يرى العملاء SANDBOX / TEST MODE — no real money is charged. أسفل طريقة الدفع.

Sandbox Merchant ID وLive Merchant ID: Merchant ID لحساب sandbox أو live.

Sandbox Public Key وLive Public Key: Public Key لذلك الحساب.

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

Sandbox merchant account ID(s) وLive merchant account ID(s): اختياري. تُخصم Braintree بعملة حساب التاجر. اتركه فارغًا لاستخدام حساب التاجر الافتراضي، أو أدخل معرّفًا واحدًا (مثل mystore_EUR) أو معرّفًا لكل عملة: EUR=mystore_EUR، USD=mystore_USD. إذا لم تطابق العملة المخصومة عملة الطلب، يُلغى الإجراء تلقائيًا ولا يُخصم من العميل أي مبلغ.

Clear saved private keys: ضع علامة على Sandbox Private Key أو Live Private Key وانقر على Save لإزالته. يحتفظ الحقل الفارغ بالقيمة المحفوظة.

الدفع

Transaction type: طريقة خصم البطاقة.

3-D Secure: تُلزم المصادقة القوية للعميل 3-D Secure 2 (Strong Customer Authentication) لمعظم مدفوعات البطاقات في المنطقة الاقتصادية الأوروبية والمملكة المتحدة. ويجب تفعيله أيضًا لحسابك في Braintree (تواصل مع دعم Braintree إذا فشلت المدفوعات بخطأ في إعداد 3-D Secure).

تُفحص نتيجة 3-D Secure على الخادم، لا في المتصفح فقط، قبل خصم البطاقة.

متقدم

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

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

Delete data on uninstall: عند التفعيل، يؤدي إلغاء تثبيت الوحدة إلى حذف إعدادات البوابة والسجل. تبقى معاملات Braintree والاستردادات وحالات الطلبات دائمًا، لذلك يمكن استرداد الطلبات المدفوعة سابقًا أو تحصيلها أو إلغاؤها بعد إعادة التثبيت. الافتراضي: off.

صفحة الدفع

في خطوة الدفع، يختار العميل طريقة الدفع (الافتراضية Credit / debit card) ويُدخل البطاقة في نموذج Braintree داخل خيار الدفع. يُحمَّل النموذج من Braintree في صفحة الدفع فقط، ويستخدم لغة المتجر. وعند تفعيل 3-D Secure، يُكمل العميل التحقق لدى بنكه عند تقديم الطلب؛ ويُمرَّر إجمالي السلة والبريد الإلكتروني وعنوان الفوترة إلى هذا التحقق.

ثم تحصّل الوحدة الرمز لمرة واحدة عبر API الخاص بـ Braintree بإجمالي السلة وبعملة السلة، مع استخدام رقم السلة كمعرّف للطلب في Braintree. لا يوجد طلب قبل هذه النقطة. تُقارَن المبالغ المخصومة والعملة مع السلة. يُنشأ الطلب فقط بعد أن تقبل Braintree الدفعة، ويرى العميل صفحة تأكيد الطلب القياسية في PrestaShop.

إذا فشلت الدفعة، فلا يُنشأ أي طلب، ويُسجَّل السبب في سجل الوحدة، ويبقى العميل في خطوة الدفع مع رسالة، على سبيل المثال Your card was declined. Please use another card or contact your bank.، أو 3-D Secure authentication failed. Please try again or use another card.، أو The card security code or billing address could not be verified. Please check your details and try again. ويمكن للعميل المحاولة مرة أخرى فورًا. وإذا لم تطابق العملة أو المبلغ المخصوم السلة، تُلغى المعاملة ويرى العميل This payment could not be processed in the currency of your order. Your card has not been charged. Please choose another payment method or contact us.

لا تُخصم السلة مرتين أبدًا. ويعرض الإرسال الثاني أثناء تنفيذ الدفعة الرسالة This order is already being paid. Please wait a moment and check your e-mail before trying again. وإذا خُصمت البطاقة لكن PrestaShop لم يتمكن من إنشاء الطلب، يرى العميل Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. وتنشئ المحاولة التالية للسلة نفسها الطلب من المعاملة المحفوظة دون خصم جديد.

لا تقبل الوحدة إلا مدفوعات البطاقات. لا تتضمن بطاقات محفوظة أو اشتراكات أو مدفوعات متكررة، ولا PayPal أو Venmo أو Apple Pay أو Google Pay أو طرق الدفع المحلية، ولا تستخدم webhooks من Braintree.

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

حالات الطلب

لا يوجد طلب بعد: لم تُنفَّذ الدفعة أو رُفضت. لا توجد إلا السلة.

Payment accepted: خُصمت البطاقة (Sale)، أو جرى تحصيل تفويض. تُسجَّل الدفعة مع معرّف معاملة Braintree، وتعرض ملاحظة خاصة في رسائل الطلب المبلغ ومعرّف المعاملة ونتيجة 3-D Secure.

Braintree payment authorized: الأموال مفوَّضة فقط (Authorize only). لا تُسجَّل أي دفعة حتى تحصّلها.

Braintree payment on hold: أعادت Braintree حالة معاملة غير متوقعة، أو تعذّر إلغاء خصم بعملة أو مبلغ خاطئ تلقائيًا. وتشرح الملاحظة ما يجب التحقق منه في لوحة تحكم Braintree.

Canceled: أُلغي تفويض.

Refunded: استُردّت الدفعة بالكامل عبر الوحدة.

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

كتلة Braintree payment

تعرض صفحة الطلب كتلة Braintree payment تتضمن معرّف المعاملة (مرتبطًا بالمعاملة في لوحة تحكم Braintree الخاصة ببيئتها)، وحالة المعاملة، والمبلغ وحساب التاجر، ونتيجة 3-D Secure، والمبلغ المحصَّل والمسترد، وشارة Sandbox للمدفوعات التجريبية، وسجل الاستردادات. تحتاج أزرار الكتلة إلى صلاحية تعديل الطلبات؛ ولا تحتاج إلى الوصول إلى صفحات Modules.

التحصيل والإلغاء

للطلب الذي حالته Braintree payment authorized، انقر على Capture Braintree payment لخصم إجمالي الطلب، أو على Void Braintree authorization لتحرير المبلغ المحجوز. يضبط التحصيل الطلب على Payment accepted ويسجّل الدفعة؛ ويضبطه الإلغاء على Canceled. وإذا فشل الإجراء، يظهر الخطأ في الكتلة ويُضاف إلى ملاحظات الطلب.

الاستردادات

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

لا تنشئ الوحدة إشعارات دائنة (credit slips). لا ترسل أزرار الاسترداد القياسية في PrestaShop على صفحة الطلب أي أموال عبر Braintree. ولا تُزامَن النزاعات (chargebacks) وإخفاقات التسوية والاستردادات التي تُجرى في لوحة تحكم Braintree مع PrestaShop.

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

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

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

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

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

لا يظهر Braintree في صفحة الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن البيئة المحددة تحتوي على Merchant ID وPublic Key وPrivate Key. تعرض صفحة الإعدادات تحذيرًا عند غياب أحد المفاتيح. وفي Payment > Preferences، تحقق من أن الوحدة مسموح بها لعملة السلة وبلد العميل ومجموعة العميل.

خُصمت البطاقة لكن لم يُنشأ أي طلب: تُؤكَّد مدفوعات البطاقات فورًا دون webhook. راجع حقل Log في صفحة الوحدة. إذا كان السجل يقول إن رد Braintree قد ضاع، فتحقق في لوحة تحكم Braintree من وجود معاملة يكون فيها رقم السلة معرّف الطلب، قبل قبول دفعة أخرى. وإذا تعذّر إنشاء الطلب بعد الخصم، فإن محاولة الدفع التالية للسلة نفسها تنشئه دون خصم جديد.

يعرض نموذج البطاقة Could not initialize payment form: مفاتيح البيئة المحددة غير صحيحة، أو معرّف حساب التاجر غير موجود في ذلك الحساب. تحقق من المفاتيح ومعرّفات حسابات التاجر، ثم أعد تحميل الصفحة.

يفشل 3-D Secure في كل دفعة: يجب تفعيل 3-D Secure لحساب التاجر الخاص بك في Braintree. تواصل مع دعم Braintree، أو اضبط 3-D Secure على Disabled (غير مستحسن في المنطقة الاقتصادية الأوروبية والمملكة المتحدة، حيث تكون SCA إلزامية).

يُبلَّغ العميل بأن الدفعة تعذّر معالجتها بعملة الطلب: خصمت Braintree بعملة حساب التاجر. أدخل معرّف حساب التاجر لعملة السلة في حقل حساب التاجر للبيئة الحالية.

يرى العميل الرسالة The order total must be greater than zero to pay by card: إجمالي السلة صفر، على سبيل المثال بعد تطبيق قسيمة. لا يمكن دفع مثل هذه الطلبات بالبطاقة.

يفشل الاسترداد الجزئي مباشرة بعد الدفع: لا تسترد Braintree إلا المعاملات المُسوّاة، وعادةً خلال 24 ساعة. استرد المبلغ كاملًا لإلغاء المعاملة الآن، أو نفّذ الاسترداد الجزئي بعد التسوية.

يفشل الاسترداد أو التحصيل أو الإلغاء برسالة تتعلق بالبيئة: تمت الدفعة في بيئة sandbox أو live، ولم تُضبط بيانات الاعتماد الخاصة بتلك البيئة. أدخلها وأعد المحاولة.

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

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

Braintree علامة تجارية مملوكة لصاحبها. هذه الوحدة غير تابعة لـ Braintree ولا معتمدة من قبلها.