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

المتطلبات

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

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

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

حساب Khipu: تحتاج إلى Receiver ID («Id de cobrador») ومفتاح API والمفتاح السري (Secret key) الخاصة بحساب التحصيل في Khipu. تجدها في حسابك في Khipu ضمن ملف التاجر (khipu.com/merchant/profile). المفاتيح الثلاثة مطلوبة كلها: بدون المفتاح السري لا يمكن تأكيد أي دفع. لا تحتاج إلى إعداد أي شيء في حساب Khipu.

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

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

التثبيت

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

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

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

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

5. فعّل Enable / Disable وانقر على Save. للاختبار أولًا، استخدم مفاتيح حساب المطوّر في Khipu، ثم استبدلها بمفاتيح حساب الإنتاج الخاص بك.

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

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Khipu Gateway > Configure. لكل قسم زر Save خاص به، ويحفظ الصفحة كاملة. وفوق الحقول تحذرك الصفحة عندما يكون Receiver ID أو API key أو Secret key مفقودًا (وعندها لا يُعرض Khipu في الدفع)، وعندما لا يكون العملة الافتراضية للمتجر مدعومة من Khipu.

Khipu

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

Title: اسم طريقة الدفع الذي يراه العملاء عند الدفع. وهو أيضًا اسم طريقة الدفع المحفوظ في الطلب. الافتراضي: Khipu. مطلوب.

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

حساب Khipu

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

Receiver ID: معرّف المستلم («cobrador») الخاص بك في Khipu. تُرفض المدفوعات المرسلة إلى حسابات Khipu أخرى.

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

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

لا تُعرض المفاتيح المحفوظة مرة أخرى. يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها.

Clear saved secrets: ضع علامة على API key أو Secret key ثم انقر على Save لحذفه. الحقل الفارغ يُبقي القيمة المحفوظة كما هي.

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

Notification URL: يؤكد Khipu المدفوعات باستدعاء عنوان URL المعروض هنا. مع الروابط الودية يبدو هكذا: https://your-shop/module/wcp_khipu_gateway/webhook، وقد يتضمن رمز اللغة. يُرسل عنوان URL تلقائيًا مع كل دفع، لذلك لا يلزم إعداد أي شيء في حساب Khipu، لكن يجب أن يكون عنوان URL متاحًا من الإنترنت.

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

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

متقدم

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

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

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

الدفع

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

بعد الدفع يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد أن يؤكد Khipu ذلك: إما عبر الإشعار الموقّع، أو عبر طلب حالة إلى Khipu عند عودة العميل. العودة نفسها لا تُعلّم أي شيء كمدفوع. وبعد إنشاء الطلب يرى العميل صفحة تأكيد الطلب القياسية. أما إذا كان البنك لا يزال يتحقق من التحويل أو تعذّر الوصول إلى Khipu، فتظهر صفحة Payment confirmation تتضمن النص Khipu is confirming your bank transfer. Your order will be created automatically as soon as Khipu confirms the payment, and you will receive an e-mail. مع الزرين Check again وBack to checkout. وإذا تعذّر ربط آخر دفع Khipu للسلة بها (على سبيل المثال، إذا كان تابعًا لمعرّف Receiver ID آخر)، يعود العميل إلى الدفع مع الرسالة We could not match this payment to an order. If you paid, please contact us.

إذا غادر العميل صفحة Khipu دون الدفع، أو لم يكتمل الدفع، يعود العميل إلى الدفع مع الرسالة 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 إنشاء الدفع، يبقى العميل عند الدفع مع رسالة قصيرة، مثل 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. وتُكتب التفاصيل في السجل.

تعمل الإشعارات أثناء وضع الصيانة في المتجر، ولا يحجبها تقييد الدول في متجرك.

تقبل الوحدة مدفوعات التحويل البنكي لمرة واحدة فقط. لا تُرسل المبالغ المستردة من PrestaShop إلى Khipu، ولا توفر الوحدة اشتراكات أو طرق دفع محفوظة أو تفويضات مسبقة. ولا ترتبط المدفوعات غير المكتملة بحجز للمخزون.

الطلبات

حالات الطلب

No order yet: أُرسل العميل إلى Khipu ولم يدفع، أو لم يؤكد Khipu التحويل بعد. لا توجد سوى السلة.

Payment accepted or Delivered: أكّد Khipu الدفع. تتبع الحالة Status after payment. يُسجَّل الدفع بمعرّف دفع Khipu كمعرّف للمعاملة، وتعرض ملاحظة Khipu payment verified. Payment ID: مع معرّف الدفع والمبلغ.

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

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

كتلة دفع Khipu

تعرض صفحة الطلب كتلة Khipu payment تضم محاولات دفع Khipu الخاصة بسلة الطلب (التاريخ، والمبلغ، ومعرّف دفع Khipu، وحالة Khipu والنتيجة)، وتحذيرًا Manual review طالما أن الطلب في حالة Khipu payment on hold، وKhipu notes الخاصة بالطلب. الكتلة للقراءة فقط.

المبالغ المستردة

لا تُرسل المبالغ المستردة من PrestaShop إلى Khipu، لأن Khipu لا يوفر استردادًا عبر واجهة API الخاصة به. استرد المبلغ للعميل من حسابك في Khipu أو عبر تحويل بنكي، ثم سجّل الاسترداد يدويًا في PrestaShop.

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

تعمل الوحدة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox Khipu Gateway هي الكتلة الأولى في صفحة Modules > Module Manager > VibeFox Khipu Gateway > Configure، فوق الإعدادات. أدخل المفتاح في License key واضغط Activate. بعد ذلك تعرض الكتلة المفتاح مُخفًى، والحالة (مثلًا التاريخ الذي تبقى فيه الرخصة سارية ونطاقك)، والأزرار Check now لإعادة فحص الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وتحتها السطر Product: presta-payment-khipu والرابط 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.

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

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

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

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

تم الدفع لكن لم يُنشأ أي طلب: يؤكد Khipu التحويل بعد أن يتحقق منه البنك. يُنشأ الطلب عند وصول إشعار Khipu أو عندما ينقر العميل على Check again. تحقّق من أن متجرك متاح من الإنترنت عند عنوان URL المعروض في Notification URL (دون حماية بكلمة مرور أو جدار ناري يحجب Khipu)، وراجع حقل Log في صفحة الوحدة.

يردّ الإشعار بـ Secret key not configured: الحقل Secret key فارغ. أدخله. سيعيد Khipu إرسال الإشعار.

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

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

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

يردّ الإشعار بـ Busy, retry later أو Order could not be created, retry later: كان الطلب يُؤكَّد في الوقت نفسه بطلب آخر، أو تعذّر إنشاء الطلب (مثلًا لأن الوحدة معطّلة). سيعيد Khipu إرسال الإشعار. والسبب موجود في السجل.

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

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

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

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

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

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