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

المتطلبات

WordPress: 6.0 أو أحدث.

WooCommerce: 8.0 أو أحدث، مثبت ومفعّل.

PHP: 8.0 أو أحدث.

عملة المتجر: البيزو التشيلي (CLP) أو الدولار الأمريكي (USD). تُخفى طريقة الدفع في صفحة الدفع للعملات الأخرى. في متاجر CLP، اضبط WooCommerce > Settings > General > Number of decimals على 0 لأن Flow تُحصّل مبالغ صحيحة بالبيزو.

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

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

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

التثبيت

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

2. انقر على Activate.

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

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

5. أدخل API Key وSecret Key لبيئة الاختبار، وفعّل Enable / Disable، واحفظ ثم قدّم طلبًا تجريبيًا.

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

الإعداد

توجد جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > Flow.cl. تعرض الصفحة تنبيهًا فوق الحقول عندما تكون مفاتيح الوضع الحالي فارغة (فتُخفى Flow في صفحة الدفع)، أو تكون عملة المتجر غير مدعومة، أو يستخدم متجر CLP منازل عشرية (تُحصّل Flow مبالغ صحيحة بالبيزو، لذا اضبط Number of decimals على 0 لتتطابق الأسعار والإجماليات والاستردادات تمامًا). في وضع الاختبار، تعرض Sandbox mode — تُرسل المدفوعات إلى sandbox.flow.cl ولا تُخصم أموال حقيقية. في قائمة طرق الدفع، تُعلَّم Flow بأنها تحتاج إلى إعداد حتى تُدخل مفاتيح الوضع الحالي، وتظهر شارة وضع التجربة في وضع الاختبار.

عام

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

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: Use the Flow sandbox (sandbox.flow.cl) and the sandbox keys. لا تُخصم أموال حقيقية في وضع الاختبار. الافتراضي: مفعّل. أوقفه وأدخل مفاتيح الإنتاج لقبول المدفوعات الحقيقية. تستخدم الاستردادات دائمًا البيئة التي دُفع فيها الطلب.

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. احتفظ به سريًا.

الإشعارات

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

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

متقدم

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

Delete data on uninstall: Remove the settings and logs of this plugin when it is deleted (Flow data saved on orders is kept). الافتراضي: معطّل.

إتمام الدفع

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

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

إذا رُفض الدفع، يعود العميل إلى صفحة Pay for order (أو صفحة إتمام الدفع) مع 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. توجد التفاصيل في السجل.

تعمل طريقة الدفع على صفحة الدفع الكلاسيكية وكتلة الدفع وصفحة Pay for order. وهي متوافقة مع WooCommerce High-Performance Order Storage (HPOS). النصوص الموجهة للعميل مترجمة إلى الإسبانية (تشيلي وإسبانيا).

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

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

حالات الطلب

Pending payment: أُرسل العميل إلى Flow ولم يدفع بعد. تعرض ملاحظة الطلب المبلغ ورقم طلب Flow الخاص بالمحاولة.

On hold, awaiting coupon payment: أنشأ العميل قسيمة دفع Servipag أو Multicaja. يتغير الطلب عندما تؤكد Flow الدفع.

Processing: أبلغت Flow بأن الدفع مسدد، والمبلغ والعملة متطابقان (تصبح الطلبات التي تتضمن منتجات افتراضية قابلة للتنزيل فقط مكتملة، وفق سلوك WooCommerce الافتراضي). تعرض ملاحظة الطلب المبلغ ورقم طلب Flow. معرّف معاملة الطلب هو رقم طلب Flow.

On hold, amount/currency mismatch: أبلغت Flow عن مبلغ أو عملة مختلفين عن الطلب. لم يُعلَّم الطلب كمدفوع؛ تحقّق منه يدويًا.

On hold, payment for a cancelled order: وصل دفع لطلب كان قد أُلغي دون دفعه. راجع الطلب واشحنه أو استرد الدفع في Flow.

Failed: رفضت Flow آخر محاولة دفع لطلب غير مدفوع. يمكن للعميل المحاولة مجددًا.

Cancelled: أُلغيت آخر محاولة دفع في Flow.

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

الاستردادات

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

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

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

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

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

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

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

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

لا تظهر Flow في صفحة الدفع: تحقّق من أن الترخيص نشط، وأن Enable / Disable مفعّل، وأن مفاتيح الوضع الحالي مدخلة (مفاتيح الاختبار في وضع الاختبار ومفاتيح الإنتاج في وضع الإنتاج)، وأن عملة المتجر CLP أو USD. تُفحص عملة الطلب في صفحة Pay for order.

نجح الدفع لكن الطلب ما زال Pending payment: لا يصل تأكيد Flow إلى متجرك ولم يعد العميل. تحقّق من أن عنوان URL للتأكيد المعروض في الإعدادات يُفتح من الإنترنت ولا يحظره وضع الصيانة أو حماية بكلمة مرور أو جدار حماية. فعّل Debug log وراجع WooCommerce > Status > Logs، بالمصدر wcp_flow_gateway.

يرد التأكيد برسالة Payment does not belong to the order أو Unknown order: لم يُنشئ هذا المتجر الدفع لهذا الطلب، أو أُنشئ في بيئة أخرى. لا يتغير الطلب.

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

يرد التأكيد برسالة Flow API unavailable: فشل طلب الحالة إلى 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 إلى البريد الإلكتروني للعميل.

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

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

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

للمطورين، يسرد ملف readme المرشح wc_flw_supported_currencies (العملات التي تتاح لها بوابة الدفع).

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

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

Flow علامة تجارية لمالكها المعني. هذه الإضافة ليست تابعة لـ Flow ولا معتمدة منها.