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

المتطلبات

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

PHP: 8.0 أو أحدث.

العملة: يجب ضبط الريال البرازيلي (BRL) في System > Localisation > Currencies. تفرض Vindi الرسوم بعملة BRL فقط، لذلك لا تُعرض طريقة الدفع إلا عندما يدفع العميل بعملة BRL.

حساب Vindi: تحتاج إلى مفتاح الواجهة البرمجية لحساب Vindi الخاص بك. بيئة Vindi التجريبية (sandbox) حساب اختبار منفصل لدى Vindi بمفتاح خاص به. ويجب أيضًا تفعيل boleto وPIX وBolePix في حساب Vindi الخاص بك إذا أردت تقديمها.

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

التثبيت

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

OpenCart 3

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

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

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

4. الصق Sandbox API key وعندما تكون جاهزًا، الصق Live API key. اختر Offered methods.

5. انسخ عنوان URL الخاص بالـ webhook من الإعدادات إلى Vindi (راجع الإعدادات).

6. فعّل Enable / Disable وانقر على Save. اختبر دفعة في وضع sandbox، ثم أوقف Sandbox mode لقبول المدفوعات الفعلية.

OpenCart 4

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

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

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

4. أدخل مفتاح الترخيص ومفاتيح API والطرق والـ webhook كما في الخطوات من 3 إلى 6 لـ OpenCart 3. صفحة الإعدادات وحقولها متطابقة في الإصدارين. العنوان الوحيد المختلف هو عنوان الـ webhook (راجع Webhook).

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

الإعدادات

توجد جميع الإعدادات في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox Vindi Gateway > Edit. تُعرض الأقسام في الجهة اليسرى، ويحفظ الزر Save أسفل القائمة الصفحة كاملة. وفوق الإعدادات، تعرض الصفحة الوضع، TEST MODE أو LIVE، وتحذّرك عندما يكون مفتاح API للوضع الحالي فارغًا (فلا تُعرض طريقة الدفع عند الدفع) أو عندما لا تكون العملة الافتراضية للمتجر BRL (فلا تُعرض طريقة الدفع إلا عندما يدفع العميل بعملة BRL). وبدون صلاحية تعديل الإضافة تعرض الصفحة الإعدادات لكنها لا تستطيع حفظها.

عند الحفظ، تُحفظ المفاتيح كما كُتبت، دون مسافات في البداية والنهاية. وإذا لم تُختر أي طريقة دفع، تُحفظ البطاقة الائتمانية وتعرض الصفحة Choose at least one payment method — credit card was selected. ولا يُقبل Title فارغ أو أطول من 128 حرفًا، أو Sort Order ليس عددًا صحيحًا (القيم السالبة مسموح بها)، أو Total ليس رقمًا يساوي 0 أو أكبر، أو منطقة جغرافية أو حالة طلب غير موجودة: لا يُحفظ أي شيء وتعرض الصفحة الرسالة، مثل Enter a title for the payment method (1 to 128 characters).

Vindi

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

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

Description: النص الذي يراه العميل في خطوة Confirm Order فوق حقول الدفع. الافتراضي: Pay by credit card on the secure Vindi page, or by boleto / PIX.

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

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

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

مفاتيح API

أنشئ المفاتيح في لوحة Vindi ضمن Settings > API keys: على app.vindi.com.br للبيئة الحية، وعلى sandbox-app.vindi.com.br لبيئة sandbox. للبيئة الحية وبيئة sandbox مضيفان ومفتاحان منفصلان. تتذكر كل دفعة البيئة التي أُنشئت فيها فاتورتها، لذلك تستخدم عمليات التحقق والإلغاء والاسترداد هذه البيئة دائمًا.

Sandbox mode: ينشئ مدفوعات جديدة في بيئة Vindi التجريبية، باستخدام sandbox-app.vindi.com.br ومفتاح API الخاص بالبيئة التجريبية. يرى العملاء عند الدفع ملاحظة TEST MODE: Vindi sandbox: no real charges. الافتراضي: مفعّل. أوقفه لقبول المدفوعات الفعلية.

Live API key: المفتاح الخاص لحساب Vindi الحي. يُرسل إلى واجهة Vindi البرمجية فقط.

Sandbox API key: المفتاح الخاص لحساب Vindi التجريبي.

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

طرق الدفع

Offered methods: الطرق التي يمكن للعملاء اختيارها. الافتراضي: البطاقة الائتمانية. يجب أن تكون الطرق مفعّلة أيضًا في حساب Vindi الخاص بك.

تحتاج طرق boleto وPIX وBolePix إلى CPF أو CNPJ الخاص بالعميل، ويُطلب عند الدفع.

إشعارات الدفع (webhook)

يُخبر الـ webhook متجرك بأن فاتورة قد دُفعت أو أُلغيت أو رُفضت أو استُردت. يعرض حقل Webhook URL في هذا القسم العنوان. على OpenCart 3 يكون بالشكل https://your-store/index.php?route=extension/payment/wcp_vindi_gateway/webhook&token=...، وعلى OpenCart 4 بالشكل https://your-store/index.php?route=extension/wcp_vindi_gateway/payment/wcp_vindi_gateway.webhook&token=.... ويُبنى من عنوان واجهة متجر تثبيت OpenCart الخاص بك، ويحتوي على رمز سري تُنشئه الإضافة. انسخه تمامًا كما تعرضه الإعدادات. في Vindi انتقل إلى Settings > Webhooks، في الحساب الحي وفي حساب sandbox، وأضف هذا العنوان واختر هذه الأحداث:

لا يوقّع Vindi إشعاراته، لذلك تُرفض الطلبات التي يكون رمزها مفقودًا أو خاطئًا، وكل إشعار لا يجعل الإضافة إلا تعيد قراءة الفاتورة عبر واجهة Vindi البرمجية قبل أن يتغير أي طلب. ويعمل العنوان أيضًا أثناء وضع الصيانة في المتجر (على OpenCart 4 يسمح إجراء بدء التشغيل (startup action) التابع للإضافة بمرور الـ webhook وصفحة حالة الدفع). وليس لفواتير Vindi عنوان URL للعودة، لذلك بدون الـ webhook لا تُلتقط المدفوعات بالبطاقة إلا عندما يؤكد العميل الطلب مرة أخرى بالسلة نفسها (فتُعثر حينها على الفاتورة المدفوعة)، وتُلتقط مدفوعات boleto أو PIX عندما يفتح العميل الطلب مرة أخرى في حسابه (My Account > Order History).

الطلبات

ينشئ OpenCart الطلب في خطوة Confirm Order بلا حالة (طلب مفقود). ولا يحصل الطلب على حالة إلا بعد أن يبلغ Vindi عن الفاتورة؛ وتُقرأ الفاتورة دائمًا من Vindi مرة أخرى. وتحصل طلبات boleto وPIX وBolePix على حالة الانتظار فور إصدار الفاتورة. يسرد كل حقل أدناه حالات طلبات OpenCart لديك. ولا تملك OpenCart حالة احتجاز (On Hold)، لذلك تستخدم حالتا الانتظار والاحتجاز الافتراضي Pending؛ وتميّز ملاحظات الطلب بينهما. يمكنك إنشاء حالاتك الخاصة في System > Localisation > Order Statuses واختيارها هنا.

Order Status After Payment: يُعيَّن بعد دفعة Vindi مُتحقَّق منها. الافتراضي: Processing.

Awaiting Vindi Payment Status: صدرت فاتورة boleto أو PIX أو BolePix عند الدفع؛ وستؤكد Vindi استلام المال لاحقًا. تُضاف بيانات الدفع إلى تعليق السجل الذي يراه العميل. الافتراضي: Pending.

Vindi Payment On Hold Status: الفاتورة قيد المراجعة لدى Vindi، أو أن الفاتورة المدفوعة لا تطابق الطلب (العملة أو المبلغ أو رمز الفاتورة أو عميل Vindi)، أو أنها دُفعت بعد إلغاء الطلب. تشرح ملاحظة السبب. الافتراضي: Pending.

Payment Error Status: رفضت Vindi محاولة دفع لطلب كان في الانتظار. ويستطيع العميل دفع الفاتورة نفسها ما زال؛ وتعيّن الدفعة اللاحقة حالة ما بعد الدفع. الافتراضي: Failed.

Canceled Status: أُلغيت فاتورة الطلب المنتظر في Vindi. عندما تضبط طلبًا من هذه الإضافة على هذه الحالة، تُلغى فاتورة Vindi المعلّقة الخاصة به أيضًا. الافتراضي: Canceled.

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

متقدم

Debug log: يسجل استدعاءات API والإشعارات في الملف wc_vdi_debug.log.php في مجلد سجلات OpenCart (storage/logs، وعلى OpenCart 4 في system/storage/logs). لا يمكن فتح الملف من الويب. تُسجَّل الأخطاء والتحذيرات دائمًا، حتى عندما يكون هذا الخيار معطّلًا. ولا تُسجَّل المفاتيح أو رمز الـ webhook أو بيانات العملاء أبدًا. الافتراضي: معطّل.

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

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

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

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

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

الدفع

في خطوة Payment Method يختار العميل طريقة الدفع (افتراضيًا Vindi). وفي خطوة Confirm Order يرى العميل وصفك. وعندما تُعرض أكثر من طريقة، يعرض مربع الدفع Pay with واختيارًا بين البطاقة الائتمانية وboleto وPIX وBolePix. وعندما تُعرض طريقة boleto أو PIX أو BolePix، يحتوي المربع أيضًا على حقل CPF or CNPJ. وهو مطلوب عندما لا تُعرض البطاقة الائتمانية؛ وإلا يعرض Required for boleto and PIX. ويُملأ الحقل من حقل مخصص للعميل أو من العنوان المسمى CPF أو CNPJ عندما يحتوي على رقم صالح. ويُتحقق من الرقم بأرقام التحقق الخاصة به. وإذا نقص شيء، يرى العميل Please choose how you want to pay with Vindi. أو Please enter a valid CPF or CNPJ. أو Please enter your CPF or CNPJ — it is required for boleto and PIX. وفي OpenCart 4 يختار العميل طريقة الدفع بزر Choose في كتلة طريقة الدفع، في النافذة Payment method options؛ ومربع الدفع بهذه الحقول وزر Confirm Order يظهران في أسفل صفحة الدفع.

عندما ينقر العميل على Confirm Order، تنشئ الإضافة عميلًا في Vindi لهذه السلة من عنوان الدفع، وفاتورة Vindi لإجمالي الطلب بقسط واحد. وتُسمّى الفاتورة في Vindi Order # مع رقم طلب OpenCart.

البطاقة الائتمانية: يُرسل العميل إلى صفحة فاتورة Vindi ويدفع هناك. يبقى الطلب بلا حالة. وليس لدى Vindi عنوان URL للعودة للفواتير، لذلك لا يُعاد العميل تلقائيًا إلى المتجر. يحصل الطلب على حالته عندما تؤكد Vindi الدفع عبر الـ webhook. وإذا أكد العميل الطلب مرة أخرى بالسلة نفسها وكانت الفاتورة مدفوعة بالفعل، يُؤكَّد الطلب المدفوع ويرى العميل صفحة النجاح.

boleto وPIX وBolePix: تُصدر الفاتورة فورًا، ويحصل الطلب على حالة الانتظار، ويصل العميل إلى صفحة نجاح الطلب في OpenCart. وهناك، وفي تفاصيل الطلب في حساب العميل، يعرض قسم Payment رمز QR الخاص بـ PIX، ورمز PIX للنسخ واللصق مع زر Copy code وتاريخ انتهائه، وزر Open boleto. ويحتوي بريد الطلب الإلكتروني وسجل طلبات العميل على رمز PIX ورابط boleto. وإذا لم تُرجع Vindi بيانات boleto أو PIX، تُلغى الفاتورة ويرى العميل خطأً.

لا يُعلَّم الطلب كمدفوع إلا بعد تأكيد Vindi: تقرأ الإضافة الفاتورة من واجهة Vindi البرمجية وتتحقق من العملة، ومن أن الفاتورة تخص الطلب (رمز الفاتورة وعميل Vindi)، ومن أن المبلغ المدفوع يساوي إجمالي الطلب. وتعيد صفحة النجاح وصفحة الطلب في حساب العميل التحقق من الطلب المنتظر عبر الواجهة البرمجية، بحد أقصى مرة كل 15 ثانية. وعندما يُستلم الدفع، تعرض صفحة النجاح Your payment with Vindi has been received. وطالما لم يُؤكَّد الدفع تعرض We are confirming your payment with Vindi. The order will be updated automatically — please do not pay again. وبالنسبة إلى طلب ملغى تعرض This order was cancelled and its Vindi bill can no longer be paid. Please contact us if you have already paid.

طالما لم يُؤكَّد الدفع، تعرض صفحة النجاح وصفحة الطلب في حساب العميل (للطلب المنتظر أو المحتجز) أيضًا زر Check payment status. وهو يتحقق من أحدث فاتورة Vindi للطلب. ويعود الطلب المؤكد أو المنتظر إلى صفحة النجاح ببيانات دفعه. وإذا كانت الفاتورة ما زالت غير مدفوعة، يقول قسم Payment: Your payment has not been completed yet. If you have already paid, the order is confirmed as soon as Vindi reports the payment — please do not pay again. ويحتوي على أزرار Pay at Vindi وCheck again وBack to checkout.

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

يُبقي OpenCart 4 الطلب في صفحة الدفع حتى تُعرض صفحة النجاح. بعد دفعة بطاقة مرفوضة أو فاتورة ملغاة يدفع العميل الطلب نفسه مرة أخرى. وإذا أُغلق ذلك الطلب دون دفع في الأثناء، يُعاد العميل إلى صفحة الدفع، وتدفع الخطوة التالية Confirm Order طلبًا جديدًا: فالطلب الملغى يعرض This order was cancelled and its Vindi bill can no longer be paid. Please contact us if you have already paid.، والطلب الفاشل يعرض Your Vindi payment attempt was rejected. You can try again below.. وفي OpenCart 4 تظهر رسائل صفحة حالة الدفع Payment التي تعيد إلى صفحة الدفع فوق صفحة الدفع نفسها.

إذا تعذّر على Vindi بدء الدفع، يبقى العميل في خطوة Confirm Order ويرى رسالة قصيرة فوق الزر، مثل التحقق من CPF / CNPJ، أو عنوان الفوترة (الشارع والرمز البريدي والمدينة والولاية مطلوبة لـ boleto)، أو البريد الإلكتروني أو رقم الهاتف، أو أن Vindi غير متاحة مؤقتًا. ويُكتب السبب التقني في السجل.

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

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

حالات الطلب

بلا حالة (طلب مفقود): بدأت عملية دفع بالبطاقة ولم تؤكدها Vindi بعد. في Sales > Orders لا تظهر هذه الطلبات إلا عند ضبط مرشح Order Status على Missing Orders. وفي OpenCart 4.1 قد تحمل مثل هذه الطلبات الحالة Voided، التي يضعها OpenCart عند عرض خطوة التأكيد مرة أخرى؛ وتعدّها الإضافة طلبًا بلا حالة.

Awaiting Vindi Payment Status (الافتراضي Pending): دفعة boleto أو PIX أو BolePix في الانتظار. ينتقل الطلب إلى Order Status After Payment عندما تُبلغ Vindi بأن الفاتورة مدفوعة.

Order Status After Payment (الافتراضي Processing): تأكد الدفع. يحصل الطلب على حالته بالطريقة المعتادة في OpenCart، مع رسائل الطلب الإلكترونية المعتادة وتحديث المخزون. تعرض ملاحظة فاتورة Vindi والمبلغ والبيئة.

Vindi Payment On Hold Status (الافتراضي Pending): الفاتورة قيد المراجعة لدى Vindi، أو أن الفاتورة المدفوعة لا تطابق الطلب (العملة أو المبلغ أو رمز الفاتورة أو عميل Vindi)، أو أن الفاتورة دُفعت بعد إلغاء الطلب. وتشرح الملاحظة ذلك. تحقق من الطلب والمخزون، ثم أكمل الطلب أو استرد الدفعة.

Payment Error Status (الافتراضي Failed): رفضت Vindi محاولة دفع لطلب كان في الانتظار. وتعرض الملاحظة السبب من جهة المعالجة إن وُجد. ويستطيع العميل دفع الفاتورة نفسها ما زال، والدفعة اللاحقة تنقل الطلب إلى Order Status After Payment.

Canceled Status (الافتراضي Canceled): أُلغيت فاتورة الطلب المنتظر في Vindi. وعندما تضبط طلبًا على هذه الحالة في OpenCart، تُلغى فاتورة Vindi المعلّقة الخاصة به أيضًا، فلا يمكن دفعها بعد ذلك. وإذا لم يكن ذلك ممكنًا، تطلب منك ملاحظة إلغاء الفاتورة في لوحة Vindi.

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

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

تبويب VibeFox Vindi Gateway

في Sales > Orders افتح طلبًا دُفع عبر Vindi. في أسفل صفحة الطلب، بجوار History وAdditional، يعرض تبويب VibeFox Vindi Gateway الحقول Vindi bill وCharge والبيئة (مع شارة Sandbox لمدفوعات البيئة التجريبية) وPayment method وStatus والمبالغ Paid / refunded ونموذج الاسترداد وسجل الاسترداد وكل Bills of this cart وVindi notes الخاصة بالطلب. ويظهر التبويب للمستخدمين الذين لديهم حق الوصول إلى الإضافة.

الاسترداد

في تبويب VibeFox Vindi Gateway أدخل Amount (يُملأ المبلغ الذي لم يُسترد بعد)، واختياريًا Reason (optional)، ثم انقر على Refund via Vindi. أكّد السؤال Refund this amount through Vindi? This cannot be undone. والاسترداد الكامل والجزئي لمدفوعات البطاقة وPIX مدعوم. تحتاج إلى صلاحية تعديل الإضافة (تُضبط في System > Users > User Groups). يقتصر الاسترداد على المبلغ الذي حصّلته Vindi فعلًا، لذلك بعد وجود فرق يمكنك الاسترداد حتى المبلغ الذي دفعه العميل، لا إجمالي الطلب. ويُرسل الاسترداد في بيئة الدفع (الحية أو التجريبية)، لذلك يجب ضبط مفتاح API لتلك البيئة.

الاسترداد الكامل يلغي الفاتورة أيضًا في Vindi ويضع الطلب في Refunded Status دون إشعار العميل ودون إعادة المنتجات إلى المخزون، كتغيير حالة يدوي. ولا يغيّر الاسترداد الجزئي الحالة. ويُضاف الاسترداد الناجح إلى سجل الاسترداد والملاحظات مع رسوم Vindi والحالة. وإذا رفضت Vindi أو جهة المعالجة الاسترداد، يعرض التبويب الخطأ ولا يُسجَّل أي استرداد. وتكون الاستردادات متاحة بعد أن تُبلغ Vindi بأن الفاتورة مدفوعة.

لا تستطيع Vindi استرداد مدفوعات boleto. ويعرض التبويب Vindi cannot refund boleto payments. Return the money to the customer by bank transfer and record the refund manually.

لا ترجع مرتجعات المنتجات في Sales > Returns أي أموال عبر Vindi. وتصل عمليات الاسترداد التي تُجرى في لوحة Vindi عبر الـ webhook charge_refunded وتُضاف إلى الملاحظات. ولا تتغير حالة الطلب تلقائيًا. حدّثها يدويًا إذا لزم الأمر.

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

تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox Vindi Gateway هي الكتلة الأولى في Extensions > Extensions > Payments > VibeFox Vindi Gateway > Edit، فوق الإعدادات. أدخل المفتاح في License key وانقر على Activate. بعد ذلك تعرض الكتلة المفتاح مقنّعًا، والحالة (مثل تاريخ انتهاء صلاحية الترخيص ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وتحتها سطر Product: opencart-payment-vindi والرابط 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.

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

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

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

لا يظهر Vindi عند الدفع: تحقق من أن الترخيص نشط، وأن Enable / Disable مفعّل، وأن العميل يدفع بعملة BRL، وأن طريقة واحدة على الأقل مختارة في Offered methods، وأن الوضع الحالي لديه مفتاح API: Sandbox API key في وضع sandbox، وLive API key في الوضع الحي. وتعرض صفحة الإعدادات تحذيرًا عندما يكون المفتاح مفقودًا أو عندما لا تكون عملة المتجر BRL. تحقق أيضًا من أن عنوان الدفع ضمن Geo Zone المختارة، وأن الطلب يبلغ Total المحدد في الإعدادات.

تمت عملية الدفع لكن الطلب بقي بلا حالة أو في حالة الانتظار: الـ webhook لا يعمل. في Vindi تحقق من وجود الـ webhook في الحساب الذي تستخدمه (الحي أو التجريبي)، ومن أن عنوانه مطابق تمامًا للعنوان المعروض في الإعدادات، بما في ذلك الرمز، ومن اختيار الأحداث الأربعة.

يرد الـ webhook بـ Forbidden: الرمز في العنوان مفقود أو خاطئ. انسخ العنوان من الإعدادات مرة أخرى.

يرد الـ webhook بـ Verification failed, retry later: تعذّرت قراءة الفاتورة من واجهة Vindi البرمجية (مثلًا أُزيل مفتاح API لتلك البيئة)، أو كانت السلة تُحدَّث بطلب آخر في اللحظة نفسها، أو تعذّر تعيين حالة الطلب. ستعيد Vindi إرسال الإشعار. ويعرض السجل السبب.

يعرض عنوان الـ webhook Method not allowed في المتصفح: هذا طبيعي. يقبل العنوان الطلبات الصادرة من Vindi فقط.

يرى العميل This payment method is temporarily unavailable: رفضت Vindi مفتاح API. تحقق من مفتاح الوضع الحالي.

يرى العميل خطأً بعد Confirm Order: انظر حقل Log في صفحة الإضافة. تُسجَّل الأخطاء حتى عندما يكون Debug log معطّلًا. ولطريقة boleto يجب أن يحتوي عنوان الفوترة على الشارع والرمز البريدي والمدينة والولاية.

الطلب في حالة الاحتجاز: اقرأ الملاحظات في تبويب VibeFox Vindi Gateway (راجع حالات الطلب)، ثم أكمل الطلب أو استرد الدفعة.

طلبات sandbox القديمة بعد التحويل إلى الوضع الحي: تحتفظ كل دفعة ببيئة فاتورتها. وتستمر عمليات التحقق والإلغاء والاسترداد لطلبات sandbox في استخدام مفتاح sandbox طالما بقي في الإعدادات.

يفشل الاسترداد: اقرأ الرسالة. لا يمكن استرداد مدفوعات boleto عبر Vindi، ويجب ضبط مفتاح API لبيئة الدفع. وبدون صلاحية تعديل الإضافة يقول التبويب You do not have permission to refund orders (modify this extension).

للمطورين: قبل إنشاء عميل Vindi والفاتورة، تُطلق الإضافة أحداث OpenCart wc_vdi_customer_request وwc_vdi_bill_request مع بيانات الطلب والطلب نفسه.

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

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

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

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