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

المتطلبات

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

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

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

عملة المتجر: البيزو التشيلي (CLP) أو البيزو الأرجنتيني (ARS) أو السول البيروفي (PEN). تُخفى طريقة الدفع في صفحة الدفع عندما يستخدم المتجر، أو يستخدم الطلب في صفحة Pay for order، عملة أخرى.

حساب Khipu: تحتاج إلى معرّف المستلم ("Id de cobrador") ومفتاح API والمفتاح السري ("llave") لحساب التحصيل الخاص بك في Khipu. تجدها في حسابك في Khipu ضمن ملف التاجر (khipu.com/merchant/profile). الثلاثة مطلوبة: بدون المفتاح السري لا يمكن تأكيد أي دفعة.

موقع قابل للوصول: يؤكد Khipu الدفعات عبر استدعاء متجرك، لذا يجب أن يكون الموقع قابلاً للوصول من الإنترنت (دون وضع الصيانة أو مصادقة أساسية أو جدار حماية يحجب Khipu).

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

التثبيت

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

2. انقر Activate.

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

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

5. أدخل Receiver ID وAPI key وSecret key لحساب التحصيل الخاص بك في Khipu (انظر الإعدادات).

6. شغّل Enable / Disable واحفظ. للاختبار أولاً، استخدم مفاتيح حساب مطوّر في Khipu، ثم استبدلها بمفاتيح حساب الإنتاج الخاص بك.

الإعدادات

كل الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > Khipu. تنبّهك الصفحة فوق الحقول عند غياب Receiver ID أو مفتاح API أو المفتاح السري (حينها لا يُعرض Khipu في صفحة الدفع) وعندما تكون عملة المتجر غير مدعومة. وفي قائمة طرق الدفع، يظهر Khipu بحاجة إلى إعداد إلى أن تُدخل المفاتيح الثلاثة.

عام

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

Title: اسم طريقة الدفع الذي يراه العملاء في صفحة الدفع. الافتراضي: Khipu.

Description: النص المعروض أسفل طريقة الدفع في صفحة الدفع. الافتراضي: Pay by bank transfer with Khipu.

حساب Khipu

انسخ Receiver ID ومفتاح API والمفتاح السري من حساب التحصيل الخاص بك في Khipu (khipu.com/merchant/profile). لا يوفّر Khipu خادم اختبار منفصلًا، ولا تحتوي الإضافة على مفتاح لوضع الاختبار. للاختبار، استخدم مفاتيح حساب تحصيل خاص بالمطوّرين ("desarrollo"): فهو يدفع عبر بنك الاختبار DemoBank، ولا تُحوَّل أموال حقيقية. انتقل إلى مفاتيح حساب التحصيل الإنتاجي عند بدء العمل الفعلي.

Receiver ID: معرّف المستلم ("cobrador") في Khipu. تُرفض دفعات حسابات Khipu الأخرى.

API key: يُستخدم لإنشاء الدفعات وللتحقق من كل دفعة مع Khipu.

Secret key: يُستخدم للتحقق من توقيع (HMAC-SHA256) إشعارات الدفع من Khipu. بدونه لا يمكن تأكيد أي دفعة.

إشعارات الدفع

يؤكد Khipu الدفعات عبر استدعاء رابط الإشعار المعروض في هذا القسم من الإعدادات. وهو بهذا الشكل https://your-site/wc-api/webhook_wc_khipu/. يُرسل الرابط تلقائيًا مع كل دفعة، لذا لا يوجد ما تُعدّه في حسابك في Khipu، لكن يجب أن يكون الرابط قابلاً للوصول من الإنترنت.

يجب أن يحمل كل إشعار توقيعًا صالحًا مُنشأً بـSecret key. تُرفض الإشعارات التي لا تحمل توقيعًا صالحًا. بعد ذلك تطلب الإضافة من Khipu حالة الدفعة وتتصرف وفق ما يبلّغ به Khipu:

Status after payment: حالة الطلب بعد أن يؤكد Khipu الدفعة. تُضبط الحالة فورًا، بتغيير حالة واحد ومجموعة واحدة من رسائل البريد الإلكتروني.

متقدم

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

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. تُحفظ بيانات الطلبات (معرّفات دفعات Khipu في الطلبات) دائمًا. الافتراضي: معطّل.

الدفع

يختار العميل طريقة الدفع (افتراضيًا Khipu) ويُتمّ الطلب. تُنشئ الإضافة دفعة Khipu بإجمالي الطلب بعملة الطلب، مع رقم الطلب واسم المتجر والعناصر المطلوبة، وتوجّه العميل إلى صفحة الدفع في Khipu. ويُمرَّر بريد الفوترة إلى Khipu عندما يكون صالحًا. وفي صفحة Khipu يدفع العميل بتحويل بنكي من بنكه ويختار هناك بين أنواع التحويل التي يعرضها Khipu.

بعد الدفع، يعود العميل إلى صفحة استلام الطلب في متجرك. ولا يُعلَّم الطلب كمدفوع إلا بعد أن يؤكد Khipu التحويل: عبر الإشعار الموقّع، أو عبر طلب حالة إلى Khipu عندما يفتح العميل صفحة استلام الطلب. والعودة بحد ذاتها لا تعلّم أي طلب كمدفوع. وإلى أن يُؤكَّد التحويل، تعرض الصفحة Khipu is confirming your bank transfer. Your order will be updated automatically as soon as Khipu confirms the payment, and you will receive an e-mail.

إذا غادر العميل صفحة Khipu دون دفع، يصل إلى صفحة Pay for order مع The Khipu payment was not completed. You can try again or choose another payment method. والمحاولة الجديدة تحذف دفعة Khipu السابقة غير المدفوعة، فلا يعود الرابط القديم قابلاً للدفع. وإذا كان Khipu قد استلم الدفعة السابقة، يُكمَل الطلب ولا تُنشأ دفعة جديدة. وإذا كان التحويل السابق لا يزال قيد التحقق، يرى العميل Your previous Khipu payment for this order is still being verified by the bank. Please wait a few minutes before paying again.

عند تفعيل إدارة المخزون، تنتهي صلاحية دفعة Khipu مع مدة Hold stock (minutes) في WooCommerce، فلا يستطيع العميل دفع طلب أُلغي بالفعل.

إذا لم يتمكن Khipu من إنشاء الدفعة، يرى العميل رسالة قصيرة، مثل Khipu could not create the payment for this order. Please check your billing details and try again, or contact the store. أو Khipu is temporarily unavailable. Please try again in a few minutes. وتُكتب التفاصيل في السجل.

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

تتعامل الإضافة مع دفعات التحويل البنكي لمرة واحدة فقط. لا تُدعم عمليات الاسترداد من WooCommerce، ولا توجد اشتراكات ولا طرق دفع محفوظة ولا تفويض مسبق.

الطلبات

حالات الطلب

Pending payment: أُرسل العميل إلى Khipu ولم يدفع بعد، أو لم يؤكد Khipu التحويل بعد. وتعرض ملاحظة الطلب معرّف دفعة Khipu.

Processing or Completed: أكد Khipu الدفعة. وتتبع الحالة Status after payment. وتعرض ملاحظة الطلب معرّف دفعة Khipu، ومعرّف المعاملة هو معرّف دفعة Khipu.

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

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

عمليات الاسترداد

لا تُرسل عمليات الاسترداد إلى Khipu من WooCommerce. استرد المبلغ للعميل من حسابك في Khipu أو بتحويل بنكي، ثم سجّل الاسترداد في WooCommerce يدويًا.

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

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

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

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

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

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

لا يظهر Khipu في صفحة الدفع: تحقق من أن الترخيص فعّال، وأن Enable / Disable مفعّل، وأن Receiver ID وAPI key وSecret key مُدخلة جميعها. ويجب أن تكون عملة المتجر CLP أو ARS أو PEN. وتعرض صفحة الإعدادات تحذيرًا عند غياب أي منها.

نجحت الدفعة لكن الطلب يبقى Pending payment: يؤكد Khipu التحويل بعد أن يتحقق منه البنك. ويُحدَّث الطلب عند وصول إشعار Khipu أو عند فتح العميل صفحة استلام الطلب. تحقق من أن موقعك قابل للوصول من الإنترنت على رابط الإشعار المعروض في الإعدادات (دون وضع صيانة أو مصادقة أساسية أو جدار حماية يحجب Khipu)، وانظر إلى WooCommerce > Status > Logs، المصدر wcp_khipu_gateway.

يجيب الإشعار Secret key not configured: Secret key فارغ. أدخله. وسيرسل Khipu الإشعار مرة أخرى.

يجيب الإشعار Invalid signature أو Missing signature أو Malformed signature: لا ينتمي Secret key إلى حساب التحصيل الذي تستخدم مفاتيحه، أو أن الطلب لم يأتِ من Khipu.

يجيب الإشعار Payment does not belong to this order: دُفعت الدفعة إلى Receiver ID آخر أو لطلب آخر. تحقق من Receiver ID.

يجيب الإشعار Payment not final yet أو Verification unavailable: لا يزال التحويل قيد التحقق، أو تعذّر الوصول إلى Khipu. وسيرسل Khipu الإشعار مرة أخرى.

الطلب On hold: اقرأ ملاحظة الطلب. لم يطابق المبلغ أو العملة الطلب، أو وصلت الدفعة بعد إلغاء الطلب.

يرى العميل "Khipu payments are not available right now": مفتاح API مفقود أو خاطئ. تحقق من المفاتيح في حسابك في Khipu.

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

إذا كان حسابك في Khipu يقبل عملة أخرى، مثل EUR لـKhipu Spain، يمكن للمطورين إضافتها عبر الفلتر wc_khp_supported_currencies.

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

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

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