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

المتطلبات

WordPress: 6.0 أو أحدث.

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

PHP: 8.0 أو أحدث.

حساب finby (TrustPay): تحتاج إلى مشروع في finby Merchant Portal مع Project ID وSecret key الخاصين به. ولإجراء مدفوعات تجريبية تحتاج إلى مشروع اختبار (playground) منفصل، مع Project ID وSecret key خاصين به. لا حاجة لأي مفاتيح أخرى: يُستخدم Secret key للحصول على وصول إلى واجهة API وللتحقق من توقيع إشعارات الدفع معًا.

عنوان إشعار يمكن الوصول إليه: يجب أن تستطيع finby الوصول إلى موقعك من الإنترنت. فجدار الحماية أو وضع الصيانة أو حماية الموقع بكلمة مرور تمنع إشعارات الدفع.

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

التثبيت

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

2. انقر على Activate.

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

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

5. أدخل Project ID وSecret key لمشروع الإنتاج، وأدخل بيانات مشروع الاختبار إذا كنت ستجري اختبارات (انظر الإعدادات).

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

عند التحديث من الإصدار 1.0، يبقى Project ID وSecret key محفوظين كبيانات اعتماد للإنتاج، ويُعطَّل وضع الاختبار. راجع الإعدادات بعد التحديث.

الإعدادات

جميع الإعدادات موجودة في صفحة واحدة: WooCommerce > Settings > Payments > TrustPay / finby. تُظهر الصفحة فوق الحقول تحذيرًا عندما تكون البوابة مفعّلة لكن Project ID أو Secret key للوضع الحالي فارغ، وعندما لا تكون عملة المتجر مدعومة. وفي الحالتين تُخفى طريقة الدفع في صفحة الدفع. وفي قائمة طرق الدفع تظهر البوابة على أنها تحتاج إلى إعداد حتى يحتوي الوضع الحالي على Project ID وSecret key.

General

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

Title: اسم طريقة الدفع الذي يراه العملاء في صفحة الدفع. الافتراضي: Card payment (TrustPay).

Description: النص الذي يظهر أسفل طريقة الدفع في صفحة الدفع. الافتراضي: Pay securely by card on the TrustPay / finby payment page.

API credentials

انسخ Project ID وSecret key لمشروعك من finby (TrustPay) Merchant Portal. يحتوي القسم على رابط إلى Merchant Portal. تستخدم المدفوعات التجريبية مشروع اختبار (playground) منفصلًا، له Project ID وSecret key خاصان به. لا يُخصم أي مبلغ حقيقي هناك.

Test mode: Use the test project (no real payments). تستخدم المدفوعات والاستردادات الجديدة بيانات الاعتماد التجريبية. تُنفَّذ استردادات الطلب دائمًا على المشروع الذي دُفع من خلاله الطلب. الافتراضي: مفعّل.

Live Project ID: معرّف Project ID الرقمي لمشروع الإنتاج الخاص بك.

Live Secret key: مفتاح Secret key لمشروع الإنتاج. يُستخدم للحصول على رموز الوصول إلى API والتحقق من إشعارات الدفع.

Test Project ID: معرّف Project ID الرقمي لمشروع الاختبار (playground) الخاص بك.

Test Secret key: مفتاح Secret key لمشروع الاختبار.

يجب أن يحتوي Project ID على أرقام فقط. إذا حفظت قيمة أخرى، تُظهر الصفحة خطأ ويبقى الإدخال السابق كما هو. تُحفظ مفاتيح Secret key كما أدخلتها، ولا يُحذف إلا المسافات في بداية النص ونهايته.

Payment notifications

لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكد finby الدفع بإشعار موقَّع. ترسل الإضافة عنوان الإشعار مع كل دفعة تلقائيًا، لذا لا تحتاج إلى إعداده. يعرض القسم العنوان، مثل https://your-site/wc-api/trustpay_payment_callback/. ويمكنك أيضًا إدخاله بوصفه عنوان الإشعار لمشاريعك في Merchant Portal. تُرفض الإشعارات التي لا تحمل توقيعًا صالحًا.

لا تستعلم الإضافة بنفسها من finby عن حالة الدفع. إذا تعذّر وصول إشعار إلى موقعك، يبقى الطلب في حالة Pending payment حتى ترسله finby.

Advanced

Order status after payment: حالة الطلب التي تُعيَّن بعد نجاح الدفع. تُعيَّن الحالة بخطوة واحدة، فيتلقى العميل رسالة بريد إلكتروني واحدة.

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

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

الدفع

يختار العميل طريقة الدفع (افتراضيًا Card payment (TrustPay)) ويُتمّ الطلب. في وضع الاختبار تعرض صفحة الدفع Test mode: no real payment will be taken. أسفل الوصف.

تتطلب مدفوعات البطاقات عنوان الفوترة. إذا كان الشارع أو المدينة أو الرمز البريدي أو الدولة مفقودًا، يرى العميل Please enter your billing address (street, city, postcode and country) — it is required for card payments.

تنشئ الإضافة طلب دفع بالبطاقة لدى finby بقيمة إجمالي الطلب وبعملة الطلب. يُرسل اسم العميل وعنوانه وبريده الإلكتروني من أجل 3-D Secure، ويُرسل رقم الطلب كمرجع. يُنقل العميل إلى صفحة دفع finby ويدفع بالبطاقة هناك. تُفتح الصفحة بلغة متجرك إذا كانت finby تدعمها، وإلا فبالإنجليزية. تعرض ملاحظة على الطلب طلب الدفع والمبلغ والمشروع (اختبار أو إنتاج).

بعد الدفع يعود العميل إلى صفحة استلام الطلب في متجرك، ويُفرَّغ سلة التسوق. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكد finby ذلك بالإشعار الموقَّع. ولا تغيّر العودة نفسها حالة الدفع أبدًا.

إذا ألغى العميل في صفحة الدفع، أو أعادت صفحة الدفع خطأً، يعود العميل إلى صفحة Pay for order مع الرسالة The card payment was cancelled. You can try again or choose another payment method. أو The card payment was not completed. Please try again or choose another payment method. تُضاف ملاحظة إلى الطلب. يمكن للعميل أن يدفع مرة أخرى من تلك الصفحة.

إذا تعذّر على finby بدء الدفع، يرى العميل We could not start the card payment. Please try again in a moment or choose another payment method. ويُكتب السبب التقني في السجل.

العملات: EUR وCZK وHUF وGBP وPLN وNOK وSEK وDKK وBGN وRON وCHF وUSD. تُرسل مبالغ HUF بدون منازل عشرية. وتُتحقق عملة الطلب في صفحة Pay for order.

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

تقبل الإضافة مدفوعات البطاقات فقط، بوصفها عملية شراء بخطوة واحدة في صفحة finby. لا تتضمن تحويلات بنكية أو طرق دفع أخرى من finby، ولا أزرار Apple Pay أو Google Pay، ولا بطاقات محفوظة، ولا اشتراكات أو مدفوعات متكررة، ولا تفويضًا وتحصيلًا منفصلين، ولا استطلاعًا دوريًا للحالة.

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

حالات الطلب

Pending payment: أُرسل العميل إلى finby ولم يدفع بعد، أو لم يصل الإشعار بعد.

Processing or Completed: أكدت finby الدفع، ويتطابق المبلغ والعملة مع طلب الدفع وإجمالي الطلب. تتبع الحالة Order status after payment. تعرض ملاحظة الطلب المبلغ وطلب الدفع والمشروع. ومعرّف المعاملة هو معرّف طلب الدفع في finby.

On hold: يُعيَّن في ثلاث حالات. الدفع ما زال معلقًا لدى finby، والطلب ينتظر النتيجة النهائية. الدفع مُفوَّض فقط ولم يُحصَّل: حصّله أو ألغِه في finby Merchant Portal ثم حدّث الطلب. أو أن المبلغ المدفوع أو العملة يختلف عن طلب الدفع أو إجمالي الطلب، مثلًا بسبب تعديل الطلب بعد إرسال العميل إلى صفحة الدفع: تحقق من الدفع قبل الشحن. وتوضح ملاحظة الطلب الحالة.

Failed: رفضت finby آخر دفعة للطلب. تعرض الملاحظة السبب عندما ترسله finby. ويمكن للعميل أن يدفع مرة أخرى من Pay for order.

لا يُعاد فتح الطلبات الملغاة أو المستردة بسبب دفعة متأخرة. وتطلب ملاحظة منك استعادة الطلب أو استرداد الدفع في Merchant Portal. وإذا وصلت دفعة ثانية لطلب مدفوع بالفعل، لا يتغير الطلب وتطلب ملاحظة منك استرداد النسخة المكررة في Merchant Portal. وتُضاف الاعتراضات (chargebacks) والنزاعات التي تبلغ عنها finby كملاحظات.

الاستردادات

افتح الطلب، وانقر على Refund، وأدخل المبلغ، ثم انقر على Refund via Card payment (TrustPay) (يعرض الزر Title الخاص بك). يُدعم الاسترداد الكامل والجزئي. يُرسل الاسترداد إلى المشروع الذي دُفع من خلاله الطلب (اختبار أو إنتاج)، حتى إذا غيّرت الوضع بعد ذلك، لذلك يجب أن يكون Project ID وSecret key لذلك الوضع مضبوطين. يجب أن تكون استردادات HUF مبالغ صحيحة.

لا يُسجَّل الاسترداد إلا عندما تقبله finby. وإلا يعرض WooCommerce TrustPay refused the refund: مع السبب، ولا يُنشأ أي استرداد. ويُضاف الاسترداد الناجح إلى ملاحظات الطلب.

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

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

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

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

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

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

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

لا تظهر Card payment (TrustPay) في صفحة الدفع: تحقق من أن الترخيص فعّال، وأن Enable / Disable مفعّل، وأن الوضع الحالي يحتوي على Project ID وSecret key: Test Project ID وTest Secret key في وضع الاختبار، وLive Project ID وLive Secret key في وضع الإنتاج. يجب أن تكون عملة المتجر، أو عملة الطلب في صفحة Pay for order، إحدى العملات المدعومة. تعرض صفحة الإعدادات تحذيرًا في الحالتين. ويمكن للمطورين تغيير قائمة العملات بالفلتر trustpay_p_supported_currencies.

تمت عملية الدفع لكن الطلب ما زال في Pending payment: لم يصل الإشعار إلى متجرك. تحقق من أن https://your-site/wc-api/trustpay_payment_callback/ متاح من الإنترنت (بدون جدار حماية أو وضع صيانة أو حماية بكلمة مرور). تعيد finby إرسال الإشعار. راجع WooCommerce > Status > Logs، المصدر wcp_trustpay_gateway.

يعرض السجل Notification rejected: invalid signature or unknown project: جاء الإشعار من مشروع لا يوجد Project ID الخاص به في الإعدادات، أو أن Secret key لذلك المشروع غير صحيح. يرد المتجر بـ Invalid signature ولا يتغير الطلب. تحقق من Project ID وSecret key للوضع الذي تمت فيه عملية الدفع.

يعرض السجل Notification ignored: ينتمي الإشعار إلى طلب دفع لم ينشئه هذا المتجر لذلك الطلب، أو إلى مشروع غير المشروع الذي بدأ به الدفع. لا يتغير الطلب.

يتلقى الإشعار الرد Busy, retry later: كان الطلب يُحدَّث بإشعار آخر في الوقت نفسه. ستعيد finby المحاولة.

يرى العميل We could not start the card payment: افتح السجل. يعطي Project ID أو Secret key خاطئ رسالة تفيد بأن finby رفضت بيانات اعتماد المشروع. تحقق من أن بيانات الاختبار موجودة في حقول الاختبار، وبيانات الإنتاج في حقول الإنتاج.

الدفع بالبطاقة غير متاح مؤقتًا: يرى العميل هذه الرسالة عندما لا يحتوي الوضع الحالي على Project ID أو Secret key. أدخلهما واحفظ.

الطلب في حالة On hold مع ملاحظة اختلاف المبلغ أو العملة: كان الإشعار صحيحًا، لكن المبلغ المدفوع أو العملة يختلف عن طلب الدفع أو إجمالي الطلب. تحقق من الدفع في Merchant Portal قبل الشحن، ثم أكمل الطلب أو استرد الدفع.

يفشل الاسترداد برسالة تتعلق بالمشروع: دُفع الطلب عبر مشروع الاختبار أو الإنتاج، وإما أن Project ID أو Secret key لذلك الوضع غير مضبوط، أو أن Project ID آخر محفوظ الآن. أدخل بيانات اعتماد ذلك المشروع، أو استرد الدفع في finby Merchant Portal.

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

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

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

TrustPay وfinby علامتان تجاريتان لمالكيهما. هذه الإضافة غير تابعة لـ TrustPay أو finby ولا معتمدة منهما.