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

المتطلبات

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

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

عملة المتجر: الريال البرازيلي (BRL). تحصّل Vindi بعملة BRL فقط، لذلك تُخفى طريقة الدفع عن السلات بأي عملة أخرى.

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

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

التثبيت

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

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

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

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

5. انسخ رابط webhook من الإعدادات والصقه في Vindi (راجع الإعداد).

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

عند التثبيت تُنشئ الوحدة حالتين للطلب: Awaiting Vindi payment وVindi payment on hold. يوفر PrestaShop وحدة دفع جديدة لجميع العملات والدول ومجموعات العملاء. يمكنك تقييدها من Payment > Preferences؛ ويجب أن تكون الوحدة مسموحًا بها لعملة BRL هناك.

الإعداد

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Vindi Gateway > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كاملة. وفوق الحقول تحذرك الصفحة عندما لا تكون عملة المتجر BRL، أو عندما يكون مفتاح API للوضع الحالي فارغًا. وفي الحالتين لا تظهر طريقة الدفع عند الدفع. وعند الحفظ تُزال المسافات الزائدة من بداية المفاتيح ونهايتها. وإذا لم تُختر أي طريقة دفع تُحدَّد البطاقة الائتمانية وتعرض الصفحة Choose at least one payment method — credit card was selected. ولا يُحفظ حقل Title الفارغ: فتعرض الصفحة Enter a title for the payment method.

Vindi

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

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

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

مفاتيح API

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

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

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

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

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

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

طرق الدفع

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

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

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

يُخبر webhook متجرك بأن الفاتورة قد دُفعت أو أُلغيت أو رُفضت أو استُردت. يعرض حقل Webhook URL في هذا القسم الرابط. وعند تفعيل الروابط الودية يبدو بهذا الشكل: https://your-shop/module/wcp_vindi_gateway/webhook?token=... ويحتوي على رمز سري تنشئه الوحدة. انسخه تمامًا كما تعرضه الإعدادات. في Vindi انتقل إلى Settings > Webhooks، في حساب الإنتاج وفي حساب sandbox، أضف هذا الرابط واختر هذه الأحداث:

لا توقّع Vindi إشعاراتها، لذلك تُرفض الطلبات التي يكون فيها الرمز مفقودًا أو خاطئًا، وكل إشعار يجعل الوحدة تعيد قراءة الفاتورة عبر Vindi API قبل أن يتغير أي طلب. وبدون webhook لا تُكتشف مدفوعات البطاقة إلا عندما يعيد العميل تقديم الطلب بالسلة نفسها (فتُوجد الفاتورة المدفوعة ويُنشأ الطلب)، وتُكتشف مدفوعات boleto أو PIX عندما يعيد العميل فتح صفحة تأكيد الطلب.

متقدم

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

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

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

الدفع

يختار العميل طريقة الدفع (افتراضيًا Vindi). وعندما تُعرض أكثر من طريقة يعرض مربع الدفع Pay with واختيارًا بين البطاقة الائتمانية وboleto وPIX وBolePix. وعند عرض boleto أو PIX أو BolePix يحتوي المربع أيضًا على حقل CPF or CNPJ. وهو إلزامي عندما لا تُعرض البطاقة الائتمانية؛ وفي غير ذلك يعرض Required for boleto and PIX. يُملأ الحقل من Identification number أو رقم VAT في عنوان الفوترة عندما يحتوي على 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.

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

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

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

لا يُعلَّم الطلب كمدفوع إلا بعد تأكيد Vindi: تقرأ الوحدة الفاتورة من Vindi API وتتحقق من العملة، ومن أن الفاتورة تخص السلة (رمز السلة وعميل Vindi)، ومن أن المبلغ المدفوع يساوي إجمالي الطلب. وتعيد صفحة تأكيد الطلب فحص الطلب المنتظر عبر API، بحد أقصى كل 15 ثانية. وعند استلام الدفعة تعرض Your payment with Vindi has been received. وأثناء مراجعة الفاتورة لدى Vindi تعرض 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.

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

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

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

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

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

حالات الطلب

No order yet: بدأت دفعة بالبطاقة ولم تؤكدها Vindi بعد. لا توجد إلا السلة.

Awaiting Vindi payment: دفعة boleto أو PIX أو BolePix في الانتظار (ملاحظة Awaiting ... payment at Vindi.). ينتقل الطلب إلى Payment accepted عندما تبلغ Vindi بأن الفاتورة مدفوعة.

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

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

Payment error: رفضت Vindi محاولة الدفع لطلب منتظر. تعرض الملاحظة سبب الرفض من جهة المعالجة إن وُجد. ويستطيع العميل أن يدفع الفاتورة نفسها، وتنقل دفعة لاحقة الطلب إلى Payment accepted.

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

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

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

كتلة الدفع في Vindi

تعرض صفحة الطلب كتلة Vindi payment تتضمن فاتورة Vindi والخصم، والبيئة (مع شارة Sandbox لمدفوعات sandbox)، وطريقة الدفع، والحالة، والمبلغ المدفوع والمسترد، وسجل الاسترداد، وجميع Bills of this cart وVindi notes الخاصة بالطلب.

الاستردادات

في كتلة Vindi payment أدخل المبلغ (يُملأ المبلغ الذي لم يُسترد بعد)، واختياريًا السبب، ثم انقر على Refund via Vindi. أكّد السؤال Refund this amount through Vindi? This cannot be undone. الاستردادات الكاملة والجزئية لمدفوعات البطاقة وPIX مدعومة. تحتاج إلى صلاحية تعديل الطلبات؛ ولا يلزمك الوصول إلى صفحات الوحدات. تُقيَّد الاستردادات بالمبلغ الذي حصّلته Vindi فعليًا، لذلك بعد أي تضارب يمكنك الاسترداد حتى المبلغ الذي دفعه العميل، لا إجمالي الطلب. يُرسل الاسترداد في بيئة الدفعة (الإنتاج أو sandbox)، لذلك يجب ضبط مفتاح API لتلك البيئة. ويلغي الاسترداد الكامل الفاتورة في Vindi أيضًا ويضع الطلب في Refunded؛ أما الاسترداد الجزئي فلا يغيّر الحالة. ويُضاف الاسترداد الناجح إلى سجل الاسترداد والملاحظات مع خصم Vindi والحالة. وإذا رفضت Vindi أو جهة المعالجة الاسترداد، تعرض الكتلة الخطأ ولا يُسجَّل أي استرداد. الاستردادات متاحة بعد أن تبلغ Vindi بأن الفاتورة مدفوعة.

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

لا تُنشئ الوحدة إشعارات دائنة (credit slips). أزرار الاسترداد القياسية في PrestaShop على صفحة الطلب لا ترسل الأموال عبر Vindi. وتصل الاستردادات التي تتم في لوحة Vindi عبر webhook من نوع charge_refunded وتُضاف إلى الملاحظات. ولا تتغير حالة الطلب تلقائيًا؛ سجّلها في PrestaShop باسترداد يدوي إذا لزم الأمر.

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

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

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

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

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

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

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

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

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

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

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

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

الطلب في Vindi payment on hold: اقرأ الملاحظات في كتلة Vindi payment (انظر حالات الطلب)، ثم أكمل الطلب أو استرد الدفعة.

طلبات sandbox القديمة بعد التحويل إلى الإنتاج: تحتفظ كل دفعة ببيئة فاتورتها. وتستمر فحوص الطلبات التجريبية وإلغاؤها واستردادها في استخدام مفتاح sandbox ما دام موجودًا في الإعدادات.

يفشل الاسترداد: اقرأ الرسالة. لا يمكن استرداد مدفوعات boleto عبر Vindi، ويجب ضبط مفتاح API لبيئة الدفعة.

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

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

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