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

المتطلبات

WordPress: 6.0 أو أحدث.

WooCommerce: 8.0 أو أحدث، مثبت ومفعّل.

PHP: 8.0 أو أحدث.

HTTPS: يُستحسن أن يعمل موقعك عبر HTTPS.

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

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

التثبيت

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

2. انقر Activate.

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

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

5. انسخ Merchant ID وPublic Key وPrivate Key من لوحة تحكم Braintree إلى حقول بيئة الاختبار (sandbox) أو الإنتاج.

6. فعّل Enable/Disable. أبقِ Sandbox mode مفعّلًا، وأجرِ طلبًا تجريبيًا ببطاقة اختبار من Braintree، مثل 4111 1111 1111 1111 بأي تاريخ انتهاء مستقبلي. ولاختبار 3-D Secure استخدم بطاقات اختبار 3-D Secure الخاصة بـ Braintree.

7. ألغِ تحديد Sandbox mode لاستقبال مدفوعات حقيقية ببيانات اعتماد الإنتاج.

الإعدادات

جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > Braintree. إذا كانت البوابة مفعّلة لكن Merchant ID أو Public Key أو Private Key للوضع المختار ناقصة، تحذّرك الصفحة بأن طريقة الدفع مخفية عند الدفع حتى تُملأ هذه الحقول. وتعرض الصفحة حقول بيانات الاعتماد للوضع المختار فقط، وتبقى المجموعتان محفوظتين معًا.

عام

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

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

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

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

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

Sandbox mode: Use the Braintree sandbox (test payments, no real money). الافتراضي: مفعّل. ألغِ تحديده لاستقبال مدفوعات حقيقية ببيانات اعتماد الإنتاج. تُنفَّذ الاستردادات والتحصيل والإلغاء دائمًا في البيئة التي دُفع فيها الطلب.

Sandbox Merchant ID وLive Merchant ID: Merchant ID الخاص بحساب بيئة الاختبار أو الإنتاج.

Sandbox Public Key وLive Public Key: المفتاح العام لذلك الحساب.

Sandbox Private Key وLive Private Key: المفتاح الخاص لذلك الحساب.

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

الدفع

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

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

متقدم

Debug log: Also log API calls and payment steps (errors are always logged). تُكتب السجلات في WooCommerce > Status > Logs، والمصدر wcp_braintree_gateway. ولا تتضمن السجلات أبدًا مفاتيح API ولا بيانات البطاقة أو العميل. الافتراضي: إيقاف.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. الافتراضي: إيقاف.

صفحة الدفع

يختار العميل طريقة الدفع (افتراضيًا Credit / debit card) ويُدخل البطاقة في نموذج Braintree في صفحة الدفع. في بيئة الاختبار (sandbox) يعرض النموذج SANDBOX / TEST MODE — no real money is charged. وعند تفعيل 3-D Secure يُكمل العميل التحقق لدى البنك عند تقديم الطلب.

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

إذا فشل الدفع يبقى الطلب «بانتظار الدفع»، ويُضاف السبب إلى ملاحظات الطلب، ويرى العميل رسالة واضحة، مثل 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.

تعمل طريقة الدفع في صفحة الدفع الكلاسيكية، وفي كتلة Checkout، وفي صفحة Pay for order. وهي متوافقة مع WooCommerce High-Performance Order Storage (HPOS).

تقبل الإضافة مدفوعات البطاقات فقط. لا تتضمن البطاقات المحفوظة (vaulting)، ولا اشتراكات WooCommerce Subscriptions أو الطلبات المسبقة، ولا PayPal أو Venmo أو Apple Pay أو Google Pay أو ACH أو طرق الدفع المحلية، ولا webhooks من Braintree، ولا بيانات Level 2/3، ولا بنود الطلب، ولا Fastlane.

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

حالات الطلب

Pending payment: لم يُدفع المبلغ بعد، أو رُفض الدفع.

Processing or Completed: خُصم المبلغ (Sale)، أو تم تحصيل تفويض. تضبط WooCommerce الحالة «قيد التنفيذ»، أو «مكتمل» للطلبات التي تحتوي على منتجات افتراضية قابلة للتنزيل فقط. تعرض ملاحظة الطلب المبلغ، ومعرّف المعاملة، ونتيجة 3-D Secure. ومعرّف المعاملة هو معرّف معاملة Braintree، وهو على شاشة الطلب رابط إلى المعاملة في لوحة تحكم Braintree.

On hold: المبلغ مُفوَّض فقط (Authorize only). ويُوضع الطلب في «في الانتظار» أيضًا عندما تُرجع Braintree حالة معاملة غير متوقعة، أو عندما يتعذر إلغاء خصم بعملة خاطئة تلقائيًا. وتشرح ملاحظة الطلب ما يجب التحقق منه في لوحة تحكم Braintree.

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

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

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

الاستردادات

افتح الطلب، وانقر Refund، وأدخل المبلغ، ثم انقر Refund via Credit / debit card (يستخدم الزر عنوان طريقة الدفع لديك). يُدعم الاسترداد الكامل والجزئي. لا يمكن لـ Braintree استرداد إلا المعاملات المُسوّاة، وتُسوّى عادةً خلال 24 ساعة. وقبل التسوية يُنفَّذ الاسترداد الكامل كإلغاء (void)، ويفشل الاسترداد الجزئي حينها برسالة تطلب الانتظار حتى التسوية. يُرسل الاسترداد إلى البيئة (بيئة الاختبار أو الإنتاج) التي دُفع فيها الطلب. وإذا لم تقبل Braintree الاسترداد، تعرض WooCommerce الخطأ ولا يُسجَّل أي استرداد. وتُضاف عملية الاسترداد أو الإلغاء الناجحة إلى ملاحظات الطلب.

لا تُزامَن النزاعات (chargebacks) ولا إخفاقات التسوية مع WooCommerce. تحقق منها في لوحة تحكم Braintree.

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

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

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

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

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

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

Braintree لا يظهر في صفحة الدفع: تحقق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن الوضع المختار لديه Merchant ID وPublic Key وPrivate Key. تعرض صفحة الإعدادات تحذيرًا عند نقص أي منها.

تم الدفع لكن الطلب ما زال Pending payment: تُؤكَّد مدفوعات البطاقات فورًا دون webhook. وإذا ذكرت ملاحظة الطلب أن رد Braintree قد فُقد، فتحقق في لوحة تحكم Braintree من وجود معاملة بهذا الرقم قبل قبول دفعة أخرى. فعّل Debug log وراجع WooCommerce > Status > Logs، والمصدر wcp_braintree_gateway.

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

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

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

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

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

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

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

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