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

المتطلبات

WordPress: 6.0 أو أحدث.

WooCommerce: 8.0 أو أحدث، مثبّت ومفعّل. لا تُفعَّل الإضافة بدونه.

PHP: 8.0 أو أحدث.

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

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

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

التثبيت

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

2. افتح الإعدادات: WooCommerce > Settings > Payments > Vindi > Manage، أو انقر Settings أسفل اسم الإضافة في صفحة Plugins.

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

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

5. انسخ رابط webhook من الإعدادات إلى Vindi (راجع «الإعدادات»).

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

الإعدادات

جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > Vindi. وفوق الحقول تحذرك الصفحة عندما لا تكون عملة المتجر BRL، أو عندما يكون مفتاح API للوضع الحالي فارغًا. وفي الحالتين لا تظهر طريقة الدفع في صفحة الدفع. وفي قائمة طرق الدفع يُعلَّم Vindi على أنه يحتاج إلى إعداد حتى يكون للوضع الحالي مفتاح API. وعند الحفظ تُقص المسافات الزائدة في المفاتيح، وإذا لم تُختر أي طريقة دفع تُختار البطاقة الائتمانية وتعرض الصفحة Choose at least one payment method — credit card was selected.

عام

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

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 mode: Create new payments in the Vindi sandbox يستخدم sandbox-app.vindi.com.br مع مفتاح API الخاص بـ sandbox. يرى العملاء عند الدفع ملاحظة TEST MODE: Vindi sandbox: no real charges. الافتراضي: on. ألغِ التحديد لقبول المدفوعات الحقيقية.

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

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

طرق الدفع

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

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

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

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

متقدم

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

Delete data on uninstall: Remove the settings, webhook token and logs when the plugin is deleted. الافتراضي: off.

الدفع

يختار العميل طريقة الدفع (افتراضيًا Vindi). وعندما تُعرض أكثر من طريقة، يعرض صندوق الدفع Pay with واختيارًا بين البطاقة الائتمانية وboleto وPIX وBolePix. وعندما تُعرض boleto أو PIX أو BolePix يحتوي الصندوق أيضًا على حقل CPF or CNPJ. ويكون الحقل إلزاميًا عندما تُعرض هذه الطرق وحدها؛ وإلا يظهر Required for boleto and PIX. ويُتحقق من الرقم بأرقام التحقق الخاصة به. وفي صفحة الدفع الكلاسيكية لا يظهر الحقل عندما تكون Brazilian Market on WooCommerce مفعّلة، لأن تلك الإضافة تطلب CPF / CNPJ بالفعل، وعندها تُستخدم بيانات 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 بإجمالي الطلب بقسط واحد.

Credit card: يُرسَل العميل إلى صفحة فاتورة Vindi ويدفع هناك. لا يملك Vindi رابط عودة للفواتير، لذلك لا يعود العميل إلى المتجر تلقائيًا. يُؤكَّد الطلب عبر webhook أو عندما يفتح العميل صفحة استلام الطلب. وما دام الدفع غير مكتمل تعرض تلك الصفحة والطلب في My account الرسالة Your payment has not been completed yet. وزر Pay at Vindi.

Boleto وPIX وBolePix: تُصدر الفاتورة فورًا، ويُضبط الطلب على «قيد الانتظار»، ويصل العميل إلى صفحة استلام الطلب. وهناك، وفي My account > Orders، يعرض قسم Payment رمز PIX QR، ورمز PIX للنسخ واللصق مع زر Copy code وتاريخ انتهائه، وزر Open boleto. وتتضمن رسالة الطلب المعلّق للعميل ورسالة الفاتورة رمز PIX ورابط boleto.

لا يُعلَّم الطلب كمدفوع إلا بعد تأكيد Vindi: تقرأ الإضافة الفاتورة من Vindi API وتتحقق من أنها تخص الطلب (رمز الطلب وعميل Vindi) وأن المبلغ المدفوع يساوي إجمالي الطلب.

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

إذا تعذر على Vindi بدء الدفع يرى العميل رسالة قصيرة، مثل التحقق من CPF / CNPJ أو عنوان الفوترة أو البريد الإلكتروني أو رقم الهاتف، أو أن Vindi غير متاح مؤقتًا. وإذا كان الطلب نفسه يُعالَج بطلب آخر في تلك اللحظة يُطلب من العميل الانتظار لحظة ثم المحاولة مرة أخرى.

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

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

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

حالات الطلب

Pending payment: بدأت عملية دفع بالبطاقة ولم يؤكدها Vindi بعد.

On hold: مدفوعة boleto أو PIX أو BolePix في الانتظار (ملاحظة Awaiting ... payment at Vindi.)، أو فاتورة Vindi قيد المراجعة.

Processing or Completed: تم تأكيد الدفع. تُضبط الحالة بالطريقة القياسية في WooCommerce: «قيد التنفيذ»، أو «مكتمل» للطلبات التي تحتوي على منتجات افتراضية قابلة للتنزيل فقط. تعرض ملاحظة الطلب فاتورة Vindi والمبلغ والبيئة. ومعرّف المعاملة هو معرّف فاتورة Vindi.

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

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

Cancelled: أُلغيت الفاتورة في Vindi، أو أُلغي الطلب بواسطتك أو بواسطة العميل أو بسبب انتهاء مهلة حجز المخزون في WooCommerce. وعند إلغاء طلب في المتجر تُلغى فاتورة Vindi المعلقة الخاصة به أيضًا، فلا يمكن دفعها بعد ذلك. وإذا تعذر ذلك تطلب منك ملاحظة إلغاء الفاتورة من لوحة Vindi. وقبل أن تُلغي مهلة حجز المخزون الطلب تُفحص الفاتورة: إذا دُفعت في الأثناء يُعلَّم الطلب كمدفوع بدلًا من ذلك.

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

الاسترداد

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

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

تصل عمليات الاسترداد التي تُجرى في لوحة Vindi عبر webhook من نوع charge_refunded وتُضاف إلى ملاحظات الطلب. ولا تُسجَّل تلقائيًا كاسترداد في WooCommerce. وإذا لزم الأمر أنشئ استردادًا يدويًا في WooCommerce دون استخدام Refund via Vindi.

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

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

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

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

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

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

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

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

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

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

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

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

الطلب On hold بعد الدفع: اقرأ ملاحظة الطلب. اختلف المبلغ المدفوع أو رمز الطلب أو عميل Vindi عن الطلب، أو وصلت الدفعة بعد إلغاء الطلب. أكمل الطلب أو استرد الدفعة.

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

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

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

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

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

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