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

المتطلبات

OpenCart: الإصدار 3.0.x (تم الاختبار على 3.0.5.0) أو 4.0.2 أو أحدث (تم الاختبار على 4.1.0.3).

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

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

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

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

التثبيت

التنزيل ملف zip واحد يحتوي على الحزم الخاصة بالإصدارين من OpenCart. فُكّ ضغطه على حاسوبك. ويحتوي على README.txt، وحزمة OpenCart 3 wcp_square_gateway-oc3-(version).ocmod.zip، وحزمة OpenCart 4 wcp_square_gateway.ocmod.zip. ثبّت الحزمة الخاصة بإصدار OpenCart لديك فقط. مفتاح الترخيص واحد للإصدارين.

OpenCart 3

1. في لوحة الإدارة، انتقل إلى Extensions > Installer، وانقر على Upload، ثم اختر الملف wcp_square_gateway-oc3-(version).ocmod.zip. لا تحتوي الإضافة على تعديلات OCMOD، لذلك لا تحتاج Extensions > Modifications إلى تحديث. وبدلًا من المثبّت يمكنك نسخ محتويات المجلد upload من هذه الحزمة إلى المجلد الجذري لمتجرك.

2. انتقل إلى Extensions > Extensions واختر النوع Payments. ابحث عن VibeFox Square Gateway وانقر على Install (الزر الأخضر +). يحتاج مستخدم الإدارة لديك إلى صلاحية تعديل قائمة إضافات الدفع.

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

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

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

OpenCart 4

1. في لوحة الإدارة، انتقل إلى Extensions > Installer، وانقر على Upload، ثم اختر الملف wcp_square_gateway.ocmod.zip. لا تُغيّر اسم الملف: يأخذ OpenCart 4 رمز الإضافة من اسم الملف، ولا تعمل الحزمة إذا أُعيدت تسميتها.

2. تظهر الحزمة في قائمة الإضافات المثبتة في الصفحة نفسها. انقر على Install (الزر الأخضر +) بجانبها.

3. انتقل إلى Extensions > Extensions واختر النوع Payments. ابحث عن VibeFox Square Gateway، وانقر على Install (الزر الأخضر +)، ثم على Edit (زر القلم).

4. أدخل مفتاح الترخيص وبيانات اعتماد Square كما في الخطوات من 3 إلى 5 لـ OpenCart 3. صفحة الإعدادات وحقولها متطابقة في الإصدارين.

تبدأ عملية التثبيت الجديدة وطريقة الدفع معطلة ووضع Sandbox مفعّل.

الإعداد

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

عند الحفظ، يجب ألا يكون حقل Title فارغًا (حتى 128 حرفًا)، ويجب أن يكون Sort Order عددًا صحيحًا (تُقبل القيم السالبة)، ويجب أن يكون Total رقمًا يساوي 0 أو أكبر، ويجب أن توجد المنطقة الجغرافية وحالات الطلب المحددة؛ وإلا فلن يُحفظ شيء. ثم تتحقق الإضافة من بيانات اعتماد الوضع المحدد لدى Square. تُحفظ الإعدادات في كل الأحوال، وتظهر التحذيرات في كتلة حمراء فوق الإعدادات: رفضت Square الـ Access Token، أو لم يُعثر على Location ID لهذا الرمز، أو تعذّر التحقق من بيانات الاعتماد، أو اختلفت عملة الموقع عن عملة المتجر. لا تستطيع Square الخصم إلا بعملة الموقع: تتذكر الإضافة عملة الموقع الذي تم التحقق منه، وتخفي طريقة الدفع للطلبات التي تستخدم عملة أخرى. كما تحذّر إذا استُخدم Application ID الخاص بالـ sandbox في وضع الإنتاج أو العكس.

Square

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

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

Description: النص الذي يراه العميل في خطوة Confirm Order فوق نموذج البطاقة. الافتراضي: Pay securely with your credit or debit card via Square.

Sort Order: موضع الدفع بالبطاقة بين طرق الدفع في صفحة الدفع. اتركه فارغًا أو أدخل عددًا صحيحًا (تُقبل القيم السالبة).

Geo Zone: اعرض نموذج البطاقة فقط لعناوين الدفع الواقعة في المنطقة الجغرافية المحددة. الافتراضي: All zones. تُضبط المناطق الجغرافية في System > Localisation > Geo Zones.

Total: إجمالي صفحة الدفع، بالعملة الافتراضية للمتجر، الذي يجب أن يبلغه الطلب حتى تُعرض طريقة الدفع. اتركه فارغًا لعرضها مهما كان المبلغ.

حساب Square

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

Sandbox Mode: تذهب المدفوعات إلى بيئة Sandbox الخاصة بـ Square، ولا يُخصم أي مبلغ حقيقي. استخدم بطاقات الاختبار الخاصة بـ Square. الافتراضي: مفعّل. تستخدم الاستردادات الخاصة بأي طلب دائمًا البيئة والموقع اللذين دُفع الطلب بهما.

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

Sandbox Access Token: رمز Access Token الخاص ببيئة الاختبار في Square.

Sandbox Location ID: معرّف الموقع الخاص ببيئة الاختبار في Square.

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

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

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

لا تُعرض رموز Access Token المحفوظة مرة أخرى. يبقى الحقل فارغًا ويعرض محفوظ — اتركه فارغًا للاحتفاظ به.. لا تُدخل قيمة جديدة إلا إذا أردت تغييرها. لحذف رمز Access Token محفوظ، فعّل خانة Clear the saved value on save أسفل الحقل، وانقر على Save.

الطلبات

ينشئ OpenCart الطلب في خطوة Confirm Order بدون حالة (طلب غير مكتمل). لا يحصل الطلب على حالة إلا بعد أن ترد Square على الدفع. يعرض كل حقل أدناه حالات الطلبات الخاصة بـ OpenCart لديك.

Order Status After Payment: أتمّت Square الدفع بالمبلغ والعملة المطابقين تمامًا للطلب. الافتراضي: Processing.

On Hold (Review) Status: يحتاج الدفع إلى مراجعتك (انظر حالات الطلب). الافتراضي: Pending، لأن OpenCart لا يملك حالة On hold. يمكنك إنشاء حالة خاصة بك في System > Localisation > Order Statuses واختيارها هنا.

Refunded Status: تُضبط بعد استرداد الدفع بالكامل من تبويب الطلب. الافتراضي: Refunded.

متقدم

Debug log: تُسجَّل الأخطاء والتحذيرات دائمًا. عند تفعيله، تُسجَّل أيضًا كل الطلبات والردود، دون بيانات البطاقات أو المفاتيح، في wc_sqg_debug.log.php داخل مجلد سجلات OpenCart (storage/logs). لا يمكن فتح الملف من الويب، وعند بلوغه 5 ميغابايت يُنقل إلى wc_sqg_debug.old.log.php. الافتراضي: معطّل.

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

Delete data on uninstall: عند التفعيل، يؤدي إلغاء تثبيت الإضافة إلى حذف إعدادات البوابة وملفات السجل. تبقى مدفوعات Square واستردادات الطلبات محفوظة دائمًا. الافتراضي: معطّل.

الاستيراد / التصدير

Export: يحفظ Download JSON الإعدادات في ملف JSON. لا تُصدَّر رموز Access Token.

Import: الصق ملف JSON المُصدَّر سابقًا وانقر على Import لاستعادة الإعدادات. تبقى رموز Access Token المحفوظة كما هي.

الدفع

في خطوة Payment Method يختار العميل طريقة الدفع (افتراضيًا Credit / debit card). وفي خطوة Confirm Order يرى العميل Credit / debit card (Square) ووصفك، والرسالة وضع SANDBOX — لن تُجرى أي خصومات حقيقية. ما دام وضع Sandbox مفعّلًا، ونموذج بطاقة Square. ينشئ OpenCart الطلب في هذه الخطوة، ولا يزال بدون حالة. عندما ينقر العميل على Confirm Order، تُحوَّل البطاقة إلى رمز داخل المتصفح مع التحقق من المشتري (3-D Secure / SCA): يُرسل إجمالي الطلب والعملة وعنوان الدفع إلى Square، وقد يطلب بنك العميل التأكيد. ولا يستلم متجرك سوى رمز لمرة واحدة. في OpenCart 4 يختار العميل طريقة الدفع بزر Choose في كتلة طريقة الدفع، في النافذة Payment method options، ويظهر نموذج بطاقة Square بعد ذلك في كتلة التأكيد أسفل صفحة الدفع، فوق Confirm Order.

ثم تخصم الإضافة الرمز عبر Square Payments API بقيمة الطلب بعملة الطلب، مع رقم الطلب كمرجع، وملاحظة Order # تتضمن رقم الطلب واسم متجرك، وبريد العميل الإلكتروني. يُحصَّل الدفع فورًا. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكده Square: يجب أن يُظهر رد Square دفعة بالحالة COMPLETED بالإجمالي والعملة ورقم الطلب والموقع المطابقة تمامًا. ثم يحصل الطلب على Order Status After Payment بالطريقة المعتادة في OpenCart، مع رسائل البريد المعتادة للطلب وتحديث المخزون، ويرى العميل صفحة نجاح الطلب في OpenCart مع الرسالة تم استلام دفعتك بالبطاقة. ورابط View the receipt إلى إيصال Square. إذا لم تكن حالة الدفع COMPLETED أو اختلفت أي قيمة، يحصل الطلب على On Hold (Review) Status وتعرض الصفحة الرسالة تم استلام دفعتك بالبطاقة وهي قيد المراجعة. سنحدّث طلبك فور اكتمال المراجعة.

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

إذا لم ترد Square (مشكلة في الشبكة، أو انتهاء المهلة، أو خطأ في الخادم)، يُعاد الطلب مرة واحدة بالمفتاح idempotency نفسه. وإذا لم يصل رد بعد ذلك، تبحث الإضافة فورًا في Square عن دفعة هذا الطلب. فإن وجدتها، يحصل الطلب على حالته منها. وإذا لم تُوجد أي دفعة، يبقى العميل في خطوة Confirm Order مع الرسالة تعذّر الحصول على تأكيد من مزوّد الدفع. يرجى الانتظار دقيقة ثم المحاولة مرة أخرى — إذا خُصمت بطاقتك بالفعل، فسيتم التعرف على الدفعة ولن تُخصم منك مرتين. تبحث المحاولة التالية للسلة نفسها أولًا عن الدفعة السابقة مرة أخرى. وإذا تعذّر الوصول إلى Square لهذا البحث أيضًا، يحصل الطلب على On Hold (Review) Status بدون دفعة، مع ملاحظة بأنه ربما خُصمت البطاقة، وتعرض صفحة النجاح الرسالة تعذّر الحصول على تأكيد لدفعتك بالبطاقة من Square. يرجى التحقق من بريدك الإلكتروني وكشف حساب بطاقتك قبل الدفع مرة أخرى، أو التواصل معنا.

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

يحتفظ OpenCart 4 بطلب واحد للدفع ويحدّثه، لذلك بعد رفض البطاقة يدفع العميل الطلب نفسه مرة أخرى، وبعد دفعة لم يصل ردّ Square عليها تبحث المحاولة التالية لذلك الطلب أولًا عن الدفعة السابقة. وإذا كانت لطلب الدفع حالة بالفعل (دُفع أو أغلقه المتجر) وتحتوي السلة على منتجات جديدة، يُعاد العميل إلى صفحة الدفع وتُدفع السلة الجديدة بطلب جديد.

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

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

حالات الطلب

بدون حالة (طلب غير مكتمل): لم يدفع العميل بعد، أو رُفضت البطاقة، أو ضاع رد Square ولم تُوجد أي دفعة. في Sales > Orders تظهر هذه الطلبات فقط عند ضبط فلتر Order Status على Missing Orders.

Order Status After Payment (الافتراضي Processing): أكّدت Square دفعة COMPLETED بإجمالي الطلب. تُظهر ملاحظة معرّف الدفعة في Square، وعلامة البطاقة وآخر 4 أرقام، والوضع (sandbox أو الإنتاج).

On Hold (Review) Status (الافتراضي Pending): ردّت Square بدفعة ليست COMPLETED (مثل APPROVED أو PENDING)، أو بمبلغ أو عملة أو مرجع أو موقع مختلف. تُظهر الملاحظة الدفعة في Square تحتاج إلى مراجعة معرّف الدفعة والحالة والمبالغ. تُستخدم هذه الحالة أيضًا عندما يتغير الطلب أثناء الدفع، وعندما يضيع رد Square ولا يمكن التحقق منه (في هذه الحالة لا تُسجَّل أي دفعة، وتطلب الملاحظة منك التحقق من دفعات الموقع في Square Dashboard مع رقم الطلب كمرجع). تحقق من الدفعة في Square Dashboard قبل تنفيذ الطلب.

Refunded Status (الافتراضي Refunded): استُرد الدفع بالكامل عبر الإضافة.

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

الملاحظات هي إدخالات في History الطلب التي لا يراها العميل.

تبويب VibeFox Square Gateway

في Sales > Orders افتح طلبًا دُفع عبر Square. في أسفل صفحة الطلب، بجوار History وAdditional، يعرض تبويب VibeFox Square Gateway معرّف الدفع Payment ID في Square (مرتبطًا بالدفعة في Square Dashboard) مع تسمية Sandbox للدفعات التجريبية، وStatus في Square، وعلامة Card وآخر 4 أرقام، والمبالغ Paid / order / refunded، وEnvironment / location، ورابط Square receipt، ونموذج الاسترداد، وسجل الاستردادات، وSquare notes الخاصة بالطلب. لا تُخزَّن أرقام البطاقات أبدًا. يظهر التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة.

الاستردادات

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

لا تعيد المرتجعات في Sales > Returns الأموال عبر Square. تُنجز Square الاستردادات من جهتها: لا يُبلَّغ عن استرداد ترفضه Square لاحقًا، ولا تظهر في OpenCart الاستردادات التي تُنفَّذ في Square Dashboard.

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

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

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

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

بدون مفتاح نشط لا يظهر Square للعملاء في صفحة الدفع. وإذا بدأ الدفع رغم ذلك، يرى العميل الرسالة طريقة الدفع هذه غير متاحة. يرجى اختيار طريقة أخرى. ويظل مستخدم الإدارة المسجّل الدخول إلى لوحة الإدارة في المتصفح نفسه يرى طريقة الدفع في المتجر، مع العلامة (unlicensed — visible to admins only)، حتى تتمكن من إعداد الإضافة واختبارها قبل شراء مفتاح. في OpenCart 4 هذه المعاينة غير متاحة: لا يرى المتجر تسجيل دخول الإدارة، لذلك تكون طريقة الدفع مخفية عن الجميع بدون مفتاح نشط. بعد أن تفتح صفحة Edit مرة واحدة، يظهر تذكير في Dashboard الخاصة بلوحة الإدارة. أغلقه بالزر × لإخفائه لمدة 7 أيام. لا تتأثر الطلبات الحالية: تبقى الطلبات المدفوعة مدفوعة، وتعمل الاستردادات.

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

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

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

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

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

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

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

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

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

يرى العميل الرسالة طريقة الدفع هذه غير متاحة لطلبك: لم تعد صفحة الدفع متطابقة مع الطلب، أو ربما أُوقفت طريقة الدفع في هذه الأثناء، أو لا يمكن خصم عملة الطلب. يعيد العميل تحميل صفحة الدفع أو يختار طريقة دفع أخرى.

الطلب في حالة المراجعة بعد الدفع: اقرأ الملاحظات في تبويب VibeFox Square Gateway (انظر حالات الطلب). تحقق من الدفعة في Square Dashboard، ثم نفّذ الطلب أو استرد الدفعة.

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

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

أخطاء أخرى: فعّل Debug log وانظر إلى الحقل Log في صفحة الإضافة.

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

انتقل إلى Extensions > Extensions، واختر النوع Payments، ثم انقر على Uninstall (الزر الأحمر −) بجوار VibeFox Square Gateway. تُحذف دائمًا مفتاح الترخيص وحالة الترخيص لهذه الإضافة. وتحذف OpenCart دائمًا إعدادات الإضافة الخاصة بها: Enable/Disable وSort Order وGeo Zone وTotal وحالات الطلبات في قسم Orders، التي تعود إلى قيمها الافتراضية عند إعادة التثبيت. يُحذف أيضًا حدث OpenCart الخاص بالإضافة. إذا كان Delete data on uninstall مفعّلًا، تُحذف بقية إعدادات البوابة (العنوان والوصف ووضع sandbox وبيانات الاعتماد والتسجيل) وملفات السجل. وإذا كان معطّلًا، تُحفظ لإعادة التثبيت لاحقًا. تبقى مدفوعات Square واستردادات الطلبات محفوظة دائمًا، لذلك يمكن استرداد الطلبات المدفوعة سابقًا حتى بعد إعادة التثبيت. تحتفظ الطلبات الحالية بملاحظات الدفع الخاصة بها.

في OpenCart 4، لحذف ملفات الإضافة أيضًا، انتقل إلى Extensions > Installer بعد إلغاء التثبيت، وانقر على Uninstall (الزر البرتقالي −) بجوار VibeFox Square Gateway في قائمة الإضافات المثبتة، ثم على Delete (زر سلة المهملات الأحمر) لحذف الحزمة المرفوعة.

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