بوابة Square Terminal

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

الميزات

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

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

اقتران سهل

اقتران الأجهزة الطرفية من WooCommerce باستخدام رمز جهاز Square مؤقت

تأكيد عبر Webhook

تأكيد إتمام الدفع عبر إشعارات Square webhook الموثّقة، مع عرض الحالة مباشرةً أثناء الانتظار

معاملات آمنة

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

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

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

آلية العمل

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

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

التثبيت

1

تثبيت Square Terminal for WooCommerce

ثبّت الإضافة من WP Admin > نقطة البيع > الإعدادات > الإضافات، أو حمّل أحدث ملف zip للإضافة (وليس ملف zip أو tarball الخاص بالشيفرة المصدرية من GitHub) من صفحة الإصدارات على GitHub وارفعه عبر إضافات > إضافة جديد > رفع إضافة.

2

إعداد Square

1. انتقل إلى WP Admin > WooCommerce > الإعدادات > المدفوعات
2. ابحث عن Square Terminal في قائمة طرق الدفع وانقر عليه لفتح الإعدادات
3. اختر البيئة (Sandbox للاختبار، Production للمدفوعات الفعلية)
4. أدخل رمز الوصول الخاص بالبيئة المحددة (Sandbox أو Production)، المتاح من لوحة مطوري Square
5. أدخل معرّف الموقع — موقع Square الذي تُجرى فيه مدفوعات الطرفية
6. أدخل مفتاح توقيع Webhook وعنوان URL لإشعارات Webhook (انظر الخطوة التالية)
7. انقر على التحقق من الإعدادات لتأكيد صحة بيانات الاعتماد، ثم احفظ

ملاحظة

لا تحتاج إلى تفعيل بوابة Square Terminal في إعدادات WooCommerce. سيتم تفعيلها تحديدًا لنقطة البيع في خطوة لاحقة.

3

إعداد Webhooks في Square

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

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

هام

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

4

إقران جهاز Square Terminal

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

هام

يجب أن يكون الجهاز مقترنًا بنجاح ومتصلًا بالإنترنت قبل أن تتمكن من معالجة المدفوعات. تأكد من اكتمال الإقران قبل المتابعة.

5

التفعيل في WCPOS

1. انتقل إلى WP Admin > نقطة البيع > الإعدادات > إتمام الطلب
2. ابحث عن بوابة Square Terminal في القائمة
3. فعّل البوابة لاستخدامها في نقطة البيع
4. احفظ الإعدادات

الاستخدام

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

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

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

عند استخدام بوابة Square Terminal، تتوفر لديك الخيارات التالية:

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

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

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

المتطلبات

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

بيانات اعتماد API: رمز الوصول، ومعرّف الموقع، ومفتاح توقيع Webhook من لوحة تحكم مطوري Square

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

موقع HTTPS عام: يجب أن يكون موقعك قابلاً للوصول عبر HTTPS حتى تتمكن Square من إرسال إشعارات Webhook

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

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

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

يستخدم Square Terminal واجهة Terminal API من Square على جانب الخادم: يتم إنشاء عملية الدفع من موقعك وتسليمها إلى الجهاز المقترن بواسطة Square. يجب أن يكون الجهاز متصلاً بالإنترنت ومسجّلاً الدخول إلى نفس حساب Square ونفس الموقع، ويجب أن يستقبل موقعك إشعارات Square webhooks عبر HTTPS لتحديث الطلبات.

الأجهزة المدعومة

• Square Terminal ✅ — جهاز الدفع بالبطاقات المخصص من Square للطاولات

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

نطاق الإصدار v0.1

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

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

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

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

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

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

• تحقق من أن رمز الوصول يتطابق مع البيئة المحددة (رمز Sandbox لن يعمل في Production والعكس صحيح)
• تأكد من أن معرّف الموقع ينتمي إلى ذلك الحساب
• أعد نسخ الرمز من لوحة تحكم Square Developer تحسبًا لوجود أحرف زائدة

تكتمل عملية الدفع على الجهاز لكن الطلب لا يُحدَّث

• يجب أن يتطابق عنوان URL لإشعار Webhook في Square مع إعداد الإضافة تمامًا
• تأكد من الاشتراك في حدث terminal.checkout.updated في لوحة تحكم Square Developer
• تأكد من أن مفتاح توقيع Webhook في الإضافة يتطابق مع المفتاح الموجود في Square
• تأكد من أن موقعك متاح للعامة عبر HTTPS؛ تحقق من محاولات تسليم الـ webhook في لوحة تحكم Square

لا يبدأ الدفع

• تأكد من إدخال معرّف جهاز الطرفية صالح ومن أن الجهاز مقترن ومتصل بالإنترنت
• تحقق من أن الجهاز مسجّل الدخول إلى معرّف الموقع المُعدّ
• راجع سجل المدفوعات وسجلات أخطاء WordPress للاطلاع على رسائل Square API

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

للدعم الفني:

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

لقطات الشاشة

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

• إعداد بيانات اعتماد Square والـ webhook وإقران الجهاز
• تفعيل بوابة الدفع في إعدادات WCPOS
• سير عملية الدفع في شاشة الدفع بنقطة البيع