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

المتطلبات

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

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

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

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

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

التثبيت

1. في لوحة الإدارة، انتقل إلى Modules > Module Manager وانقر على Upload a module. اختر ملف ZIP الخاص بالوحدة.

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

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

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

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

6. تأكد من أن PEN أو USD عملة نشطة في متجرك.

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

الإعدادات

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

Culqi

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

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

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

مفاتيح API

انسخ المفاتيح من CulqiPanel > Desarrollo > API Keys: مفاتيح التكامل (الاختبار) من integ-panel.culqi.com، ومفاتيح الإنتاج من mipanel.culqi.com. يستخدم وضع الاختبار مفاتيح الاختبار فقط، ويستخدم الوضع الحي مفاتيح الإنتاج فقط. يجب أن يبدأ كل مفتاح ببادئة حقله. لا يُحفظ المفتاح ذو البادئة الخاطئة: تعرض الصفحة خطأ، مثل Live Secret Key must start with sk_live_ — the previous value was kept.، وتُحفظ الحقول الأخرى.

Test Mode: عند التفعيل، تُستخدم مفاتيح الاختبار (pk_test_ / sk_test_) ولا يُخصم أي مبلغ حقيقي. الافتراضي: مفعّل. أوقفه لقبول المدفوعات الحقيقية بالمفاتيح الحية. وطالما هو مفعّل، يرى العملاء أسفل طريقة الدفع العبارة 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 saved secret keys: حدّد Test Secret Key أو Live Secret Key ثم انقر على Save لإزالته. الحقل الفارغ يُبقي القيمة المحفوظة.

طرق الدفع

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

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

متقدم

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

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

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

الدفع

في خطوة الدفع، يختار العميل طريقة الدفع (افتراضيًا Credit/Debit Card or Yape (Culqi)) وينقر على زر تقديم الطلب. تُفتح نافذة Culqi Checkout المنبثقة في الصفحة نفسها، وتعرض اسم متجرك ومجموع السلة والعملة. هناك يُدخل العميل بيانات البطاقة أو يدفع عبر Yape. ولا تُحمَّل نصوص Culqi إلا في صفحة الدفع.

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

إذا اشترط المصرف 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، لا يُخصم أي مبلغ، ويرى العميل The payment window was closed before the payment was completed. ويمكنه تقديم الطلب مرة أخرى. تبقى السلة محفوظة في كل هذه الحالات. وتُكتب المحاولات الفاشلة في سجل الوحدة، لأنه لا يوجد طلب بعد.

لا تُخصم السلة مرتين أبدًا. إذا أعاد العميل الإرسال أثناء معالجة دفعة لنفس السلة، يرى 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. تُحتفظ عملية الخصم، وتنشئ المحاولة التالية الطلب منها دون خصم جديد.

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

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

حالات الطلب

No order yet: رُفضت البطاقة، أو أغلق العميل نافذة Culqi، أو لم ترد Culqi. لا توجد إلا السلة. تفاصيل الحالة موجودة في سجل الوحدة.

Payment accepted: تم تأكيد عملية الخصم وتطابقها مع السلة. يُسجَّل الدفع بمعرّف عملية خصم Culqi (chr_...) كمعرّف للمعاملة، وتعرض ملاحظة الوضع (اختبار أو حي) وما إذا كان 3-D Secure قد استُخدم.

Culqi payment on hold: أبلغت Culqi عن عملية خصم لا يتطابق مبلغها أو عملتها مع السلة، أو عن دفعة مُصرَّح بها لكنها غير محصّلة. تشرح الملاحظة ذلك وتعرض معرّف عملية الخصم. تُسجَّل عملية الخصم المحصّلة بعملة السلة كدفعة بالمبلغ الذي خُصم فعليًا. تحقق من عملية الخصم في CulqiPanel، ثم أكمل الطلب أو استرد الدفعة.

Refunded: تم استرداد الدفعة بالكامل من خلال الوحدة.

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

كتلة Culqi payment

تعرض صفحة الطلب كتلة Culqi payment تتضمن معرّف عملية الخصم، والمبلغ المخصوم (مع 3-D Secure إن استُخدم)، وشارة Test للمدفوعات التجريبية، وتلميحًا للمراجعة للطلبات المعلّقة، والمبالغ المدفوعة والمستردة، وسجل الاستردادات.

الاستردادات

في كتلة Culqi payment أدخل المبلغ (يُملأ تلقائيًا المبلغ الذي لم يُسترد بعد)، واكتب سببًا اختياريًا، ثم انقر على Refund via Culqi. أكّد السؤال Refund this amount through Culqi? This cannot be undone. الاستردادات الكاملة والجزئية مدعومة. يلزمك حق تعديل الطلبات؛ ولا يلزمك الوصول إلى الوحدات. تُنفَّذ الاستردادات بالمبلغ والعملة اللذين خصمتهما Culqi، لذلك بعد عدم تطابق المبلغ يمكنك الاسترداد حتى المبلغ الذي دفعه العميل فعليًا، لا إجمالي الطلب. يُرسل الاسترداد بمفاتيح الوضع الذي تم فيه الدفع (اختبار أو حي)، حتى لو غيّرت الوضع بعد ذلك، لذلك يجب تعيين المفتاح السري لذلك الوضع. إذا لم تقبل Culqi الاسترداد، تعرض الكتلة الخطأ ولا يُسجَّل أي استرداد. يُضاف الاسترداد الناجح إلى سجل الاستردادات وملاحظات الطلب مع معرّف استرداد Culqi والمبلغ وسببك. الاسترداد الكامل يضع الطلب في حالة Refunded. الاسترداد الجزئي لا يغيّر الحالة.

لا تُنشئ الوحدة إشعارات دائنة (credit slips). أزرار الاسترداد القياسية في PrestaShop على صفحة الطلب لا تعيد الأموال عبر Culqi. الاستردادات التي تتم في CulqiPanel لا تُزامَن مع PrestaShop. حدّث الطلب يدويًا عند الحاجة.

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

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

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

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

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

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

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

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

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

الطلب في حالة Culqi payment on hold بعد الدفع: اقرأ الملاحظة في الطلب. كان المبلغ المخصوم أو عملته مختلفين عن السلة، أو لم تُحصَّل الدفعة. تحقق من عملية الخصم في 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 order is already being paid: كان طلب دفع آخر لنفس السلة قيد التنفيذ في الوقت نفسه. يجب على العميل الانتظار والتحقق من بريده الإلكتروني قبل المحاولة مجددًا.

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

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

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

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

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