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

المتطلبات

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

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

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

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

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

التثبيت

1. في الواجهة الخلفية (back office) انتقل إلى Modules > Module Manager ثم انقر على Upload a module. اختر ملف ZIP الخاص بالوحدة.

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

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

4. أدخل Project ID وSecret key لمشروع الاختبار، ولمشروع الإنتاج عند تنفيذ مدفوعات حقيقية (راجع قسم الإعدادات).

5. فعّل Enable / Disable ثم انقر على Save. نفّذ دفعة تجريبية مع تفعيل Test mode، ثم أوقف Test mode لقبول المدفوعات الحقيقية.

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

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox TrustPay Gateway > Configure. لكل قسم زر Save خاص به، وهذا الزر يحفظ الصفحة بأكملها. وفوق الحقول تحذّرك الصفحة عندما تكون الوحدة مفعّلة بينما يكون Project ID أو Secret key للوضع الحالي فارغًا، وعندما لا تكون عملة المتجر الافتراضية مدعومة. وفي الحالتين يُخفى خيار الدفع عند إتمام الشراء.

TrustPay / finby

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

Title: اسم خيار الدفع الذي يراه العميل عند إتمام الشراء. وهو أيضًا اسم خيار الدفع المحفوظ في الطلب. الافتراضي: Card payment (TrustPay). مطلوب.

Description: النص الذي يظهر أسفل خيار الدفع عند إتمام الشراء. الافتراضي: Pay securely by card on the TrustPay / finby payment page.

بيانات اعتماد API

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

Test mode: يستخدم مشروع الاختبار (لا مدفوعات حقيقية). تستخدم المدفوعات والاستردادات الجديدة بيانات الاعتماد التجريبية. تُنفَّذ استردادات الطلب دائمًا على المشروع الذي دُفع من خلاله الطلب. الافتراضي: on. وطالما هو مفعّل يرى العملاء أسفل خيار الدفع العبارة Test mode: no real payment will be taken.

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

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

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

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

يجب أن يحتوي Project ID على أرقام فقط. إذا حفظت قيمة أخرى تعرض الصفحة must contain digits only — the previous value was kept. وتُحفظ الحقول الأخرى. تُحفظ مفاتيح Secret key كما أدخلتها تمامًا، وتُحذف فقط المسافات في البداية والنهاية. لا تُعرض مفاتيح Secret key المحفوظة مرة أخرى. يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط عندما تريد تغييرها. وحفظ الإعدادات يحذف أيضًا رموز وصول API المخزنة مؤقتًا، فتُستخدم بيانات الاعتماد الجديدة فورًا.

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

إشعارات الدفع

لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكده finby بإشعار موقَّع. ترسل الوحدة عنوان URL للإشعارات تلقائيًا مع كل دفعة، لذلك لا تحتاج إلى إعداده. يعرض القسم العنوان تحت Notification URL. وعند تفعيل الروابط الودية يبدو هكذا: https://your-shop/module/wcp_trustpay_gateway/callback، وقد يسبقه رمز لغة. ويمكنك أيضًا إدخاله كعنوان إشعارات لمشاريعك في Merchant Portal. تُرفض الإشعارات التي لا تحمل توقيعًا صالحًا.

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

متقدم

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

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

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

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

إتمام الشراء

في خطوة الدفع يختار العميل خيار الدفع (افتراضيًا Card payment (TrustPay)) ويؤكد الطلب. يُعرض خيار الدفع فقط بالعملات المدعومة: EUR وCZK وHUF وGBP وPLN وNOK وSEK وDKK وBGN وRON وCHF وUSD. تُرسل مبالغ HUF بدون كسور عشرية.

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

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

بعد الدفع يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكده finby بالإشعار الموقَّع. والعودة نفسها لا تغيّر حالة الدفع أبدًا. إذا وصل الإشعار بالفعل يرى العميل صفحة تأكيد الطلب المعتادة. وإذا لم يصل بعد، تظهر صفحة Payment confirmation تفيد بأن finby تؤكد الدفع بالبطاقة وأن الطلب سيُنشأ فور تأكيده. تحتوي الصفحة على زر Check again وزر Back to checkout. وطالما الطلب في حالة Awaiting TrustPay payment أو TrustPay payment on hold تعرض صفحة التأكيد Your card payment is being confirmed by TrustPay / finby. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. وإذا رفضت finby الدفع أو أُلغي الطلب غير المدفوع، تعرض Your card payment was not completed. Please contact us about this order.

إذا ألغى العميل في صفحة الدفع، يعود إلى إتمام الشراء مع الرسالة The card payment was cancelled. You can try again or choose another payment method. وإذا أعادت صفحة الدفع خطأ، أو رفضت finby الدفع بالفعل، تكون الرسالة 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. ويُكتب السبب التقني في السجل.

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

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

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

حالات الطلب

No order yet: أُرسل العميل إلى finby ولم يدفع، أو لم يصل الإشعار بعد. لا توجد إلا السلة.

Payment accepted or Delivered: أكدت finby الدفع، والمبلغ والعملة يطابقان طلب الدفع وإجمالي السلة. تتبع الحالة Order status after payment. يُسجَّل الدفع بمعرّف طلب الدفع لدى finby كمعرّف للمعاملة، وتعرض ملاحظة المبلغ وطلب الدفع والمشروع (اختبار أو إنتاج).

Awaiting TrustPay payment: أبلغت finby بأن آخر دفعة قيد الانتظار. ينتقل الطلب إلى حالة الدفع عندما تؤكد finby الدفعة.

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

Payment error: رفضت finby آخر دفعة لطلب كان ينتظر. وتعرض الملاحظة السبب عندما ترسله finby. ومع ذلك تنقل أي دفعة مؤكدة لاحقًا الطلب إلى حالة الدفع.

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

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

كتلة الدفع TrustPay / finby

تعرض صفحة الطلب كتلة TrustPay / finby payment تحتوي على معرّف طلب الدفع، ومعرّف دفعة finby، والمشروع، وحالة الدفع، والمبلغ المطلوب والمبلغ المدفوع، والمبلغ المسترد، وشارة Test project للمدفوعات التجريبية، وسجل الاسترداد، وTrustPay notes الخاصة بالطلب.

الاسترداد

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

يُرسل الاسترداد إلى المشروع الذي دُفع من خلاله الطلب (اختبار أو إنتاج)، حتى لو بدّلت الوضع بعد ذلك. ويجب أن يكون Project ID وSecret key لذلك المشروع مُعدّين، وألا يكون Project ID قد تغيّر. لا يُسجَّل الاسترداد إلا عندما تقبله finby. وإلا تعرض الكتلة TrustPay refused the refund: مع السبب، ولا يُسجَّل أي استرداد. ويُضاف الاسترداد الناجح إلى سجل الاسترداد والملاحظات. الاسترداد الكامل يضع الطلب في حالة Refunded. أما الاسترداد الجزئي فلا يغيّر الحالة.

لا تنشئ الوحدة إشعارات دائنة (credit slips). أزرار الاسترداد القياسية في PrestaShop على صفحة الطلب لا تعيد الأموال عبر finby. والاستردادات التي تُجرى في finby Merchant Portal لا تُسجَّل كاستردادات. وإذا أرسلت finby إشعارًا بشأنها، يُضاف كملاحظة ولا تتغير حالة الطلب.

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

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

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

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

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

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

تمت الدفعة لكن لم يُنشأ أي طلب: لم يصل الإشعار إلى متجرك. تحقّق من أن العنوان المعروض تحت Notification URL متاح من الإنترنت (دون جدار حماية أو تسجيل دخول للصيانة أو مصادقة HTTP). تعيد finby إرسال الإشعار، وينشأ الطلب عند وصوله. فعّل Debug logging وراجع حقل Log في صفحة الوحدة.

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

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

يتلقى الإشعار الرد Busy, retry later أو Temporary error: كانت السلة تُحدَّث بإشعار آخر في اللحظة نفسها، أو تعذّر إنشاء الطلب (مثلًا لأن الوحدة معطّلة). ستعيد finby المحاولة. ويعرض السجل السبب.

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

Card payment is temporarily unavailable: يرى العميل هذه الرسالة عندما لا يحتوي الوضع الحالي على Project ID أو Secret key. أدخلهما واحفظ.

الطلب في حالة TrustPay payment on hold: اقرأ الملاحظات في كتلة TrustPay / finby payment (راجع حالات الطلب). تحقّق من الدفعة في Merchant Portal قبل الشحن، ثم أكمل الطلب أو استرد الدفعة.

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

Invalid refund amount: at most … can be refunded: المبلغ أكبر من المبلغ المدفوع مطروحًا منه الاستردادات التي تمت بالفعل عبر الوحدة.

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

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

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