بوابة Square Terminal

تتيح لك بوابة Square Terminal تحصيل مدفوعات طلبات WooCommerce على أجهزة Square Terminal مباشرةً من WCPOS. يُطلب الدفع من WooCommerce ويُتَمّ على جهاز Square Terminal مقترن، ثم تُسجَّل النتيجة في الطلب.

الميزات

تكامل الأجهزة

إرسال المدفوعات إلى أجهزة Square Terminal المقترنة وتحصيل المدفوعات بالبطاقة الحضورية

اتصال بنقرة واحدة

التفويض مع Square مباشرةً — دون إنشاء رمز وصول أو لصقه

إتمام موثوق

تُؤكَّد المدفوعات بالاستعلام الدوري وبمُصفٍّ يعمل في الخلفية، مع webhooks لتسريع ذلك

معاملات آمنة

معالجة دفع متوافقة مع PCI عبر البطاقات الحاضرة تتم على أجهزة Square

بيئة الاختبار والإنتاج

تحقق من الإعدادات في بيئة Square Sandbox قبل التبديل إلى المدفوعات الفعلية

آلية العمل

على عكس بوابات الدفع المعتمدة على SDK في المتصفح، يستخدم Square Terminal واجهة Terminal API من جانب الخادم الخاصة بـ Square. عند بدء عملية دفع، ينشئ WooCommerce عملية Terminal Checkout للطلب ويدفعها Square إلى الجهاز المقترن. يدفع العميل عبر الجهاز الطرفي، ثم تُسجَّل النتيجة في الطلب.

كيف يُؤكَّد الدفع. تستعلم نقطة البيع من Square أثناء تنفيذ الدفع، ويسوّي مُصفٍّ يعمل في الخلفية أي شيء يفوت الاستعلام — مثل علامة تبويب متصفح أُغلقت. أما webhooks الخاصة بـ Square فهي إضافة اختيارية تُقصّر مدة الانتظار؛ وهي ليست مطلوبة، ولا يفقد موقع بلا webhooks أي عملية دفع.

يجب أن يكون جهاز Square Terminal متصلاً بالإنترنت ومسجّلاً الدخول بنفس حساب Square ونفس الموقع المستخدمَين في الإضافة.

الإعداد

1

تثبيت Square Terminal for WooCommerce

ثبّت الإضافة من WP Admin > POS > Settings > Extensions، أو حمّل أحدث ملف zip للإضافة (وليس ملف zip أو tarball الخاص بالشيفرة المصدرية من GitHub) من صفحة الإصدارات على GitHub وارفعه عبر Plugins > Add New > Upload Plugin.

2

الاتصال بـ Square

1. انتقل إلى WP Admin > WooCommerce > Settings > Payments وافتح Square Terminal
2. ضمن حساب Square، اختر البيئة — Sandbox للاختبار، وProduction للمدفوعات الفعلية
3. انقر الاتصال بـ Square ووافق على الأذونات التي يعرضها Square
4. اختر معرّف الموقع — موقع Square الذي يحصّل الجهاز الطرفي المدفوعات لحسابه

اختر البيئة قبل الاتصال. فالاتصال الواحد يغطي بيئة واحدة فقط؛ ولا يمكن لاتصال Sandbox أن يفوّض مدفوعات الإنتاج أبدًا.

أتستخدم بالفعل إضافة WooCommerce Square الرسمية؟

تُملأ البيئة ومعرّف الموقع مسبقًا من إعداداتها. ولا تُقرأ سوى هاتين القيمتين — فلا تُشارَك أي بيانات اعتماد بين الإضافتين، ولا يزال عليك الاتصال أو تقديم رمز وصول هنا.

أتفضّل استخدام رمز الوصول الخاص بك؟

افتح الإعدادات المتقدمة والصق رمز وصول للبيئة المحددة بدلًا من الاتصال. وكل ما عدا ذلك يعمل بالطريقة نفسها.

3

اقتران جهاز Square Terminal

ضمن Terminal:

1. انقر إنشاء رمز جهاز — يظهر رمز اقتران
2. على جهاز Square Terminal، افتح شاشة تسجيل الدخول برمز الجهاز وأدخل الرمز. وإذا كان الجهاز مسجّل الدخول حاليًا في Square POS أو في تكامل آخر، فسجّل الخروج من ذلك أولًا — إذ لا يمكن الوصول إلى شاشة رمز الجهاز أثناء استخدامه في مكان آخر.
3. انقر البحث عن القارئات للتأكد من ظهوره الآن ضمن مقترن بهذه الإضافة

القائمة الفارغة قبل الاقتران أمر متوقّع وليس عطلًا. فواجهة الأجهزة لدى Square لا تُبلّغ إلا عن الأجهزة الطرفية التي أُعدّت لاستخدام Terminal API — ولا يظهر جهاز طرفي يعمل بـ Square POS إطلاقًا حتى يُدخَل فيه رمز جهاز.

4

التفعيل في WCPOS

1. انتقل إلى WP Admin > POS > Settings > Checkout
2. ابحث عن بوابة Square Terminal وفعّلها لنقطة البيع
3. احفظ إعداداتك

ملاحظة

لا يتحكم مربع تفعيل/تعطيل في شاشة إعدادات WooCommerce إلا في دفع المتجر الإلكتروني. أما WCPOS فيستخدم هذه البوابة تلقائيًا بمجرد إعدادها، سواء أكان ذلك المربع محددًا أم لا.

اقتران جهاز طرفي

يجب اقتران جهاز Square Terminal بـهذه الإضافة قبل أن يتمكن أمين الصندوق من اختياره. ويُنشئ الاقتران رمز جهاز عبر Terminal API، وهو السبيل الوحيد الذي يمكن للإضافة من خلاله مخاطبة الجهاز.

ضمن Terminal في شاشة الإعدادات:

• إنشاء رمز جهاز — يولّد رمزًا يُدخَل في الجهاز الطرفي. وهو قصير الأجل؛ فولّد رمزًا جديدًا إذا انتهت صلاحيته.
• البحث عن القارئات — يسرد ما يستطيع Square رؤيته، في مجموعتين:
  • مقترن بهذه الإضافة — قابل للاختيار عند الدفع
  • أجهزة أخرى يستطيع Square رؤيتها في هذا الموقع — أُعدّت بواسطة تطبيق آخر، فلا يمكن اختيارها هنا حتى تُقترن بهذه الإضافة
• التحقق من الإعدادات — يفحص بيانات الاعتماد والموقع لدى Square

لماذا قد لا يكون جهاز طرفي تملكه قابلًا للاختيار

رموز الأجهزة تعود إلى التطبيق الذي أنشأها، لذا يظهر جهاز طرفي أعدّه تكامل آخر عبر Terminal API ضمن أجهزة أخرى يستطيع Square رؤيتها لكن لا يمكن اختياره هنا. ولا يظهر جهاز طرفي يعمل بـ Square POS إطلاقًا.

وفي كلتا الحالتين الحل واحد: سجّل خروج الجهاز الطرفي مما هو مقترن به حاليًا، ثم أدخل رمزًا جديدًا من إنشاء رمز جهاز هنا.

Webhooks

إن webhooks اختيارية. فهي تُقصّر المدة التي يستغرقها تأكيد الدفع. أما الاستعلام الدوري والمُصفّي العامل في الخلفية فيؤكدان كل عملية دفع على أي حال، لذا يظل الموقع الذي لا يشترك في webhook يعمل بشكل صحيح — لكن بتسوية أبطأ قليلًا.

غير متاح إذا استخدمت «الاتصال بـ Square»

اشتراك webhook يعود إلى تطبيق لدى Square، وإضافته تتطلب الوصول إلى ذلك التطبيق في لوحة مطوري Square. فإذا اتصلت عبر الاتصال بـ Square فأنت تفوّض تطبيق WCPOS لا تطبيقًا خاصًا بك، ومن ثم لا توجد لوحة تضيف فيها اشتراكًا ولا مفتاح توقيع تنسخه.

ومع ذلك تُؤكَّد المدفوعات بشكل طبيعي — عبر الاستعلام الدوري والمُصفّي. ولا تنطبق الخطوات أدناه إلا إذا أعددت الإضافة بـرمز الوصول الخاص بك ضمن الإعدادات المتقدمة.

لإضافة واحد باستخدام تطبيق Square الخاص بك:

1. في شاشة الإعدادات، ضمن Terminal → Webhooks، انقر نسخ لنسخ عنوان URL الخاص بـ webhook
2. في لوحة مطوري Square، افتح تطبيقك وانتقل إلى Webhooks
3. أضف اشتراكًا لحدث terminal.checkout.updated، مع لصق ذلك العنوان بوصفه عنوان URL للإشعارات
4. انسخ مفتاح توقيع Webhook من Square إلى الإعدادات المتقدمة في الإضافة

عندها يُبلّغ صف Webhooks عمّا إذا كان قد وصل webhook مُتحقَّق من توقيعه، ومتى.

يجب أن يتطابق العنوان تمامًا

يوقّع Square كل webhook على عنوان الإشعار الذي أُعطي له. فإذا اختلف العنوان في Square عن عنوان الإضافة ولو بحرف واحد، فشل التحقق من كل عملية تسليم. استخدم زر نسخ بدلًا من كتابته.

لماذا هذه الخطوة يدوية

واجهة Webhook Subscriptions API لدى Square محدَّدة النطاق بـالتطبيق، لا بالبائعين الأفراد، ولا يمكن استدعاؤها برمز وصول بائع. لذا لا تستطيع الإضافة إنشاء الاشتراك نيابةً عنك.

إذا توقف التحقق من webhooks

يعرض صف Webhooks عبارة لم يُتحقَّق منه بعد عندما لا يصل أي webhook ويُتحقَّق منه وفق الإعدادات الحالية. فإذا كانت المدفوعات قد جرت بالفعل، فتحقق بهذا الترتيب:

1. تطابُق مفتاح توقيع Webhook في الإعدادات المتقدمة مع المفتاح في Square
2. تطابُق عنوان URL للإشعارات في Square مع العنوان المعروض في الإضافة تمامًا
3. الاشتراك في حدث terminal.checkout.updated
4. إمكانية الوصول إلى موقعك علنًا عبر HTTPS — تحقق من محاولات التسليم في لوحة Square

يؤدي تغيير البيئة أو عنوان webhook أو مفتاح التوقيع إلى إعادة تعيين هذا الصف حتى وصول webhook التالي. وهذا مقصود: فعملية تسليم تم التحقق منها وفق الإعدادات القديمة لا تقول شيئًا عن الإعدادات الجديدة.

مرجع الإعدادات

شاشة الإعدادات مرتَّبة بالترتيب الذي يجري به الإعداد.

القسم	يحتوي على
حساب Square	البيئة، والاتصال بـ Square، ومعرّف الموقع
Terminal	عناصر التحكم في الاقتران، وقائمة القارئات، وحالة webhook
سلوك الدفع	تخطي شاشة الإيصال، وتحصيل التوقيع، وسجلات التصحيح
الإعدادات المتقدمة	رموز الوصول، ومفتاح توقيع webhook، وتجاوز عنوان webhook

الإعدادات المتقدمة مطوية افتراضيًا. وهي تحتوي على رموز الوصول اليدوية — اللازمة فقط إذا لم تكن تستخدم الاتصال — وعلى مفتاح توقيع webhook. أما تجاوز عنوان webhook فينبغي أن يبقى فارغًا ما لم يكن عنوانك العلني مختلفًا عن العنوان الذي تشتقه الإضافة، مثلًا خلف وكيل أو نطاق مخصص.

الاستخدام

معالجة المدفوعات

1. إضافة العناصر: أضف المنتجات إلى سلتك في نقطة البيع
2. اختيار البوابة: اختر "Square Terminal" طريقةً للدفع
3. اختيار الجهاز: اختر الجهاز الطرفي المقترن من قائمة جهاز Terminal
4. بدء الدفع: انقر بدء الدفع — عندها يدفع Square عملية الدفع إلى الجهاز
5. دفع العميل: يمرر العميل بطاقته أو يُدخلها أو يلمس بها جهاز Square Terminal
6. الإتمام: تُحدَّث الحالة مباشرةً أثناء الانتظار، ويُعلَّم الطلب مدفوعًا بمجرد تأكيد Square للدفع

في بيئة Sandbox، تحتوي قائمة الأجهزة على معرّفات أجهزة الاختبار الموثّقة لدى Square، فيمكن تجربة كل النتائج — نجاح، أو انتهاء مهلة، أو عدم اتصال — دون أجهزة فعلية.

عناصر التحكم في الدفع

• بدء الدفع: إرسال طلب دفع جديد إلى الجهاز الطرفي المحدد
• إلغاء الدفع: إلغاء عملية دفع جارية حاليًا على الجهاز الطرفي
• فحص الحالة: سؤال Square عن الحالة الراهنة فورًا
• تحرير الدفع: فصل جهاز طرفي لا يستجيب حتى يمكن دفع الطلب بطريقة أخرى؛ ومع ذلك تُسوّى عملية الدفع المهجورة في الخلفية
• سجل الدفع: سجل اختياري لكل طلب يوثّق كل خطوة ونتيجة لدى Square

إدارة الطلبات

• إتمام مُتحقَّق منه: لا تُعلَّم الطلبات مدفوعة إلا بعد التحقق من الدفع مقابل كائن الدفع لدى Square — ولا تُعلَّم أبدًا بناءً على إشارة غير مُتحقَّق منها
• تتبّع الدفع: تُخزَّن معرّفات Square وسجل الدفع في الطلب، وتُكتب الخطوات الأساسية في ملاحظات الطلب
• إنشاء الإيصالات: تُنشَأ إيصالات نقطة البيع القياسية بعد المدفوعات الناجحة

المتطلبات

حساب Square: حساب بائع Square نشط

موقع Square: موقع Square، ومعرّف الموقع الخاص به

أجهزة متوافقة: جهاز Square Terminal، متصل بالإنترنت ومسجّل الدخول في موقع Square نفسه

موقع HTTPS علني: مطلوب فقط إذا أردت webhooks؛ فالمدفوعات تُؤكَّد بالاستعلام الدوري من دونها

WCPOS: إصدار Pro مطلوب للدفع في نقطة البيع

توافق الأجهزة

متطلبات الاتصال

يستخدم Square Terminal واجهة Terminal API من جانب الخادم لدى Square: فعملية الدفع يُنشئها موقعك ويُسلّمها Square إلى الجهاز المقترن. ويجب أن يكون الجهاز الطرفي متصلاً بالإنترنت ومسجّلاً الدخول بنفس حساب Square ونفس الموقع المستخدمَين في الإضافة.

الأجهزة الطرفية المدعومة

• Square Terminal ✅ — جهاز Square الطرفي المخصص للبطاقات على المنضدة

النطاق والقيود

النطاق الحالي

• يركّز على مسارات نقطة البيع / دفع الطلب. أما التوفر في دفع واجهة المتجر الموجهة للعملاء فهو معطّل افتراضيًا ويجب تفعيله صراحةً.
• يحصّل المدفوعات فقط — إذ لا تُدعم المبالغ المستردة بعد. وتُخزَّن معرّفات Square في الطلب حتى يمكن إضافة دعم الاسترداد لاحقًا.
• يجب إضافة اشتراكات webhook يدويًا في Square؛ انظر Webhooks.

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

المشكلات الشائعة

قائمة أجهزة Terminal فارغة

• يجب اقتران الجهاز الطرفي بهذه الإضافة أولًا — استخدم إنشاء رمز جهاز وأدخل الرمز في الجهاز
• لن يظهر جهاز طرفي مقترن عبر لوحة Square أو تطبيق Square POS حتى يُقترن هنا
• انقر البحث عن القارئات: فإذا ظهر ضمن أجهزة أخرى يستطيع Square رؤيتها، فهو موجود لكنه غير مقترن بهذه الإضافة
• تأكد من تطابق معرّف الموقع مع الموقع الذي سجّل الجهاز الطرفي الدخول فيه

الجهاز لا يقترن

• تأكد من أنك أدخلت رمز الجهاز قبل انتهاء صلاحيته — ولّد رمزًا جديدًا عبر إنشاء رمز جهاز
• تأكد من أن الجهاز الطرفي متصل بالإنترنت ومسجّل الدخول بنفس حساب Square ومعرّف الموقع المستخدمَين في الإضافة
• تحقق من تطابق البيئة مع الحساب الذي سجّل الجهاز الطرفي الدخول به

فشل التحقق من الإعدادات

• إذا كنت متصلًا، فتحقق من أن صف حساب Square لا يزال يعرض متصل بـ Square؛ فإذا طلب منك إعادة الاتصال، فقد انتهى التفويض
• إذا كنت تستخدم رمز وصول، فتأكد من مطابقته لـالبيئة المحددة — إذ لن يعمل رمز Sandbox في الإنتاج، والعكس صحيح
• تأكد من أن معرّف الموقع يخص ذلك الحساب

يكتمل الدفع على الجهاز الطرفي لكن الطلب بطيء في التحديث

• هذا ما تعالجه webhooks. فمن دونها، يُحدَّث الطلب عندما يسوّيه الاستعلام الدوري أو المُصفّي العامل في الخلفية في المرة التالية
• تحقق من صف Webhooks — فإذا كان يقول لم يُتحقَّق منه بعد بعد إجراء مدفوعات، فاتبع إذا توقف التحقق من webhooks
• الطلب لا يضيع أبدًا: فالمُصفّي يسوّي أي عملية دفع يفوتها الاستعلام

الدفع لا يبدأ

• تأكد من اختيار جهاز طرفي ومن أن الجهاز مقترن ومتصل بالإنترنت
• تحقق من أن الجهاز مسجّل الدخول في معرّف الموقع المُعدّ
• راجع سجل الدفع وWooCommerce > Status > Logs بحثًا عن رسائل واجهة Square البرمجية

تظهر رسالة تفيد بضرورة إعادة الاتصال بـ Square

تُجدَّد تفويضات Square تلقائيًا. وإذا تعذّر إتمام التجديد، تُنهي الإضافة التفويض بدلًا من تركه في حالة غير قابلة للاستخدام، وتطلب منك شاشة الإعدادات إعادة الاتصال. انقر إعادة الاتصال بـ Square — ولا شيء آخر يحتاج إلى تغيير.

الحصول على المساعدة

للحصول على الدعم الفني:

• زر مستودع GitHub للإبلاغ عن المشكلات
• راجع وثائق Square Terminal API للإرشادات المتعلقة بالأجهزة وواجهة البرمجة
• تواصل مع دعم Square لمشكلات الحساب والأجهزة

تُكتب السجلات في WooCommerce > Status > Logs تحت المعرّف sqtwc، وتوثّق كل عملية بحث عن جهاز وكل نتيجة webhook.

لقطات الشاشة

ستُضاف لقطات الشاشة في تحديث مستقبلي لعرض:

• أقسام حساب Square وTerminal والإعدادات المتقدمة
• تفعيل البوابة في إعدادات WCPOS
• سير عمل معالجة الدفع في شاشة الدفع بنقطة البيع