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

المتطلبات

WordPress: 6.0 أو أحدث.

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

PHP: 8.0 أو أحدث.

العملة: اليورو (EUR) فقط. تُخفى طريقة الدفع عندما لا تكون عملة المتجر أو الطلب EUR. تقبل ifthenpay إجماليات من 0.01 إلى 99,999.99 EUR.

حساب ifthenpay: سجّل في ifthenpay.com. تحتاج إلى مفتاح الطريقة التي تقدمها: Multibanco أو MB WAY أو Credit Card (الصيغة ABC-123456). تظهر المفاتيح في الواجهة الخلفية لـ ifthenpay (backoffice.ifthenpay.com) أو ترسلها ifthenpay عند تفعيل الطريقة لحسابك. يجب أن تفعّل ifthenpay أيضًا الـ callback لمفتاحك (راجع الإعدادات)، ويجب أن يكون متجرك متاحًا من الإنترنت.

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

التثبيت

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

2. انقر Activate. تُنشئ الإضافة مفتاح مكافحة التصيد الخاص بها.

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

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

5. اختر Payment Method وأدخل مفتاح ifthenpay الخاص به. احفظ حتى تتطابق Callback URL مع الطريقة المختارة.

6. انسخ Anti-phishing Key وCallback URL المعروضين في الإعدادات، واطلب من ifthenpay تفعيل الـ callback لمفتاحك (في الواجهة الخلفية أو عبر دعم ifthenpay).

7. فعّل Enable/Disable.

الإعدادات

جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > ifthenpay. من دون مفتاح الطريقة المختارة لا تظهر طريقة الدفع عند الدفع، وتُعلَّم في قائمة طرق الدفع على أنها تحتاج إلى إجراء. عند حفظ بوابة مفعّلة من دون هذا المفتاح، تعرض الصفحة ifthenpay: enter the key of the selected payment method, otherwise the method is not shown at checkout.

Enable/Disable: Enable ifthenpay Payment يشغّل طريقة الدفع أو يوقفها. الافتراضي: إيقاف.

Title: عنوان طريقة الدفع الذي يظهر عند الدفع. الافتراضي: ifthenpay.

Description: وصف طريقة الدفع الذي يظهر عند الدفع. الافتراضي: Pay via Multibanco, MB WAY or Credit Card. غيّره ليتطابق مع الطريقة التي تقدمها.

Payment Method: الطريقة التي تُعرض عند الدفع. مفتاح هذه الطريقة وحده مطلوب.

مفاتيح ifthenpay

تُعرض المفاتيح (الصيغة ABC-123456) في الواجهة الخلفية لـ ifthenpay، أو ترسلها ifthenpay عند تفعيل طريقة الدفع لحسابك.

Multibanco Key: مفتاح ifthenpay Multibanco (MB) الخاص بك للمراجع الديناميكية.

MB WAY Key: مفتاح ifthenpay MB WAY الخاص بك.

Credit Card Key: مفتاح ifthenpay Credit Card الخاص بك. كما يتحقق من توقيع عودة العميل من صفحة البطاقة.

الـ callback (إشعارات الدفع)

يخبر الـ callback متجرك بأنه تم دفع مبلغ. اطلب من ifthenpay تفعيل الـ callback لكل مفتاح تستخدمه، مع مفتاح مكافحة التصيد وعنوان الـ callback الموضحين أدناه. تُؤكَّد طلبات Multibanco وMB WAY بالـ callback وحده؛ أما مدفوعات البطاقة فتُؤكَّد أيضًا بالعودة الموقعة من صفحة البطاقة.

Anti-phishing Key: تُنشئه الإضافة، ويُعرض للنسخ. ترسله ifthenpay مع كل callback؛ والـ callback الذي لا يتضمنه يُرفض.

Callback URL: عنوان الـ callback للطريقة المختارة، مع العناصر النائبة الخاصة بـ ifthenpay، ويُعرض للنسخ. يبدأ بـ https://your-site/wc-api/ifthenpay_payment_callback/ ويتبعه معاملات الطريقة. انسخ العنوان كاملًا كما تعرضه الإعدادات تمامًا.

يُقارَن مفتاح مكافحة التصيد في كل callback بمفتاحك. المفتاح المفقود أو الخاطئ يتلقى الرد 403، ولا يتغير الطلب. يجب أن يطابق الـ callback أيضًا طلبًا من هذه البوابة: في Multibanco بالكيان والمرجع، وفي MB WAY بالطلب وأحد طلبات MB WAY الخاصة به، وفي Credit Card بالطلب وطلب البطاقة الخاص به. من دون callback يعمل، لا تُؤكَّد طلبات Multibanco وMB WAY أبدًا، ولا تُؤكَّد مدفوعات البطاقة إلا بالعودة الموقعة.

متقدم

Test Mode: Enable test/sandbox mode. تستخدم بطاقة الائتمان وMultibanco نقاط نهاية بيئة الاختبار الخاصة بـ ifthenpay؛ لا يُخصم أي مال حقيقي، وتستخدم مفاتيح الاختبار التي توفرها ifthenpay. لا تملك MB WAY بيئة اختبار: اختبرها بمفتاح اختبار من ifthenpay. تعرض صفحة الدفع شارة TEST MODE. الافتراضي: إيقاف.

Order Status After Payment: حالة الطلب التي تُعيَّن بعد دفعة مؤكدة، مع تغيير حالة واحد وبريد إلكتروني واحد للعميل. الطلبات التي تحتوي فقط على منتجات افتراضية قابلة للتنزيل تُكمِلها WooCommerce دائمًا.

Debug Log: Enable logging. تُكتب طلبات API والـ callback في WooCommerce > Status > Logs، المصدر wcp_ifthenpay_gateway. تُسجَّل الأخطاء دائمًا. لا تُسجَّل المفاتيح ومفتاح مكافحة التصيد وأرقام الهواتف أبدًا. الافتراضي: إيقاف.

Delete Data on Uninstall: Remove the plugin settings, the anti-phishing key and the logs when the plugin is deleted (orders are kept). الافتراضي: إيقاف.

الدفع

Multibanco. عند الدفع يرى العميل You will receive a Multibanco reference to complete the payment. عند إرسال الطلب تنشئ الإضافة مرجع Multibanco ديناميكيًا بإجمالي الطلب. ينتقل الطلب إلى حالة قيد الانتظار، ويُخصم المخزون، وتُفرَّغ السلة. تعرض صفحة استلام الطلب ورسائل الطلب التي تُرسل أثناء بقائه قيد الانتظار Multibanco Payment Details: الكيان والمرجع والمبلغ، مع Please use these details to pay at any Multibanco ATM or through your online banking. إذا أعاد العميل إرسال الطلب بالمبلغ نفسه، يُعاد استخدام المرجع نفسه. يُؤكَّد الطلب عندما ترسل ifthenpay الـ callback الخاص بالدفع.

MB WAY. يُدخل العميل MB WAY phone number (912 345 678 أو +351 912 345 678 أو 351#912345678 لدول أخرى)؛ ويُملأ هاتف الفوترة تلقائيًا. ترسل الإضافة طلب دفع إلى الهاتف، وينتقل الطلب إلى قيد الانتظار، ويُخصم المخزون، وتُفرَّغ السلة. تعرض صفحة استلام الطلب A payment request has been sent to your phone via MB WAY. Please confirm it in the MB WAY app. تُحفظ جميع طلبات الطلب، لذلك يظل الطلب السابق الموافَق عليه في التطبيق مقبولًا. يُؤكَّد الطلب بالـ callback.

Credit Card. يرى العميل You will be redirected to a secure page to enter your card details. ويُوجَّه إلى صفحة البطاقات الخاصة بـ ifthenpay. يبقى الطلب في حالة Pending payment حتى يُدفع، ولا يُخصم المخزون قبل ذلك. بعد دفعة ناجحة يعود العميل إلى متجرك. لا تُقبل العودة إلا بتوقيع صالح من ifthenpay، ومفتاح الطلب، وسرّ تلك المحاولة، وطلب البطاقة الخاص بالطلب؛ عندها يُعلَّم الطلب مدفوعًا. إذا تعذّر التحقق من العودة لا يتغير الطلب، وتعرض صفحة استلام الطلب Your card payment is being confirmed by ifthenpay. You will receive an e-mail as soon as it is confirmed. دفعة البطاقة الفاشلة تجعل الطلب Failed، والملغاة تتركه Pending payment. وفي الحالتين ينتقل العميل إلى صفحة Pay for order مع The card payment was not completed. You can try again or choose another payment method. أو The card payment was cancelled. You can try again or choose another payment method.

لا يُعلَّم الطلب مدفوعًا إلا بعد تأكيد ifthenpay للدفع، ويُتحقق من المبلغ حتى السنت مقابل إجمالي الطلب. إذا تعذّر بدء الدفع، يرى العميل رسالة قصيرة، مثل The Multibanco reference could not be created. Please try again or choose another payment method. أو The MB WAY payment request could not be sent. Please check that the phone number is linked to MB WAY, or choose another payment method. أو The payment service is temporarily unavailable. Please try again in a few minutes.

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

تقدم الإضافة طريقة واحدة من ifthenpay في كل مرة. لا تدعم Payshop، أو Cofidis Pay، أو Apple Pay، أو Google Pay، أو PIX، أو Pay-by-Link، ولا الاشتراكات أو البطاقات المحفوظة، ولا الإلغاء أو الانتهاء التلقائي لمراجع Multibanco غير المدفوعة، ولا الاستعلام عن حالة الدفع.

الطلبات

Order statuses

On hold (waiting for payment): صدر مرجع Multibanco أو أُرسل طلب MB WAY. لا تُلغى المراجع غير المدفوعة تلقائيًا؛ ألغِ هذه الطلبات بنفسك إذا لزم الأمر.

Pending payment: بدأت دفعة بطاقة ولم تُؤكَّد بعد، أو أُلغيت.

Processing or Completed: تم تأكيد الدفع. تتبع الحالة Order Status After Payment. تعرض ملاحظة الطلب كيان المرجع Multibanco ومرجعه، أو معرّف معاملة MB WAY، أو معرّف طلب البطاقة.

On hold after payment: المبلغ المستلم يختلف عن إجمالي الطلب، أو وصلت الدفعة بعد إلغاء الطلب. تشرح ملاحظة الطلب ذلك. تحقّق من الدفعة في الواجهة الخلفية لـ ifthenpay، وأكمل الطلب أو استرده يدويًا.

Failed: عاد العميل من صفحة البطاقة مع خطأ.

لا يضيف إشعار الدفع الثاني لطلب مدفوع بالفعل سوى ملاحظة للتحقق من دفعة مكررة في الواجهة الخلفية لـ ifthenpay. لا تُعاد فتح الطلبات المستردة، ولا الطلبات الملغاة بعد الدفع أبدًا.

الاستردادات

لا يُدعم الاسترداد من WooCommerce. استرد الدفعة في الواجهة الخلفية لـ ifthenpay وسجّلها يدويًا في WooCommerce. لا يضيف الـ callback الخاص بالاسترداد (DEVOLVIDO) سوى ملاحظة طلب. الحالات الأخرى التي تبلغ عنها ifthenpay تضيف ملاحظة فقط أيضًا.

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

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

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

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

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

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

لا يظهر ifthenpay في الدفع: تحقّق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن مفتاح Payment Method المختار مُدخل، وأن العملة EUR، وأن الإجمالي بين 0.01 و99,999.99 EUR. في صفحة Pay for order تُحتسب عملة الطلب.

دفع العميل لكن الطلب يبقى On hold أو Pending payment: الـ callback لا يصل إلى متجرك. تحقّق من أن ifthenpay فعّل عنوان الـ callback ومفتاح مكافحة التصيد للمفتاح الذي تستخدمه، وأن العنوان هو عنوان الطريقة المختارة. يجب أن يكون الموقع متاحًا من الإنترنت، لا على localhost ولا خلف تسجيل دخول. ابحث عن أسطر Callback rejected في WooCommerce > Status > Logs، المصدر wcp_ifthenpay_gateway.

يرد الـ callback بـ 403 Forbidden: مفتاح مكافحة التصيد في الـ callback مفقود أو يختلف عن المفتاح في الإعدادات. أرسل المفتاح المعروض في الإعدادات إلى ifthenpay مجددًا.

يرد الـ callback بـ 503 Not configured: لم يُنشأ مفتاح مكافحة التصيد بعد. افتح صفحة الإعدادات مرة واحدة؛ ستعيد ifthenpay محاولة الـ callback.

يرد الـ callback بـ Order not found: المرجع أو الطلب لا ينتمي إلى طلب في هذه البوابة، مثلًا لأن طريقة الدفع بُدّلت بعد إنشاء الطلب.

لماذا وُضع طلب مدفوع في On hold؟ المبلغ المستلم يختلف عن إجمالي الطلب، أو وصلت الدفعة بعد إلغاء الطلب. اقرأ ملاحظة الطلب، وتحقّق من الدفعة في الواجهة الخلفية لـ ifthenpay، وأكمل الطلب أو استرده يدويًا.

تعذّر إرسال طلب MB WAY: رقم الهاتف غير مرتبط بـ MB WAY أو بصيغة خاطئة. استخدم 912 345 678، أو 351#912345678 لأرقام الدول الأخرى.

وضع الاختبار وMB WAY: لا توفر ifthenpay بيئة اختبار لـ MB WAY؛ استخدم مفتاح اختبار توفره ifthenpay.

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

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

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

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