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

المتطلبات

OpenCart: الإصدار 3.0.x (تم الاختبار على 3.0.5.0) أو الإصدار 4.0.2 وما بعده (تم الاختبار على 4.1.0.3).

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

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

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

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

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

التثبيت

التنزيل ملف zip واحد يحتوي على حزم كلا الإصدارين من OpenCart. فكّ ضغطه على جهازك. يحتوي على README.txt وحزمة OpenCart 3 wcp_flow_gateway-oc3-(version).ocmod.zip وحزمة OpenCart 4 wcp_flow_gateway.ocmod.zip. ثبّت فقط الحزمة الخاصة بإصدار OpenCart لديك. مفتاح الترخيص هو نفسه لكلا الإصدارين.

OpenCart 3

1. في لوحة الإدارة، انتقل إلى Extensions > Installer، ثم انقر على Upload، واختر الملف wcp_flow_gateway-oc3-(version).ocmod.zip. لا تحتوي الإضافة على تعديلات OCMOD، لذلك لا حاجة إلى تحديث Extensions > Modifications. وبدلاً من أداة التثبيت، يمكنك أيضاً نسخ محتويات المجلد upload من هذه الحزمة إلى المجلد الجذر لمتجرك.

2. انتقل إلى Extensions > Extensions، واختر النوع Payments. ابحث عن VibeFox Flow Gateway وانقر على Install (الزر الأخضر +). يجب أن يملك مستخدم الإدارة الصلاحية لتعديل قائمة إضافات الدفع.

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

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

5. لقبول مدفوعات حقيقية، أدخل مفاتيح الإنتاج، وأوقف تشغيل Sandbox mode، ثم انقر على Save.

OpenCart 4

1. في لوحة الإدارة، انتقل إلى Extensions > Installer، ثم انقر على Upload، واختر الملف wcp_flow_gateway.ocmod.zip. لا تغيّر اسم الملف: يأخذ OpenCart 4 رمز الإضافة من اسم الملف، ولا تعمل الحزمة إذا أُعيدت تسميتها.

2. تظهر الحزمة في قائمة الإضافات المثبتة في الصفحة نفسها. انقر على Install (الزر الأخضر +) بجوارها.

3. انتقل إلى Extensions > Extensions، واختر النوع Payments. ابحث عن VibeFox Flow Gateway، وانقر على Install (الزر الأخضر +)، ثم على Edit (زر القلم).

4. أدخل مفتاح الترخيص ومفاتيح Flow كما في الخطوات 3 إلى 5 الخاصة بـ OpenCart 3. صفحة الإعدادات وحقولها متطابقة في الإصدارين. الفرق الوحيد هو في روابط Flow URLs (راجع Flow URLs)، فهي تُرسل مع كل دفعة، لذلك لا يلزم تغيير أي شيء في حساب Flow.

تبدأ التثبيتات الجديدة بطريقة الدفع معطّلة ووضع sandbox مفعّلاً.

الإعدادات

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

عند الحفظ، يجب أن يتراوح طول Title بين 1 و128 حرفاً، ويجب أن يكون Sort Order فارغاً أو عدداً صحيحاً، ويجب أن يكون Total فارغاً أو عدداً لا يقل عن 0، ويجب أن توجد المنطقة الجغرافية وحالات الطلب المختارة. وإلا فلن يُحفظ شيء، وتعرض الصفحة ما يجب تصحيحه.

Flow.cl

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

Title: اسم طريقة الدفع الذي يراه العميل في صفحة الدفع. وهو أيضاً الاسم المحفوظ لطريقة الدفع في الطلب. الافتراضي: Flow. إلزامي، حتى 128 حرفاً.

Description: وصف طريقة الدفع الذي يظهر في خطوة Confirm Order، فوق زر التأكيد. الافتراضي: Pay with Webpay, credit or debit card, bank transfer and other methods. You will be redirected to Flow to complete the payment.

Sort Order: موضع Flow بين طرق الدفع في صفحة الدفع. اتركه فارغاً أو أدخل عدداً صحيحاً.

Geo Zone: اعرض Flow فقط لعناوين الدفع الواقعة ضمن المنطقة الجغرافية المختارة. الافتراضي: All zones. تُضبط المناطق الجغرافية في System > Localisation > Geo Zones.

Total: إجمالي الطلب، بالعملة الافتراضية للمتجر، الذي يجب أن يبلغه الطلب قبل عرض Flow. اتركه فارغاً لعرض Flow مهما كان الإجمالي.

بيانات اعتماد واجهة Flow API

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

Sandbox mode: يستخدم بيئة sandbox الخاصة بـ Flow (sandbox.flow.cl) ومفاتيح sandbox. في وضع sandbox لا يُخصم أي مبلغ حقيقي. الافتراضي: مفعّل. أوقفه وأدخل مفاتيح الإنتاج لقبول مدفوعات حقيقية. تستخدم الاستردادات دائماً البيئة التي دُفع فيها الطلب. وطالما هو مفعّل، يرى العملاء في خطوة Confirm Order النص SANDBOX MODE — Payments go to the Flow sandbox. No real charges.

Sandbox API Key: مفتاح API الخاص بحسابك على sandbox.flow.cl.

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

Live API Key: مفتاح API الخاص بحسابك على www.flow.cl.

Live Secret Key: مفتاح Secret Key الخاص بحسابك على www.flow.cl. احفظه في مكان آمن.

لا تُعرض المفاتيح المحفوظة مرة أخرى. يبقى الحقل فارغاً ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها. ولحذف مفتاح محفوظ، ضع علامة على Clear the saved key on save أسفل الحقل، ثم انقر على Save.

الإشعارات

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

في OpenCart 4 يستخدم المسار نقطة بدلاً من الشرطة المائلة: https://your-store/index.php?route=extension/wcp_flow_gateway/payment/wcp_flow_gateway.confirmation و….back و….refundCallback.

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

الطلبات

ينشئ OpenCart الطلب في خطوة Confirm Order بدون حالة (طلب مفقود، «missing order»). ولا يحصل الطلب على حالة إلا بعد أن يُبلغ Flow عن الدفع، إما بالتأكيد أو بعودة العميل. وتُقرأ الحالة دائماً من Flow بطلب موقّع. يسرد كل حقل أدناه حالات طلبات OpenCart الخاصة بك.

Order Status After Payment: الحالة التي تُعيَّن بعد دفعة Flow موثّقة. الافتراضي: المعالجة.

Awaiting Flow Payment Status: أنشأ العميل قسيمة دفع نقدي (Servipag وMulticaja وما شابهها). يصل المال لاحقاً، ويؤكده Flow. الافتراضي: قيد الانتظار.

Flow Payment On Hold Status: تم الدفع، لكن المبلغ أو العملة لا يطابقان الطلب، أو وصل المال عن طلب مُلغى. تشرح ملاحظة السبب؛ تحقق من الدفع يدوياً. الافتراضي: قيد الانتظار، لأن OpenCart لا يملك حالة «On hold». يمكنك إنشاء حالتك الخاصة في System > Localisation > Order Statuses واختيارها هنا.

Payment Rejected Status: طلب ينتظر دفع القسيمة، ورُفض دفع Flow الخاص به. الافتراضي: فشل.

Payment Annulled Status: طلب ينتظر دفع القسيمة، أُلغي دفع Flow الخاص به (annulled). الافتراضي: ملغى.

Refunded Status: تُعيَّن بعد استرداد الدفع بالكامل من صفحة الطلب. الافتراضي: مسترد.

خيارات متقدمة

Debug log: يكتب استدعاءات API والإشعارات في الملف flw_p_debug.log.php داخل مجلد سجلات OpenCart (storage/logs). لا يمكن فتح الملف من الويب، وعند بلوغه 5 MB يُنقل إلى flw_p_debug.old.log.php. لا تُسجَّل المفاتيح والتوقيعات وبيانات العملاء أبداً. تُسجَّل الأخطاء دائماً حتى عندما يكون الخيار معطّلاً. الافتراضي: معطّل.

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

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

الاستيراد / التصدير

Export: Download JSON يحفظ الإعدادات في ملف JSON. لا تُصدَّر مفاتيح API Keys ومفاتيح Secret Keys.

Import: الصق ملف JSON مُصدَّراً سابقاً، ثم انقر على Import لاستعادة الإعدادات. تبقى المفاتيح المحفوظة كما هي.

الدفع

في خطوة Payment Method يختار العميل طريقة الدفع (افتراضياً Flow). وفي خطوة Confirm Order يرى العميل وصفك والملاحظة You will be redirected to Flow to complete the payment. ينشئ OpenCart الطلب في هذه الخطوة، ولا يزال بدون حالة. في OpenCart 4 يختار العميل طريقة الدفع بزر Choose في كتلة طريقة الدفع، في النافذة Payment method options، وينقر على Confirm Order في أسفل صفحة الدفع. وعندما ينقر العميل على Confirm Order، تنشئ الإضافة دفعة Flow بإجمالي الطلب بعملة الطلب، بموضوع Order # متبوعاً برقم الطلب واسم المتجر، وتوجّه العميل إلى صفحة دفع Flow. يُمرَّر بريد العميل الإلكتروني إلى Flow. وهناك يختار العميل طريقة دفع مفعّلة في حسابك لدى Flow. ويحصل الطلب على الملاحظة Flow payment started مع المبلغ ورقم طلب Flow والبيئة.

بعد الدفع يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد أن يؤكد Flow ذلك: عن طريق التأكيد، أو عن طريق طلب حالة موقّع عند عودة العميل. ثم يحصل الطلب على حالته بالطريقة المعتادة في OpenCart، مع رسائل الطلب المعتادة وتحديث المخزون، ويرى العميل صفحة نجاح الطلب في OpenCart. وإذا أنشأ العميل قسيمة Servipag أو Multicaja، يحصل الطلب على Awaiting Flow Payment Status، وتعرض الصفحة أيضاً Your Flow payment coupon was generated. The order will be processed as soon as Flow confirms the payment. وإذا لم يتطابق المبلغ، تعرض الصفحة Your Flow payment was received and is being reviewed by the store.

إذا تعذر الوصول إلى Flow عند عودة العميل، أو إذا كان طلب آخر يؤكد الطلب في تلك اللحظة، تظهر صفحة Payment confirmation تعرض We could not confirm your Flow payment yet. If you completed it, you will receive a confirmation e-mail shortly — please do not pay again. مع زر 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. وتبقى السلة محفوظة. في OpenCart 4 تظهر هذه الرسائل أعلى صفحة الدفع.

يمكن للعميل أن يحاول مرة أخرى. ينشئ OpenCart 3 طلباً جديداً في كل مرة تظهر فيها خطوة Confirm Order، أما OpenCart 4 فيُحدّث طلب الدفع الحالي، فتدفع المحاولة الجديدة الطلب نفسه بدفعة Flow جديدة. ولا يستطيع Flow إلغاء دفع بدأ بالفعل. لذلك قبل أي دفع جديد، تُفحص لدى Flow المدفوعات المفتوحة لهذا الطلب ولطلبات أخرى من السلة نفسها خلال اليومين الأخيرين. فإن كان أحدها مدفوعاً أو لديه قسيمة، ينتقل العميل إلى صفحة النجاح بدلاً من الدفع مجدداً. وإذا كان طلب آخر من السلة نفسها قد دُفع بالفعل عبر Flow، فلن يُبدأ دفع جديد أيضاً. وإذا دُفعت السلة نفسها مرتين، كأن يكون ذلك في تبويبين من المتصفح، فإن الدفعة الأولى فقط هي التي تمنح طلبها حالة: يبقى الطلب الآخر بدون حالة، ويحصل الطلب المدفوع على ملاحظة تطلب منك استرداد الدفعة الثانية في حسابك لدى Flow.

يحتفظ OpenCart 4 بالطلب في صفحة الدفع حتى تظهر صفحة النجاح. وإذا أُغلق ذلك الطلب دون دفع في الأثناء (مثلاً إذا ألغيته)، يُعاد العميل إلى صفحة الدفع مع الرسالة The Flow payment was not completed. You can try again or choose another payment method.، وتدفع خطوة Confirm Order التالية طلباً جديداً للسلة. وإذا كان ذلك الطلب مدفوعاً بالفعل أو لديه قسيمة، لكن السلة تغيّرت بعد ذلك، بما في ذلك الكمية، يُعاد العميل إلى صفحة الدفع، وتدفع خطوة Confirm Order التالية السلة الجديدة بطلب جديد. ولا يظهر الطلب المدفوع أبداً كمدفوع لسلة مختلفة.

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

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

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

حالات الطلب

بدون حالة (missing order): أُرسل العميل إلى Flow ولم يدفع، أو رُفض الدفع أو لم يكتمل، أو لم يؤكد Flow الدفع بعد. وفي Sales > Orders لا تظهر هذه الطلبات إلا عند ضبط الفلتر Order Status على Missing Orders.

Order Status After Payment (default Processing): أبلغ Flow أن الدفع مدفوع، وأن المبلغ والعملة متطابقان. تعرض الملاحظة المبلغ ورقم طلب Flow.

Awaiting Flow Payment Status (default Pending): أنشأ العميل قسيمة دفع نقدي. تذكر الملاحظة نوع القسيمة. ينتقل الطلب إلى Order Status After Payment عندما يؤكد Flow الدفع.

Flow Payment On Hold Status (default Pending): أبلغ Flow عن مبلغ أو عملة يختلفان عن إجمالي الطلب، أو وصلت دفعة لطلب مُلغى. يُسجَّل المبلغ الذي حصّله Flow، وتشرح الملاحظة ذلك. تحقق من الطلب ثم أرسله أو استرد الدفعة.

Payment Rejected Status (default Failed): رفض Flow دفع القسيمة لطلب معلّق.

Payment Annulled Status (default Canceled): أُلغي دفع القسيمة لطلب معلّق في Flow.

Refunded Status (default Refunded): استُرد الدفع بالكامل عبر الإضافة.

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

الملاحظات مدخلات في History الطلب، ولا يراها العميل.

تبويب VibeFox Flow Gateway

في Sales > Orders افتح طلباً مدفوعاً عبر Flow. في أسفل صفحة الطلب، بجوار History وAdditional، يعرض تبويب VibeFox Flow Gateway رقم Flow order مع طريقة الدفع، وعلامة Sandbox لدفعات sandbox، والمرجع commerceOrder (وعدد المحاولات)، وStatus الدفع، والمبالغ Paid / refunded، ونموذج الاسترداد، وسجل الاستردادات، وFlow notes الخاصة بالطلب. يظهر التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة.

الاستردادات

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

تُضاف تغييرات الحالة اللاحقة للاسترداد التي يبلغ عنها Flow إلى الملاحظات. وإذا رفض Flow الاسترداد أو ألغاه لاحقاً، توضح الملاحظة أن المال لم يُعَد إلى العميل، ويمكن استرداد المبلغ من جديد. ولا تعيد مرتجعات المنتجات في Sales > Returns أي أموال عبر Flow. ولا تُستورد الاستردادات التي أُنشئت في لوحة Flow إلى OpenCart.

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

تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox Flow Gateway هي الكتلة الأولى في Extensions > Extensions > Payments > VibeFox Flow Gateway > Edit، فوق الإعدادات. الصق المفتاح في License key وانقر على Activate. بعد ذلك تعرض الكتلة المفتاح مخفياً جزئياً، والحالة (مثل تاريخ انتهاء صلاحية الترخيص ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وأسفلها سطر Product: opencart-payment-flow ورابط Manage licenses and domains in your account الذي يفتح حسابك على vibefox.net. لا يستطيع تغيير المفتاح إلا مستخدمو الإدارة الذين لديهم صلاحية Modify على الإضافة. وتتبع نصوص الكتلة لغة الإدارة (وتشمل الإنجليزية والروسية).

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

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

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

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

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

لا يظهر Flow في صفحة الدفع: تحقق من أن الترخيص نشط، وأن Enable / Disable مفعّل، وأن مفاتيح الوضع الحالي معبأة (مفاتيح sandbox في وضع sandbox، ومفاتيح الإنتاج في وضع الإنتاج)، وأن عملة الدفع CLP أو USD. وتحقق أيضاً من أن عنوان الدفع ضمن Geo Zone المختارة، وأن الطلب يبلغ Total المضبوط في الإعدادات.

تمت عملية الدفع، لكن الطلب بقي بدون حالة: تأكيد Flow لا يصل إلى متجرك، ولم يعد العميل. تحقق من أن رابط التأكيد الظاهر في 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 للوضع الحالي.

يرى العميل This payment method is not available. Please reload the checkout page.: جلسة الدفع لم تعد تطابق الطلب، أو أُوقفت طريقة الدفع في هذه الأثناء. يعيد العميل تحميل صفحة الدفع.

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

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

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

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

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

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

للمطورين: تُطلق الإضافة أحداث OpenCart wc_flw_supported_currencies (العملات التي تُعرض لها طريقة الدفع) وwc_flw_payment_subject (موضوع الدفع المرسل إلى Flow).

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

انتقل إلى Extensions > Extensions، واختر النوع Payments، ثم انقر على Uninstall (الزر الأحمر −) بجوار VibeFox Flow Gateway. يُحذف دائماً مفتاح ترخيص هذه الإضافة وحالة ترخيصها. ويحذف OpenCart دائماً إعدادات الإضافة الخاصة به: Enable / Disable وSort Order وGeo Zone وTotal، وحالات الطلبات في قسم Orders، وتعود هذه إلى قيمها الافتراضية عند إعادة التثبيت. كما يُحذف حدث OpenCart الخاص بالإضافة (وفي OpenCart 4 أيضاً أحداثها وإجراء بدء التشغيل الخاص بها، الذي يسمح بمرور روابط Flow URLs في وضع الصيانة). وإذا كان Delete data on uninstall مفعّلاً، تُحذف الإعدادات الأخرى (العنوان والوصف ووضع sandbox والمفاتيح ومفتاح سجل التصحيح) والسجل. وإذا كان معطّلاً، تُحفظ لإعادة التثبيت لاحقاً. وتُحفظ سجلات دفعات Flow واستردادها دائماً، لذلك يمكن استرداد الطلبات التي دُفعت سابقاً بعد إعادة التثبيت. وتحتفظ الطلبات الموجودة بملاحظات الدفع الخاصة بها.

في OpenCart 4، ولإزالة ملفات الإضافة أيضاً، انتقل إلى Extensions > Installer بعد إلغاء التثبيت، وانقر على Uninstall (الزر البرتقالي −) بجوار VibeFox Flow Gateway في قائمة الإضافات المثبتة، ثم على Delete (زر سلة المهملات الأحمر) لحذف الحزمة المرفوعة.

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