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

المتطلبات

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

PHP: 8.0 أو أحدث. لا تُثبَّت الوحدة على إصدارات PHP الأقدم.

العملة: البيزو التشيلي (CLP) أو الدولار الأمريكي (USD). بالنسبة إلى سلال التسوق بعملات أخرى، تُخفى طريقة الدفع في خطوة الدفع. بالنسبة إلى CLP، اضبط دقة عملة CLP على 0 في International > Localization > Currencies، لأن Flow تحصّل بيزو صحيحًا.

حساب Flow: تحتاج إلى API Key وSecret Key لحسابك لدى Flow، وتجدهما في Flow ضمن Mis datos, Datos técnicos. للاختبار، أنشئ حسابًا منفصلًا في بيئة الاختبار على sandbox.flow.cl واستخدم مفاتيحه. مفاتيح بيئة الاختبار ومفاتيح الإنتاج مختلفة. لا يلزم إعداد أي شيء في حساب Flow.

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

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

التثبيت

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

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

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

4. أدخل API Key وSecret Key الخاصين ببيئة الاختبار، وفعّل Enable / Disable، وانقر Save، ثم أجرِ طلب اختبار.

5. لقبول المدفوعات الحقيقية، أدخل مفاتيح الإنتاج وأوقف تفعيل Sandbox mode.

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

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Flow Gateway > Configure. لكل قسم يحتوي على حقول زر Save خاص به، وهو يحفظ الصفحة كاملة. تنبّهك الصفحة فوق الحقول عندما تكون مفاتيح الوضع الحالي فارغة (فيُخفى Flow حينها في خطوة الدفع)، وعندما لا تكون عملة المتجر الافتراضية CLP أو USD، وعندما تحتوي عملة CLP على منازل عشرية (اضبط دقتها على 0 حتى تتطابق الأسعار والإجماليات والاستردادات تمامًا). في وضع Sandbox تعرض الرسالة Sandbox mode — payments go to sandbox.flow.cl, no real money is charged.

Flow.cl

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

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

Description: النص المعروض أسفل طريقة الدفع في خطوة الدفع. الافتراضي: Pay with Webpay, credit or debit card, bank transfer and other methods. You will be redirected to Flow to complete the payment.

بيانات اعتماد Flow API

انسخ API Key وSecret Key من حسابك لدى Flow (Mis datos, Datos técnicos): مفاتيح الإنتاج من www.flow.cl، ومفاتيح بيئة الاختبار من sandbox.flow.cl (حساب منفصل للاختبار).

Sandbox mode: يستخدم بيئة الاختبار لدى Flow (sandbox.flow.cl) ومفاتيحها. لا يُخصم أي مبلغ حقيقي في وضع الاختبار. الافتراضي: on. أوقفه وأدخل مفاتيح الإنتاج لقبول مدفوعات حقيقية. تستخدم الاستردادات دائمًا البيئة التي دُفع فيها الطلب.

Sandbox API Key: API Key لحسابك على sandbox.flow.cl.

Sandbox Secret Key: Secret Key لحسابك على sandbox.flow.cl. يُستخدم لتوقيع كل طلب.

Live API Key: API Key لحسابك على www.flow.cl.

Live Secret Key: Secret Key لحسابك على www.flow.cl. احتفظ به سرًّا.

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

Clear saved keys: ضع علامة على مفتاح وانقر Save لحذفه. يُبقي الحقل الفارغ القيمة المحفوظة.

الإشعارات

ترسل الوحدة ثلاثة عناوين URL إلى Flow مع كل دفعة واسترداد، لذلك لا يلزم إعداد أي شيء في حساب Flow. يسرد حقل Flow URLs في هذا القسم هذه العناوين. مع الروابط الصديقة للبحث تبدو هكذا:

يحمل التأكيد رمز دفع فقط. تبحث الوحدة عن الرمز بين المدفوعات التي أنشأتها، وتسأل Flow عن حالة الدفع بطلب موقّع في البيئة التي أُنشئ فيها الدفع، ولا تطبّق إلا رد Flow. يُرفض أي دفع لم ينشئه هذا المتجر دون الاستعلام من Flow. وإذا لم يصل التأكيد، يُنشأ الطلب عند عودة العميل من Flow.

متقدم

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

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

Delete data on uninstall: عند التفعيل، يؤدي إلغاء تثبيت الوحدة إلى حذف إعداداتها وسجلها. تبقى بيانات Flow المحفوظة في الطلبات. الافتراضي: off.

الدفع

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

بعد الدفع يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكد Flow ذلك: عبر التأكيد أو عبر طلب حالة موقّع عند عودة العميل. عندئذ يُنشأ الطلب، ويرى العميل صفحة تأكيد الطلب القياسية مع الرسالة Your payment with Flow has been received. إذا أنشأ العميل قسيمة Servipag أو Multicaja، يُنشأ الطلب في حالة Awaiting Flow payment، وتعرض الصفحة Your Flow payment coupon was generated. The order will be processed as soon as Flow confirms the payment. إذا فشل دفع طلب القسيمة لاحقًا أو أُلغي، تعرض الصفحة Your Flow payment was not completed. Please contact us about this order. وإذا لم يتطابق المبلغ، تعرض الصفحة Your Flow payment was received and is being reviewed by the shop.

إذا تعذّر الوصول إلى Flow عند عودة العميل، أو إذا كان طلب آخر ينشئ الطلب في تلك اللحظة، تطلب صفحة Payment confirmation من العميل عدم الدفع مرة أخرى، وتعرض الخيارين Check again وBack to checkout.

إذا رُفض الدفع، يعود العميل إلى صفحة الدفع مع الرسالة Your Flow payment was rejected. Please try again or choose another payment method. وإذا غادر العميل صفحة Flow دون أن يدفع، فالرسالة هي The Flow payment was not completed. You can try again or choose another payment method. وإذا تعذّر التحقق من النتيجة، فالرسالة هي We could not confirm your Flow payment yet. If you completed it, you will receive a confirmation e-mail shortly; otherwise please try again. تبقى سلة التسوق محفوظة، وينشئ كل محاولة جديدة دفعًا جديدًا عبر Flow مرتبطًا بالسلة.

إذا تعذّر على Flow بدء الدفع، يبقى العميل في صفحة الدفع مع رسالة قصيرة، مثل Could not connect to Flow. Please try again in a moment. وتوجد التفاصيل في السجل.

إذا توقف قسيمة في السلة عن الصلاحية بين الدفع وتأكيده، تزيله PrestaShop من الطلب. ينتقل الطلب عندئذ إلى Flow payment on hold مع ملاحظة، لأن العميل دفع السعر المخفّض.

تقبل الوحدة مدفوعات لمرة واحدة فقط. لا تتضمن بطاقات محفوظة أو اشتراكات أو رسومًا متكررة أو روابط دفع، ولا تختار مسبقًا طريقة دفع من Flow. لا يمكن لـ Flow إلغاء رابط دفع أُنشئ بالفعل: إذا دفع عميل عبر رابط قديم بعد أن كانت السلة مدفوعة، يحصل الطلب على ملاحظة تطلب منك استرداد الدفعة المكررة في Flow.

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

حالات الطلب

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

Payment accepted: أبلغت Flow أن الدفع تم، وأن المبلغ والعملة متطابقان. يُسجَّل الدفع برقم طلب Flow كمعرّف للمعاملة، وتعرض ملاحظة المبلغ ورقم طلب Flow وطريقة الدفع.

Awaiting Flow payment: أنشأ العميل قسيمة دفع Servipag أو Multicaja. ينتقل الطلب إلى Payment accepted عندما تؤكد Flow الدفع.

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

Payment error: رفضت Flow دفع القسيمة لطلب قيد الانتظار.

Canceled: أُلغي دفع القسيمة لطلب قيد الانتظار في Flow.

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

إذا وصل دفع آخر لطلب مدفوع بالفعل، لا يتغير الطلب. تطلب منك ملاحظة استرداد الدفعة المكررة في حسابك لدى Flow. لا يُعاد فتح الطلب المسترد أبدًا.

كتلة دفع Flow

تعرض صفحة الطلب كتلة Flow payment تتضمن رقم طلب Flow وطريقة الدفع، ومرجع commerceOrder، وحالة الدفع، والمبلغ المدفوع والمسترد، وشارة Sandbox للمدفوعات في بيئة الاختبار، وسجل الاستردادات، وFlow notes الخاصة بالطلب.

الاستردادات

في كتلة Flow payment أدخل المبلغ (يُملأ المبلغ الذي لم يُسترد بعد)، واكتب السبب اختياريًا، ثم انقر Refund via Flow. أكّد السؤال Refund this amount via Flow? Flow e-mails the customer to complete the refund. الاستردادات الكاملة والجزئية مدعومة. تحتاج إلى صلاحية تعديل الطلبات. تقتصر الاستردادات على المبلغ الذي حصّلته Flow فعليًا، لذلك بعد تفاوت في المبلغ يمكنك الاسترداد حتى المبلغ الذي دفعه العميل، لا إجمالي الطلب. يجب أن تكون استردادات CLP بمبالغ صحيحة. يُرسل الاسترداد إلى البيئة التي تم فيها الدفع (الاختبار أو الإنتاج)، لذلك يجب أن تكون مفاتيح تلك البيئة مُدخَلة، ويحتاج العميل إلى بريد إلكتروني صالح. إذا رفضت Flow الاسترداد، تعرض الكتلة الخطأ ولا يُسجَّل أي استرداد. يُضاف الطلب الناجح إلى سجل الاستردادات والملاحظات مع رقم الاسترداد لدى Flow وحالته. يؤدي الاسترداد الكامل إلى وضع الطلب في حالة Refunded. لا يغيّر الاسترداد الجزئي الحالة. تتوفر الاستردادات بعد أن تؤكد Flow الدفع.

تُضاف تغييرات حالة الاسترداد اللاحقة التي تبلغ عنها Flow إلى الملاحظات. إذا رفضت Flow الاسترداد أو ألغته لاحقًا، توضح الملاحظة أن المال لم يُعَد إلى العميل، ويمكن استرداد المبلغ مرة أخرى. لا تُنشئ الوحدة إشعارات ائتمان. أزرار الاسترداد القياسية في PrestaShop في صفحة الطلب لا تعيد الأموال عبر Flow. الاستردادات المنشأة في لوحة تحكم Flow لا تُستورد إلى PrestaShop.

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

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

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

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

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

لا يظهر Flow في صفحة الدفع: تحقّق من أن الترخيص نشط، وأن Enable / Disable مفعّل، وأن مفاتيح الوضع الحالي مملوءة (مفاتيح الاختبار في وضع Sandbox، ومفاتيح الإنتاج في وضع الإنتاج)، وأن عملة السلة هي CLP أو USD. في Payment > Preferences تحقّق من أن الوحدة مسموح بها لعملة السلة وبلد العميل ومجموعة العميل.

تم الدفع لكن لم يُنشأ أي طلب: لم يصل تأكيد Flow إلى متجرك ولم يعد العميل. تحقّق من أن عنوان URL للتأكيد المعروض في Flow URLs يُفتح من الإنترنت ولا تمنعه حماية بكلمة مرور أو جدار حماية. فعّل Debug log وراجع حقل Log في صفحة الوحدة.

يرد التأكيد بـ Payment does not belong to the order: الرمز ليس دفعًا أنشأه هذا المتجر، أو أبلغت Flow عن مرجع آخر له. لا يتغير شيء.

يرد التأكيد بـ Gateway not configured: مفاتيح بيئة الدفع فارغة. أعد إدخالها. ستعيد Flow محاولة التأكيد.

يرد التأكيد بـ Flow API unavailable or Busy, retry: فشل طلب الحالة إلى Flow، أو كان طلب آخر ينشئ الطلب في اللحظة نفسها. ستعيد Flow محاولة التأكيد.

يرى العميل Flow payments are not available at the moment: المفاتيح مفقودة أو رفضتها Flow. تحقّق من API Key وSecret Key للوضع الحالي.

يرى العميل A valid billing email is required for Flow payments: تحتاج Flow إلى البريد الإلكتروني للعميل.

يرى العميل The order total is too small to be paid with Flow: يُقرَّب إجمالي السلة إلى الصفر بعملة السلة.

دفع العميل لكن الطلب في حالة Awaiting Flow payment أو Flow payment on hold: اقرأ الملاحظات في كتلة Flow payment. أنشأ العميل قسيمة دفع نقدي لم تُدفع بعد، أو أن المبلغ أو العملة التي أبلغت عنها Flow لا يتطابقان مع الطلب. تُقرَّب إجماليات CLP ذات المنازل العشرية إلى بيزو صحيح، لذلك اضبط دقة CLP على 0.

يفشل الاسترداد برسالة تخص مفاتيح بيئة الاختبار أو الإنتاج: دُفع الطلب في تلك البيئة، ومفاتيحها فارغة. أدخلها وأعد المحاولة.

يفشل الاسترداد مع Flow accepts CLP refunds in whole units only: أدخل مبلغًا صحيحًا.

للمطوّرين، يسرد ملف README الخطافات actionWcpFlowSupportedCurrencies (العملات التي تُعرض لها طريقة الدفع) وactionWcpFlowPaymentSubject (موضوع الدفع المرسل إلى Flow).

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

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

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