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

المتطلبات

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

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

العملة: يجب أن تكون عملة السلة هي عملة موقع 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. في back office اذهب إلى Modules > Module Manager وانقر على Upload a module. اختر ملف ZIP الخاص بالوحدة.

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

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

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

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

عند التثبيت تُنشئ الوحدة حالة الطلب Square payment on hold. تسمح PrestaShop لوحدة الدفع الجديدة بالعمل مع العملات والدول النشطة وقت التثبيت ومجموعات العملاء. راجعها، وفعّل الدول التي تضيفها لاحقًا في Payment > Preferences.

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Square Gateway > Configure. لكل قسم زر Save خاص به، ويحفظ الصفحة كاملة. عند تفعيل وضع Sandbox تعرض الصفحة فوق الحقول Square Gateway يعمل حاليًا في وضع SANDBOX. لن تُجرى أي عمليات خصم حقيقية.. وتحذّر إذا كانت Square مفعّلة لكن Application ID أو Access Token أو Location ID للوضع المحدد مفقود (وعندها تُخفى طريقة الدفع في صفحة الدفع)، أو إذا تعذّر على Square معالجة العملة الافتراضية لمتجرك، أو إذا كانت عملة موقع Square الخاص بك تختلف عنها.

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

Square

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

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

Description: وصف طريقة الدفع الذي يراه العميل في صفحة الدفع. الافتراضي: Pay securely with your credit or debit card via Square. وفي وضع Sandbox تُضاف إليه (SANDBOX MODE).

حساب Square

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

Sandbox 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 للإنتاج.

لا تُعرض رموز الوصول المحفوظة مرة أخرى. يبقى الحقل فارغًا ويعرض محفوظ — اتركه فارغًا للاحتفاظ به. اكتب قيمة جديدة فقط إذا أردت تغييرها.

Clear saved secrets: حدّد رمز وصول واضغط Save لإزالته. الحقل الفارغ يُبقي القيمة المحفوظة.

متقدم

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

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

Delete data on uninstall: عند التفعيل، تؤدي إزالة الوحدة إلى حذف إعدادات البوابة وملفات السجل. تبقى المدفوعات والاستردادات عبر Square الخاصة بالطلبات وحالة الطلب Square payment on hold محفوظة دائمًا. الافتراضي: off.

صفحة الدفع

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

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

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

إذا لم يرد Square (مشكلة في الشبكة، أو انتهاء المهلة، أو خطأ في الخادم)، يُعاد الطلب مرة واحدة بمفتاح idempotency نفسه. وإذا لم يصل رد بعد ذلك، تبحث الوحدة فورًا لدى Square عن دفعة هذه السلة. فإن وجدتها أُنشئ الطلب بها. وإذا لم تُوجد أي دفعة، يبقى العميل في صفحة الدفع ويرى رسالة لم نتمكن من الحصول على تأكيد من مزوّد الدفع. يرجى الانتظار دقيقة والمحاولة مرة أخرى — إذا كانت بطاقتك قد خُصمت بالفعل، فسيُتعرَّف على الدفعة ولن تُخصم منك مرتين. وتبحث المحاولة التالية أولًا عن الدفعة السابقة مرة أخرى. وإذا تعذّر الوصول إلى Square لهذا البحث أيضًا، يُنشأ الطلب بحالة Square payment on hold دون دفعة، مع ملاحظة بأن البطاقة ربما خُصمت، وتعرض صفحة التأكيد رسالة لم نتمكن من الحصول على تأكيد لدفعتك بالبطاقة من Square. يرجى التحقق من بريدك الإلكتروني وكشف حساب بطاقتك قبل الدفع مرة أخرى، أو التواصل معنا.

عندما يرفض البنك البطاقة، لا يُنشأ أي طلب ويبقى العميل في صفحة الدفع مع رسالة قصيرة حسب رمز الخطأ من Square، على سبيل المثال تم رفض بطاقتك. يرجى استخدام بطاقة أخرى أو طريقة دفع أخرى. أو رمز الأمان للبطاقة (CVV) غير صحيح. يرجى التحقق منه والمحاولة مرة أخرى. أو يتطلب بنكك تحققًا إضافيًا (3-D Secure). يرجى إدخال بطاقتك مرة أخرى وإكمال التحقق. تُحفظ السلة، ويمكن للعميل المحاولة مرة أخرى ببطاقة أخرى. يُسجَّل السبب التقني في السجل.

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

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

حالات الطلب

No order yet: رُفضت البطاقة، أو فُقد رد Square ولم تُوجد أي دفعة. لا يوجد سوى السلة.

Payment accepted: أكّد Square دفعة بحالة COMPLETED تطابق إجمالي السلة. تُسجَّل الدفعة بمعرّف دفعة Square كمعرّف للمعاملة، وتعرض ملاحظة معرّف الدفعة وعلامة البطاقة مع آخر 4 أرقام والوضع (sandbox أو live).

Square payment on hold: ردّ Square بدفعة ليست بحالة COMPLETED (مثل APPROVED)، أو بمبلغ أو عملة أو مرجع أو موقع مختلف. تعرض الملاحظة يحتاج دفع Square إلى مراجعة معرّف الدفعة والحالة والمبالغ. تُسجَّل الدفعة بحالة COMPLETED على الطلب بالمبلغ الذي خصمه Square. تُستخدم هذه الحالة أيضًا عندما تتغير السلة أثناء الدفع، وعندما يُفقد رد Square ولا يمكن التحقق منه (وفي هذه الحالة لا تُسجَّل أي دفعة). تحقّق من الدفعة في Square Dashboard قبل تجهيز الطلب.

Refunded: سُدِّد المبلغ كاملًا عبر الوحدة.

إذا وصلت دفعة ثانية لسلة لها طلب بالفعل، فلن يتغير الطلب. تطلب منك ملاحظة التحقق منها واسترداد النسخة المكررة في Square Dashboard.

كتلة Square

تعرض صفحة الطلب كتلة Square تتضمن معرّف دفعة Square (مرتبطًا بالدفعة في Square Dashboard)، وحالة Square، وعلامة البطاقة مع آخر 4 أرقام، والمبالغ Paid / order / refunded، والبيئة والموقع، ورابطًا إلى إيصال Square، وشارة Sandbox لدفعات sandbox، وسجل الاستردادات، وSquare notes الخاصة بالطلب. لا تُخزَّن أرقام البطاقات أبدًا.

الاستردادات

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

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

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

تعمل الوحدة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox Square Gateway هي الكتلة الأولى في Modules > Module Manager > VibeFox Square Gateway > Configure، فوق الإعدادات. الصق المفتاح في License key وانقر على Activate. بعد ذلك تعرض الكتلة المفتاح مخفيًا جزئيًا، والحالة (مثل تاريخ انتهاء الترخيص ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وتحتها السطر Product: presta-payment-square والرابط Manage licenses and domains in your account الذي يفتح حسابك في vibefox.net. لا يستطيع تغيير المفتاح إلا الموظفون الذين لديهم صلاحية Configure للوحدة. تتبع نصوص الكتلة لغة back office (وتشمل الإنجليزية والروسية).

إذا لم يُقبل المفتاح، تبيّن الكتلة السبب، مثل Key not found، أو This key belongs to another product، أو Domain limit reached، أو License expired on مع تاريخ. بعد تغيير عنوان المتجر، أو بعد تحرير خانة نطاق في حسابك، انقر على Check now. إذا تعذّر الوصول إلى خادم التراخيص، تستمر الوحدة بالعمل بآخر حالة معروفة.

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

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

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

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

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

نموذج البطاقة لا يُحمَّل: يرى العميل الرسالة تعذّر تحميل نموذج البطاقة. يرجى إعادة تحميل الصفحة أو اختيار طريقة دفع أخرى. تحقّق من أن Application ID وLocation ID يعودان إلى الوضع المحدد (معرّفات sandbox تبدأ بـ sandbox-). إذا نقر العميل مبكرًا جدًا تظهر الرسالة نموذج البطاقة ما زال قيد التحميل. يرجى الانتظار لحظة والمحاولة مرة أخرى.

اختفت طريقة الدفع بعد الحفظ: عملة موقع Square تختلف عن عملة السلة. أدخل Location ID لموقع Square بعملة متجرك واحفظ مرة أخرى: تظهر طريقة الدفع من جديد بعد تحقق ناجح.

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

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

رأى العميل الرسالة لم نتمكن من الحصول على تأكيد من مزوّد الدفع: لم يرد Square ولم تُوجد أي دفعة بعد. تحقّق من دفعات هذا الموقع في Square Dashboard (المرجع = معرّف السلة). إذا أعاد العميل المحاولة، تبحث الوحدة أولًا عن الدفعة السابقة وتنشئ الطلب بها بدلًا من الخصم مرة أخرى.

رأى العميل الرسالة تم استلام دفعتك، لكن تعذّر إكمال الطلب تلقائيًا: خُصمت البطاقة، لكن PrestaShop لم يتمكن من إنشاء الطلب (مثلًا لأن الوحدة كانت معطّلة في تلك اللحظة). اقرأ السجل، ثم أنشئ الطلب يدويًا أو استرد الدفعة في Square Dashboard.

الطلب في حالة Square payment on hold: اقرأ الملاحظات في كتلة Square (انظر حالات الطلب). تحقّق من الدفعة في Square Dashboard، ثم جهّز الطلب أو استرد الدفعة.

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

أخطاء أخرى: فعّل Debug log وراجع حقل Log في صفحة الوحدة.

الإزالة

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

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