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

المتطلبات

WordPress: الإصدار 6.0 أو أحدث.

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

PHP: الإصدار 8.0 أو أحدث.

عملة المتجر: عملة موقع Square الخاص بك: USD أو CAD أو AUD أو JPY أو GBP أو EUR. وبالنسبة للعملات الأخرى تُخفى طريقة الدفع في صفحة الدفع. تدعم Square البائعين في الولايات المتحدة وكندا وأستراليا واليابان والمملكة المتحدة وأيرلندا وفرنسا وإسبانيا.

حساب Square: تحتاج إلى تطبيق في Square Developer Dashboard. منه تنسخ Application ID وAccess Token (صفحة Credentials) وLocation ID (صفحة Locations). قيم Sandbox وProduction منفصلة. لا حاجة إلى webhook: تحصل الإضافة على نتيجة الدفع مباشرة من رد Square.

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

التثبيت

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

2. انقر على Activate.

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

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

5. أبقِ Sandbox Mode مفعّلًا، وأدخل Application ID وAccess Token وLocation ID الخاصة بـ sandbox (راجع الإعدادات). احفظ: تتحقق الإضافة من بيانات الاعتماد مع Square.

6. فعّل Enable/Disable واختبر دفعة باستخدام بطاقات الاختبار من دليل اختبار sandbox الخاص بـ Square. ثم ألغِ تحديد Sandbox Mode، وأدخل بيانات اعتماد الإنتاج، واحفظ مرة أخرى.

الإعدادات

جميع الإعدادات موجودة في صفحة واحدة: WooCommerce > Settings > Payments > Square. وأعلى الحقول تعرض الصفحة، طالما أن وضع sandbox مفعّل، الرسالة Square Gateway is currently in SANDBOX mode. No real charges will be made.. وهي تحذرك عندما يكون Square مفعّلًا لكن Application ID أو Access Token أو Location ID للوضع المحدد مفقود (وعندها تُخفى طريقة الدفع في صفحة الدفع)، وعندما يتعذر على Square معالجة عملة المتجر. وفي قائمة طرق الدفع، يعرض Square شارة Test mode طالما أن وضع sandbox مفعّل.

عند الحفظ، تتحقق الإضافة من بيانات اعتماد الوضع المحدد مع Square. ستظهر لك رسالة خطأ إذا رفضت Square Access Token، أو إذا لم يُعثر على Location ID لهذا الرمز، أو إذا تعذّر التحقق من بيانات الاعتماد، أو إذا كانت عملة الموقع مختلفة عن عملة المتجر. لا يمكن لـ Square الخصم إلا بعملة الموقع: تتذكر الإضافة عملة الموقع الذي تم التحقق منه، وتخفي طريقة الدفع في صفحة الدفع لأي عملة أخرى، وتستمر صفحة الإعدادات في عرض التحذير. كما تحذرك إذا استُخدم Application ID من sandbox في الوضع الفعلي أو العكس.

General

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

Title: عنوان طريقة الدفع الذي يراه العميل أثناء الدفع. الافتراضي: Credit / debit card.

Description: وصف طريقة الدفع الذي يراه العميل أثناء الدفع. الافتراضي: Pay securely with your credit or debit card via Square.

Square account

افتح Square Developer Dashboard، واختر تطبيقك، وانسخ Application ID وAccess token من صفحة Credentials (قيم Sandbox وProduction منفصلة)، وانسخ Location ID من صفحة Locations. يجب أن تطابق عملة الموقع عملة متجرك. تعرض الصفحة حقول بيانات الاعتماد للوضع المحدد فقط: حقول sandbox طالما أن Sandbox Mode مفعّل، وحقول الإنتاج عندما يكون معطلًا.

Sandbox Mode: Enable sandbox (test) mode. تُرسل المدفوعات إلى sandbox الخاص بـ Square ولا يُخصم أي مبلغ حقيقي. استخدم بطاقات الاختبار الخاصة بـ Square. الافتراضي: on.

Sandbox Application ID: معرّف تطبيق Square الخاص بـ sandbox (يبدأ بـ sandbox-sq0idb-).

Sandbox Access Token: رمز الوصول الخاص بـ Square في sandbox.

Sandbox Location ID: معرّف موقع Square في sandbox.

Live Application ID: معرّف تطبيق Square الخاص بالإنتاج (يبدأ بـ sq0idp-).

Live Access Token: رمز الوصول الخاص بـ Square في الإنتاج.

Live Location ID: معرّف موقع Square في الإنتاج.

Advanced

Debug log: Log API requests and responses. تُسجَّل الأخطاء دائمًا. فعّله لتسجيل كل طلب أيضًا، دون بيانات البطاقات أو المفاتيح. تقع السجلات في WooCommerce > Status > Logs، والمصدر wcp_square_gateway. الافتراضي: off.

Delete data on uninstall: Remove all plugin data when the plugin is deleted. يحذف إعدادات البوابة وملفات السجل عند حذف الإضافة. تُحتفظ بيانات دفع الطلبات. الافتراضي: off.

الدفع

يختار العميل طريقة الدفع (افتراضيًا Credit / debit card) ويُدخل بطاقته في نموذج Square الذي يظهر أسفل الوصف. في وضع sandbox تعرض صفحة الدفع إشعار sandbox. وعندما ينقر العميل على Place order، تُرمَّز البطاقة في المتصفح مع التحقق من هوية المشتري (3-D Secure / SCA): يُرسل المبلغ والعملة وجهة اتصال الفوترة إلى Square، وقد يطلب بنك العميل تأكيدًا. ولا يستلم خادمك إلا رمزًا مميزًا لمرة واحدة.

ثم تخصم الإضافة الرمز المميز عبر Square Payments API بإجمالي الطلب بعملة الطلب، مع معرّف الطلب كمرجع، وملاحظة Order # تتضمن رقم الطلب واسم موقعك، إضافةً إلى البريد الإلكتروني للفوترة. تُحصَّل الدفعة فورًا. ولا يُعلَّم الطلب كمدفوع إلا بعد تأكيد Square: يجب أن يُظهر رد Square دفعة بحالة COMPLETED تطابق تمامًا إجمالي الطلب والعملة ومعرّف الطلب والموقع. بعد ذلك ينتقل العميل إلى صفحة استلام الطلب. وإذا لم تكن الدفعة COMPLETED أو اختلفت أي قيمة، يوضع الطلب قيد الانتظار مع ملاحظة، ومع ذلك ينتقل العميل إلى صفحة استلام الطلب.

لا تُنفَّذ سوى محاولة دفع واحدة لكل طلب في الوقت نفسه. إذا نقر العميل مرتين أو دفع من تبويبين، فستعرض المحاولة الثانية الرسالة This order is already being paid. Please wait a moment and check your e-mail before trying again. (هذا الطلب يُدفع بالفعل. يُرجى الانتظار لحظة والتحقق من بريدك الإلكتروني قبل إعادة المحاولة.). الطلبات idempotent: الطلب نفسه والرمز نفسه والمبلغ نفسه لا يُنشئون دفعة ثانية أبدًا.

إذا لم يرد Square (مشكلة في الشبكة، أو انتهاء المهلة، أو خطأ في الخادم)، يُعاد الطلب مرة واحدة بمفتاح idempotency نفسه. وإذا استمر غياب الرد، يرى العميل الرسالة We could not get a confirmation from the payment provider. Please wait a minute and try again — if your card was already charged, the payment will be recognised and you will not be charged twice. (تعذّر الحصول على تأكيد من مزود الدفع. يُرجى الانتظار دقيقة ثم المحاولة مرة أخرى. وإذا كانت بطاقتك قد خُصم منها المبلغ بالفعل، فسيُتعرَّف على الدفعة ولن يُخصم منك مرتين.). وتطلب ملاحظة الطلب منك التحقق من Square Dashboard. وفي المحاولة التالية، تبحث الإضافة أولًا في Square عن الدفعة السابقة لهذا الطلب وتُكمل الطلب بها، بدلًا من خصم البطاقة مرة أخرى.

عندما يرفض البنك البطاقة، يرى العميل رسالة قصيرة بحسب رمز الخطأ من Square، مثل Your card was declined. Please use another card or payment method.، أو The card security code (CVV) is incorrect. Please check it and try again.، أو Your bank requires additional verification (3-D Secure). Please enter your card again and complete the verification.. وتُسجَّل الأسباب التقنية في ملاحظات الطلب وفي السجل. ويمكن للعميل المحاولة مرة أخرى ببطاقة أخرى، ولاحقًا أيضًا من صفحة Pay for order.

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

تقبل الإضافة مدفوعات البطاقات فقط، وتُحصَّل فورًا. لا تتضمن بطاقات محفوظة أو ملفات تعريف للعملاء، ولا WooCommerce Subscriptions أو Pre-Orders، ولا Apple Pay أو Google Pay أو Cash App Pay أو Afterpay أو ACH أو بطاقات هدايا Square، ولا المدفوعات بالتفويض فقط، ولا webhooks من Square، ولا مزامنة للمنتجات أو المخزون مع Square. وتُدار النزاعات في Square Dashboard.

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

حالات الطلب

Pending payment: أُنشئ الطلب ولم يُدفع بعد، مثلًا بعد رفض البطاقة أو فقدان رد Square.

Processing: أكّد Square دفعة COMPLETED بإجمالي الطلب. وهذه هي الحالة القياسية لـ WooCommerce بعد الدفع (تصبح الطلبات التي تحتوي على منتجات افتراضية قابلة للتنزيل فقط «مكتملة»). تعرض ملاحظة الطلب معرّف دفعة Square، وعلامة البطاقة مع آخر 4 أرقام، والوضع (sandbox أو الإنتاج). معرّف المعاملة هو معرّف دفعة Square، وعلى شاشة الطلب يرتبط بالدفعة في Square Dashboard.

On hold: ردّ Square بدفعة ليست COMPLETED، أو بمبلغ أو عملة أو مرجع أو موقع مختلف. تعرض الملاحظة Square payment needs review معرّف الدفعة والحالة والمبالغ. تحقق من التحصيل والمبلغ والعملة في Square Dashboard قبل تنفيذ الطلب.

تحفظ الإضافة في الطلب معرّف دفعة Square وعلامة البطاقة وآخر 4 أرقام، والبيئة والموقع. لا تُخزَّن أرقام البطاقات أبدًا.

الاستردادات

افتح الطلب، وانقر على Refund، وأدخل المبلغ، ثم انقر على Refund via Credit / debit card (يعرض الزر Title الخاص بك). الاسترداد الكامل والجزئي مدعومان. يُرسل الاسترداد إلى البيئة (sandbox أو الإنتاج) والموقع اللذين تمت فيهما الدفعة، لذلك يجب ضبط Access Token لذلك الوضع. وطلبات الاسترداد idempotent، وتُعاد مرة واحدة إذا لم يرد Square. ويُضاف الاسترداد الذي يقبله Square (الحالة PENDING أو COMPLETED) إلى ملاحظات الطلب مع معرّف استرداد Square. وإذا رفضه Square، يعرض WooCommerce الخطأ ولا يُسجَّل أي استرداد.

يُكمل Square الاستردادات من جهته. والاسترداد الذي يرفضه Square لاحقًا لا يُبلَّغ به WooCommerce، والاستردادات التي تتم في Square Dashboard لا تظهر في WooCommerce.

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

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

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

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

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

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

لا يظهر Square في صفحة الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن Application ID وAccess Token وLocation ID للوضع الحالي معبّأة. تحقق من أن عملة المتجر (أو عملة الطلب في صفحة Pay for order) هي USD أو CAD أو AUD أو JPY أو GBP أو EUR، وأنها تطابق عملة موقع Square الخاص بك. تعرض صفحة الإعدادات تحذيرًا لكل مشكلة من هذه المشكلات.

لا يُحمَّل نموذج البطاقة: يرى العميل الرسالة The card form could not be loaded. Please reload the page or choose another payment method. (تعذّر تحميل نموذج البطاقة. يُرجى إعادة تحميل الصفحة أو اختيار طريقة دفع أخرى.). تحقق من أن Application ID وLocation ID تنتميان إلى الوضع المحدد (معرّفات sandbox تبدأ بـ sandbox-). وإذا نقر العميل مبكرًا جدًا، تظهر الرسالة The card form is still loading. Please wait a moment and try again. (نموذج البطاقة ما زال قيد التحميل. يُرجى الانتظار لحظة ثم المحاولة مرة أخرى.).

تُرفض المدفوعات رغم أن البطاقة سليمة: يجب أن تطابق عملة الموقع عملة المتجر. احفظ الإعدادات لرؤية نتيجة التحقق من بيانات الاعتماد؛ وبعد التحقق الناجح تُخفى طريقة الدفع للعملات الأخرى.

رفض Square رمز Access Token للوضع المحدد: الرمز يتبع الوضع الآخر أو أنه غير صحيح. انسخه مرة أخرى من صفحة Credentials لتطبيقك وتحقق من Sandbox Mode.

لم يُعثر على Location ID لهذا Access Token: انسخ Location ID من صفحة Locations للتطبيق نفسه والوضع نفسه.

رأى العميل الرسالة «We could not get a confirmation from the payment provider»: لم يرد Square. اقرأ ملاحظة الطلب وتحقق من دفعات هذا الموقع في Square Dashboard (المرجع = معرّف الطلب). وإذا حاول العميل مرة أخرى، تبحث الإضافة أولًا عن الدفعة السابقة وتُكمل الطلب بها، بدلًا من إعادة الخصم.

الطلب في حالة On hold: اقرأ الملاحظة Square payment needs review. لم تكن الدفعة COMPLETED، أو اختلف مبلغها أو عملتها أو موقعها عن الطلب. تحقق منها في Square Dashboard، ثم نفّذ الطلب أو استرد الدفعة.

يفشل الاسترداد برسالة تتعلق بالوضع: تمت الدفعة في وضع sandbox أو الوضع الفعلي، ولم يُضبط Access Token لذلك الوضع. أدخله وحاول مرة أخرى.

أخطاء أخرى: فعّل Debug log وراجع WooCommerce > Status > Logs، المصدر wcp_square_gateway.

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

الإزالة

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

Square علامة تجارية مسجلة لمالكها. هذه الإضافة غير تابعة لـ Square ولا معتمدة من قِبلها.