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

المتطلبات

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

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

عملة المتجر: يجب أن يكون «سول بيروفي» (PEN) أو «دولار أمريكي» (USD) عملةً مفعّلة في متجرك. لا تقبل Culqi أي عملات أخرى، ولا يظهر طريقة الدفع إلا عندما يدفع العميل بعملة PEN أو USD.

حساب Culqi: تحتاج إلى المفتاح العام والمفتاح السري لحساب Culqi الخاص بك. تأتي مفاتيح التكامل (الاختبار) من integ-panel.culqi.com، وتأتي مفاتيح الإنتاج (الحقيقية) من mipanel.culqi.com، وذلك في CulqiPanel > Desarrollo > API Keys. يستخدم المتصفح المفتاح العام في نافذة Culqi المنبثقة. أما المفتاح السري فيُستخدم على خادمك فقط، ولا يُرسل إلى المتصفح أبدًا. لا حاجة إلى webhook.

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

التثبيت

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

OpenCart 3

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

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

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

4. الصق مفاتيح التكامل، ولمدفوعات حقيقية الصق مفاتيح الإنتاج (انظر الإعداد).

5. فعّل Enable/Disable وانقر على Save. أبقِ Test Mode مفعّلًا أثناء الاختبار، ثم أوقفه لاستقبال مدفوعات حقيقية.

OpenCart 4

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

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

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

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

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

الإعداد

توجد جميع الإعدادات في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox Culqi Payment > Edit. تظهر الأقسام في القائمة على اليسار، ويحفظ زر Save أسفل القائمة الصفحة كاملةً. وفوق الإعدادات، تعرض الصفحة Test mode is active: the integration keys are used and no real money is charged. طالما كان وضع الاختبار مفعّلًا. وتحذّرك الصفحة عندما تكون البوابة مفعّلة لكن مفاتيح الوضع الحالي مفقودة، وعندما لا تكون أي عملة مفعّلة في المتجر مدعومة من Culqi. وفي كلتا الحالتين تُخفى طريقة الدفع عند إتمام الطلب. وإذا لم تكن عملتك الافتراضية PEN أو USD، تشير الصفحة إلى أن Culqi لا يُعرض إلا عندما يدفع العميل بعملة مدعومة. وبدون صلاحية تعديل الإضافة، تعرض الصفحة الإعدادات لكن لا يمكنها حفظها.

عند الحفظ، لا تُحفظ القيمة الخاطئة، بل تحتفظ بقيمتها السابقة، بينما تُحفظ الحقول الأخرى. وتعرض الصفحة خطأً لكل حقل من هذا النوع: مفتاح ببادئة خاطئة (مثلًا Live Secret Key must start with sk_live_ — the previous value was kept.)، أو حقل Title فارغ أو أطول من 128 حرفًا، أو Sort Order ليس عددًا صحيحًا، أو Total ليس عددًا أكبر من 0 أو يساويه، أو منطقة جغرافية أو حالة طلب غير موجودة.

Culqi

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

Title: اسم طريقة الدفع الذي يراه العميل عند إتمام الطلب. وهو أيضًا اسم طريقة الدفع المحفوظ في الطلب. الافتراضي: Credit/Debit Card or Yape (Culqi). حقل مطلوب، بحد أقصى 128 حرفًا.

Description: النص الذي يراه العميل في خطوة Confirm Order، فوق زر التأكيد. الافتراضي: Pay securely with your credit/debit card or Yape via Culqi.

Sort Order: ترتيب Culqi بين طرق الدفع عند إتمام الطلب. اتركه فارغًا أو أدخل عددًا صحيحًا.

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

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

مفاتيح API

انسخ المفاتيح من CulqiPanel > Desarrollo > API Keys: مفاتيح التكامل (الاختبار) من integ-panel.culqi.com، ومفاتيح الإنتاج من mipanel.culqi.com (تتضمن الصفحة الروابط). يستخدم وضع الاختبار مفاتيح الاختبار فقط، ويستخدم الوضع الحقيقي مفاتيح الإنتاج فقط. يجب أن يبدأ كل مفتاح ببادئة حقله.

Test Mode: عند التفعيل، تُستخدم مفاتيح الاختبار (pk_test_ / sk_test_) ولا يُخصم أي مبلغ حقيقي. الافتراضي: مفعّل. أوقفه لاستقبال مدفوعات حقيقية بمفاتيح الإنتاج. وطالما كان مفعّلًا، يرى العملاء في خطوة Confirm Order العبارة TEST MODE: No real charges will be made.

Test Public Key: المفتاح العام لبيئة التكامل. يبدأ بـ pk_test_.

Test Secret Key: المفتاح السري لبيئة التكامل. يبدأ بـ sk_test_ ولا يُشارك مع المتصفح أبدًا.

Live Public Key: المفتاح العام لبيئة الإنتاج. يبدأ بـ pk_live_.

Live Secret Key: المفتاح السري لبيئة الإنتاج. يبدأ بـ sk_live_ ولا يُشارك مع المتصفح أبدًا.

لا تُعرض المفاتيح السرية المحفوظة مرة أخرى. يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. اكتب قيمة جديدة فقط عندما تريد تغييرها. ولإزالة مفتاح سري محفوظ، ضع علامة على Clear the saved key on save أسفل الحقل، ثم انقر على Save.

طرق الدفع

تُعرض البطاقات دائمًا. أما التحويل البنكي والوكلاء والمحافظ وCuotéalo فتحتاج إلى Culqi Orders API، ولا تقدّمها هذه الإضافة.

Yape: Offer Yape in the Culqi popup يعرض Yape بجانب البطاقات في نافذة Culqi. الافتراضي: مفعّل.

الطلبات

ينشئ OpenCart الطلب في خطوة Confirm Order دون حالة (طلب مفقود). لا يحصل الطلب على حالة إلا بعد أن تؤكد Culqi الخصم. يسرد كل حقل من الحقول التالية حالات الطلبات في OpenCart لديك.

Order Status After Payment: أكدت Culqi الخصم، وتطابق مبلغه وعملته مع الطلب. الافتراضي: Processing.

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

Refunded Status: استُرد الدفع بالكامل من صفحة الطلب. الاسترداد الجزئي يضيف ملاحظة فقط. الافتراضي: Refunded.

متقدم

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

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

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

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

Export: Download JSON يحفظ الإعدادات في ملف JSON. لا تُصدَّر المفاتيح السرية.

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

إتمام الطلب

في خطوة Payment Method يختار العميل طريقة الدفع (افتراضيًا Credit/Debit Card or Yape (Culqi)). وفي خطوة Confirm Order يرى العميل وصفك، وينشئ OpenCart الطلب، وما زال دون حالة. عندما ينقر العميل على Confirm Order، تُفتح نافذة Culqi Checkout المنبثقة في الصفحة نفسها، وتعرض اسم متجرك وإجمالي الطلب والعملة. هناك يُدخل العميل بيانات بطاقته أو يدفع بواسطة Yape. وتُحمَّل نصوص Culqi دائمًا من Culqi. وفي OpenCart 4 يختار العميل طريقة الدفع بزر Choose في كتلة طريقة الدفع، في النافذة Payment method options، وينقر على Confirm Order في كتلة التأكيد أسفل صفحة الدفع. وإذا لم يطلب المتجر عنوان دفع (وهو الإعداد الافتراضي في OpenCart 4)، تُؤخذ تفاصيل العميل المرسلة مع الخصم من عنوان التوصيل ومن اسم العميل.

تحوّل Culqi بيانات الدفع إلى رمز يُستخدم مرة واحدة، ولا يُرسل إلى متجرك إلا هذا الرمز. يُنشئ خادمك الخصم عبر Culqi Charges API بقيمة إجمالي الطلب بعملة الطلب، ويُحصَّل فورًا. يظهر الخصم في CulqiPanel باسم Order ورقم الطلب مع البريد الإلكتروني للعميل. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكد Culqi ذلك. ثم يحصل الطلب على حالته بالطريقة القياسية في OpenCart، مع رسائل الطلب المعتادة وتحديث المخزون، ويرى العميل صفحة نجاح الطلب في OpenCart.

إذا طلب البنك التحقق عبر 3-D Secure، يرى العميل Your bank requires additional verification (3-D Secure). Please complete it in the window that opens. وبعد المصادقة يُعاد إرسال الخصم تلقائيًا. وإذا لم يكتمل التحقق، يرى العميل The 3-D Secure verification was not completed. Please try again or use another card.

إذا رُفضت البطاقة، يرى العميل رسالة Culqi بعد Payment failed: ويمكنه المحاولة مجددًا ببطاقة أخرى في الخطوة نفسها. وإذا لم تستجب Culqi، يرى العميل We could not confirm your payment with Culqi. Please check your email or contact us before trying again. وفي هذه الحالات يبقى الطلب دون حالة، وتسجّل ملاحظة في سجل الطلب المحاولة. وإذا أغلق العميل نافذة Culqi فلن يُخصم أي مبلغ، ويمكنه النقر على زر Confirm Order مجددًا. ويُحتفظ بسلة المشتريات في كل هذه الحالات.

لا يُخصم الطلب مرتين أبدًا. وإذا أعاد العميل الإرسال أثناء جارٍ دفع للطلب نفسه، يرى This order is already being paid. Please wait a moment and check your email before trying again. وإذا حصّلت Culqi المبلغ لكن تعذّر تعيين حالة الطلب، يرى العميل Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. يُحتفظ بالخصم، والمحاولة التالية بالسلة نفسها تعيّن حالة الطلب بناءً عليه دون خصم جديد. وتُدفع السلة مرة واحدة فقط: إذا كان طلب آخر من السلة نفسها (ينشئ OpenCart 3 طلبًا جديدًا في كل مرة تُعرض فيها خطوة Confirm Order) مدفوعًا بالفعل، ينتقل العميل إلى صفحة النجاح دون خصم جديد. ويحتفظ OpenCart 4 بطلب واحد للدفع ويحدّثه، لذلك يدفع العميل الطلب نفسه بعد رفض البطاقة.

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

تقبل الإضافة مدفوعات البطاقات وYape لمرة واحدة فقط، وتُحصَّل فورًا. ولا تتضمن تطبيق بنكيًا أو وكلاء أو محافظ أو Cuotéalo، ولا بطاقات محفوظة أو اشتراكات أو أقساطًا، ولا webhooks من Culqi، ولا تفويضًا وتحصيلًا منفصلين.

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

حالات الطلب

No status (missing order): لم يدفع العميل بعد، أو رُفضت البطاقة، أو لم تستجب Culqi. وفي Sales > Orders لا تظهر هذه الطلبات إلا مع الفلتر Order Status مضبوطًا على Missing Orders. توضح الملاحظات في سجل الطلب المحاولات الفاشلة.

Order Status After Payment (default Processing): أُكد الخصم ويطابق الطلب. تعرض الملاحظة Culqi payment successful مع الوضع (اختبار أو حقيقي)، وتشير إلى 3-D Secure إن استُخدم، ومعرّف الخصم في Culqi (chr_...).

On Hold (Review) Status (default Pending): أبلغت Culqi عن خصم لا يطابق الطلب في المبلغ أو العملة، أو عن دفعة مُفوَّضة لكنها غير مُحصَّلة. توضح الملاحظة ذلك وتعرض معرّف الخصم. تحقق من الخصم في CulqiPanel، ثم أكمل الطلب أو استرد الدفعة.

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

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

تبويب VibeFox Culqi Payment

في Sales > Orders افتح طلبًا دُفع عبر Culqi. وفي أسفل صفحة الطلب، بجوار History وAdditional، يعرض تبويب VibeFox Culqi Payment الحقل Charge ID مع وسم Test للمدفوعات التجريبية، والمبلغ المخصوم Amount (مع 3-D Secure إن استُخدم)، وتلميح Review للطلبات المعلّقة، والمبالغ Paid / refunded، ونموذج الاسترداد، وسجل الاسترداد، وCulqi notes الخاصة بالطلب. يظهر التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة.

الاسترداد

في تبويب VibeFox Culqi Payment أدخل Amount (تُملأ القيمة التي لم تُسترد بعد تلقائيًا)، واختياريًا Reason (optional)، ثم انقر على Refund via Culqi. أكّد السؤال Refund this amount through Culqi? This cannot be undone. الاسترداد الكامل والجزئي مدعومان. تحتاج إلى صلاحية تعديل الإضافة (تُحدَّد في System > Users > User Groups). تُنفَّذ عمليات الاسترداد بالمبلغ والعملة اللذين خصمتهما Culqi، لذلك بعد وجود فارق في المبلغ يمكنك الاسترداد حتى المبلغ الذي دفعه العميل فعلًا، لا إجمالي الطلب. يُرسَل الاسترداد بمفاتيح الوضع الذي تم فيه الدفع (اختبار أو حقيقي)، حتى لو بدّلت الوضع بعد ذلك، لذلك يجب تعيين المفتاح السري لذلك الوضع. إذا لم تقبل Culqi الاسترداد، يعرض التبويب الخطأ ولا يُسجَّل أي استرداد. ويُضاف الاسترداد الناجح إلى سجل الاسترداد والملاحظات مع معرّف استرداد Culqi والمبلغ وسببك. يضع الاسترداد الكامل الطلب في Refunded Status دون إشعار العميل ودون إعادة المنتجات إلى المخزون، كما هو الحال عند تغيير الحالة يدويًا. ولا يغيّر الاسترداد الجزئي الحالة.

لا ترد المرتجعات في Sales > Returns أموالًا عبر Culqi. ولا تتزامن عمليات الاسترداد المنفّذة في CulqiPanel مع OpenCart. حدّث الطلب يدويًا عند الحاجة.

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

تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox Culqi Payment هي أول كتلة في Extensions > Extensions > Payments > VibeFox Culqi Payment > Edit، فوق الإعدادات. الصق المفتاح في License key وانقر على Activate. بعد ذلك تعرض الكتلة المفتاح مُخفيًا، والحالة (مثل تاريخ انتهاء الترخيص ونطاقك)، والأزرار Check now للتحقق من الحالة مجددًا، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وتحتها السطر Product: opencart-payment-culqi والرابط 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.

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

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

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

لا يظهر Culqi عند إتمام الطلب: تحقّق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن مفتاحي الوضع الحالي مُعيّنان (Test Public Key وTest Secret Key في وضع الاختبار، أو Live Public Key وLive Secret Key في الوضع الحقيقي)، وأن العميل يدفع بعملة PEN أو USD. تعرض صفحة الإعدادات تحذيرًا عند غياب المفاتيح. وتحقق أيضًا من أن عنوان الدفع يقع ضمن Geo Zone المحددة، وأن الطلب يبلغ Total المضبوط في الإعدادات.

تمّ الدفع، لكن الطلب بقي دون حالة: لا تستخدم الإضافة webhooks. ولا يُؤكَّد الخصم إلا برد Culqi على خادمك. وإذا لم ترد Culqi في الوقت المناسب، يحمل الطلب الملاحظة Culqi did not confirm the charge. ابحث عن خصم هذا الطلب في CulqiPanel. وإذا رأى العميل رسالة تفيد بأن الطلب تعذّر إتمامه، فإن محاولة الدفع التالية في جلسة العميل نفسها تعيّن الحالة دون خصم جديد.

الطلب في حالة المراجعة بعد الدفع: اقرأ الملاحظات في تبويب VibeFox Culqi Payment. كان المبلغ أو العملة المخصومة مختلفًا عن الطلب، أو لم تُحصَّل الدفعة. تحقق من الخصم في CulqiPanel، ثم أكمل الطلب أو استرد الدفعة.

المفتاح لا يُحفظ: يوضح الخطأ أن الحقل يجب أن يبدأ ببادئة، مثل sk_live_. يقبل كل حقل مفاتيح نوعه ووضعه فقط: pk_test_ أو sk_test_ أو pk_live_ أو sk_live_.

يرى العميل Payment gateway misconfiguration. Please contact the store owner.: مفاتيح الوضع الحالي مفقودة، أو رفضت Culqi المفتاح السري. تحقق من المفاتيح في الإعدادات.

يرى العميل Payment token is invalid. Please try again.: الرمز القادم من نافذة Culqi يتبع الوضع الآخر، مثلًا بعد تبديل Test Mode والصفحة مفتوحة. يجب على العميل إعادة تحميل الصفحة ثم الدفع مرة أخرى.

لا تفتح نافذة Culqi: يرى العميل The Culqi payment window could not be loaded. Please reload the page and try again. تحقق من أن نصوص js.culqi.com و3ds.culqi.com غير محظورة في صفحة الدفع، مثلًا بسبب إضافة تخزين مؤقت أو تحسين.

يرى العميل Security check failed. Please reload the page and try again.: كانت صفحة الدفع مفتوحة في جلسة أخرى. إعادة تحميل الصفحة تحل المشكلة.

يرى العميل This payment method is not available.: لم تعد جلسة الدفع تحتوي على طلب Culqi، أو أُوقفت طريقة الدفع في هذه الأثناء. يعيد العميل تحميل صفحة الدفع.

رُفضت بطاقة وتريد معرفة السبب: اقرأ الملاحظة في الطلب أو حقل Log في صفحة الإضافة. تُسجَّل حالات الرفض مع رمز رفض Culqi حتى عندما يكون Debug log معطّلًا.

لا يوجد نموذج استرداد في التبويب: يوضح التبويب السبب: تم استرداد الدفع بالكامل، أو مجموعة المستخدمين لديك لا تملك صلاحية تعديل الإضافة، أو المفتاح السري لوضع الدفع مفقود.

يفشل الاسترداد برسالة تتعلق بالمفاتيح: تم الدفع في وضع الاختبار أو الوضع الحقيقي، والمفتاح السري لذلك الوضع غير مُعيّن. أدخله ثم أعد المحاولة.

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

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

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

Culqi علامة تجارية مملوكة لصاحبها. هذه الإضافة غير تابعة لـ Culqi ولا تحظى بتأييدها.