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

المتطلبات

WordPress: الإصدار 5.8 أو أحدث.

WooCommerce: الإصدار 6.0 أو أحدث، مثبّت ومفعّل. ترفض الإضافة التفعيل بدونه.

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

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

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

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

التثبيت

1. في WordPress انتقل إلى Plugins > Add New > Upload Plugin، واختر ملف ZIP الخاص بالإضافة وانقر على Install Now. ويمكنك أيضًا رفع المجلد wcp_culqi_payment إلى /wp-content/plugins/ عبر FTP.

2. انقر على Activate.

3. افتح الإعدادات: WooCommerce > Settings > Payments > Culqi > Manage، أو انقر على Settings أسفل اسم الإضافة في صفحة الإضافات.

4. أدخل مفتاح ترخيص VibeFox في كتلة الترخيص أعلى الصفحة وانقر على Activate.

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

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

7. تأكد من أن عملة المتجر هي PEN أو USD.

الإعداد

توجد جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > Culqi. تعرض الصفحة فوق الحقول الرسالة Test mode is active: the integration keys are used and no real money is charged. ما دام وضع الاختبار مفعّلًا. وتحذّرك عندما تكون البوابة مفعّلة لكن مفاتيح الوضع الحالي مفقودة، وعندما لا تدعم 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. يستخدم وضع الاختبار مفاتيح الاختبار فقط، ويستخدم الوضع الفعلي المفاتيح الفعلية فقط. يجب أن يبدأ كل مفتاح ببادئة حقله. لا يُحفظ المفتاح ذو البادئة الخاطئة: تعرض الصفحة خطأ وتُبقي القيمة السابقة.

Test Mode: Use the Culqi integration (test) environment. عند التفعيل تُستخدم مفاتيح الاختبار (pk_test_ / sk_test_) ولا يُخصم أي مال حقيقي. الافتراضي: مفعّل. ألغِ تحديده لقبول مدفوعات حقيقية بالمفاتيح الفعلية.

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

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

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

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

إذا حدّثت من الإصدار 1.0 فسيُنقل زوج المفاتيح الوحيد في ذلك الإصدار إلى حقول الاختبار أو الإنتاج بحسب بادئته. تحقق من المفاتيح بعد التحديث.

طرق الدفع

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

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

متقدم

Debug log: يكتب Log API requests and payment steps التفاصيل في WooCommerce > Status > Logs، بالمصدر wcp_culqi_payment. تُسجَّل الأخطاء دائمًا. ولا تُسجَّل المفاتيح ولا بيانات البطاقة ولا بيانات العميل أبدًا. الافتراضي: متوقف.

Delete Data on Uninstall: Delete the gateway settings and logs when the plugin is deleted. تعطيل الإضافة لا يحذف أي شيء أبدًا. وتُحفظ دائمًا بيانات Culqi المخزنة في الطلبات. الافتراضي: متوقف.

صفحة الدفع

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

تحوّل Culqi بيانات الدفع إلى رمز لمرة واحدة، ويُرسل نموذج الدفع إلى متجرك مع هذا الرمز. وينشئ خادمك عملية الخصم عبر Culqi Charges API بإجمالي الطلب وبعملة الطلب، مع رقم الطلب في وصف الخصم. ولا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكد 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. ويمكنه إعادة تقديم الطلب.

تعمل طريقة الدفع في صفحة الدفع الكلاسيكية، وفي كتلة الدفع، وفي صفحة Pay for order. وهي متوافقة مع تخزين الطلبات عالي الأداء (HPOS) في WooCommerce.

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

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

حالات الطلب

Pending payment: أُنشئ الطلب لكنه لم يُخصم بعد، أو لم ترد Culqi. وفي هذه الحالة تذكر ملاحظة Culqi did not confirm the charge. ابحث في CulqiPanel عن عملية خصم لهذا الطلب قبل قبول دفعة أخرى.

Processing: تم تأكيد الدفع (الإعداد الافتراضي في WooCommerce؛ وتصبح الطلبات التي تحتوي على منتجات افتراضية قابلة للتنزيل فقط «مكتملة»). تعرض ملاحظة الطلب معرّف عملية الخصم في Culqi، والوضع (اختبار أو فعلي)، وهل استُخدم 3-D Secure. ومعرّف المعاملة هو معرّف عملية الخصم في Culqi.

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

Failed: رُفضت البطاقة. تعرض ملاحظة الطلب السبب ورمز الرفض ومعرّف عملية الخصم. ويمكن للعميل الدفع مجددًا ببطاقة أخرى.

لا يُخصم أبدًا من جديد الطلب المدفوع بالفعل أو الذي لديه عملية خصم من Culqi، بما في ذلك الطلب قيد الانتظار. ويُعالَج طلب دفع واحد فقط لكل طلب في الوقت نفسه.

الاستردادات

افتح الطلب، وانقر على Refund، وأدخل المبلغ، ثم انقر على Refund via Culqi. يُدعم الاسترداد الكامل والجزئي. يُرسل الاسترداد بمفاتيح الوضع الذي تم فيه الدفع (اختبار أو فعلي)، حتى لو بدّلت الوضع منذ ذلك الحين، ولذلك يجب أن يكون المفتاح السري لذلك الوضع مضبوطًا. وإذا لم تقبل Culqi الاسترداد يعرض WooCommerce الخطأ ولا يُسجَّل أي استرداد. ويُضاف الاسترداد الناجح إلى ملاحظات الطلب مع معرّف الاسترداد في Culqi والمبلغ والسبب.

لا تُزامَن الاستردادات التي تتم في CulqiPanel مع WooCommerce. وعند الحاجة، أنشئ استردادًا يدويًا في WooCommerce دون استخدام Refund via Culqi.

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

تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. توجد كتلة الترخيص أعلى WooCommerce > Settings > Payments > Culqi. الصق المفتاح في License key وانقر على Activate. تعرض الكتلة الحالة، مثل تاريخ انتهاء صلاحية الترخيص ونطاقك. استخدم Check now للتحقق من الحالة مرة أخرى، وChange key لإدخال مفتاح آخر، وRemove key لإزالته من هذا الموقع. ويفتح الرابط Manage licenses and domains in your account حسابك في vibefox.net.

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

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

عند انتهاء صلاحية الترخيص تستمر الإضافة في العمل، لكن التحديثات والدعم يتطلبان التجديد. وتُعاد مراجعة الحالة تلقائيًا في الخلفية.

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

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

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

الطلب في حالة 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 غير محظورة في صفحة الدفع الخاصة بك، مثلًا بسبب إضافة تحسين.

يرى العميل This order is already being paid: كان طلب دفع آخر لنفس الطلب قيد التنفيذ في اللحظة نفسها. على العميل الانتظار والتحقق من البريد الإلكتروني قبل المحاولة مرة أخرى.

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

تعرض كتلة الترخيص خطأً: اتبع الرسالة في الكتلة. مثلًا، إذا كان المفتاح مستخدمًا بالفعل على نطاق آخر، فحرّر خانة في حسابك في vibefox.net وانقر على Check now. وإذا تغيّر عنوان الموقع فانقر على Check now لتفعيل المفتاح للنطاق الجديد. وإذا تعذر الوصول إلى خادم التراخيص تستمر الإضافة في العمل بآخر حالة معروفة.

للمطورين، تسرد وثائق الإضافة المرشحات culqi_p_supported_currencies وculqi_p_charge_data وculqi_p_icon وculqi_p_lock_timeout.

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

تعطيل الإضافة يُبقي جميع البيانات. لإزالتها، عطّلها ثم احذفها من صفحة Plugins. يُزال دائمًا مفتاح الترخيص وحالة الترخيص الخاصان بهذه الإضافة. أما إعدادات البوابة والسجلات فلا تُزال إلا إذا كان Delete Data on Uninstall مفعّلًا. وإلا فإنها تبقى لإعادة تثبيت لاحقة. وتحتفظ الطلبات الحالية بملاحظات الدفع ومعرّفات المعاملات.

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