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

المتطلبات

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

PHP: 8.0 أو أحدث. لا تُثبَّت الوحدة على إصدارات PHP الأقدم.

العملة: EUR. لا تقبل Paytrail سوى اليورو. وفي حال كانت السلة بعملة أخرى تُخفى وسيلة الدفع في صفحة الدفع. وتُرسل المبالغ بالسنت.

اتصال متجرك بالإنترنت: تؤكد Paytrail كل عملية دفع عبر callback من خادم إلى خادم، لذلك يجب أن يكون المتجر متاحًا عبر الإنترنت. ومن دون طلبات callback، تُنشأ الطلبات مع ذلك عندما يعود العميل من Paytrail.

حساب Paytrail: تحتاج إلى Merchant ID وSecret key الخاصين بك، واللذين يظهران في لوحة تاجر Paytrail (تفاصيل الحساب أو التكامل). للاختبار لا يلزم حساب: يستخدم وضع الاختبار حساب Paytrail العام للاختبار. أما وسائل الدفع نفسها فتُفعَّل في حساب Paytrail الخاص بك.

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

التثبيت

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

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

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

4. لتجربة الوحدة أولًا، فعّل Test mode. أما للمدفوعات الحقيقية فأوقفه، وأدخل Merchant ID وSecret key الخاصين بك. لا يلزم إعداد أي رابط callback URL في Paytrail.

5. فعّل Enable/Disable وانقر على Save.

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

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Paytrail Gateway > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كاملة. وتعرض الصفحة فوق الحقول Test mode is active. Payments use the public Paytrail test account — no real money is charged. ما دام وضع الاختبار مفعّلًا. وفي الوضع الحي تُظهر تحذيرًا إذا كان Merchant ID أو Secret key مفقودًا، أو إذا كان Merchant ID هو حساب الاختبار العام 375917، كما تحذر إذا لم تكن عملة المتجر EUR. وفي كل هذه الحالات لا تظهر Paytrail في صفحة الدفع.

عند الحفظ، لا يُحفظ Merchant ID الذي يحتوي على أي شيء غير الأرقام، وتظهر رسالة الخطأ Paytrail merchant ID must contain digits only. The previous value was kept.. ولا يمكن أن يكون حقل Title فارغًا.

Paytrail

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

Title: العنوان الذي يراه العملاء أثناء الدفع، وهو أيضًا اسم وسيلة الدفع المحفوظ في الطلب. الافتراضي: Paytrail. حقل إلزامي.

Description: النص الذي يراه العملاء أسفل وسيلة الدفع أثناء الدفع. الافتراضي: Pay securely with Finnish online banking, card, mobile payment or invoice on the Paytrail payment page.

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

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

Test mode: يستخدم حساب Paytrail العام للاختبار (Merchant ID 375917) للمدفوعات الجديدة بدلًا من بيانات اعتمادك. لا يُخصم أي مبلغ حقيقي، ولا تلزم أي مفاتيح. ويرى العملاء العبارة Test mode: no real payment will be made. أسفل وسيلة الدفع. والمفتاح السري لحساب الاختبار عام، لذلك يستطيع أي شخص محاكاة دفعة تمت في وضع الاختبار. لا تُبقِ وضع الاختبار مفعّلًا في متجر حقيقي أبدًا. الافتراضي: off.

Merchant ID: معرّف التاجر الخاص بك في Paytrail (أرقام فقط). يُستخدم عندما يكون وضع الاختبار متوقفًا.

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

Clear saved secret key: ضع علامة على Secret key ثم انقر على Save لإزالة المفتاح المحفوظ. ويحتفظ الحقل الفارغ بالقيمة المحفوظة.

تستخدم الاستدعاءات وعمليات الاسترداد دائمًا بيانات اعتماد الوضع الذي تمت فيه الدفعة، لذلك لا يؤدي التبديل بين الاختبار والوضع الحي إلى تعطيل الطلبات القديمة.

الطلبات

Callback URL: يعرض الرابط الذي تؤكد عنده Paytrail كل عملية دفع من خادم إلى خادم. مع الروابط الودية يبدو هكذا: https://your-shop/module/wcp_paytrail_gateway/callback. يُرسل مع كل عملية دفع، لذلك لا يلزم ضبط أي شيء في لوحة Paytrail، لكن يجب أن يكون المتجر متاحًا عبر الإنترنت.

Order status after payment: حالة الطلب المدفوع.

تنتظر المدفوعات المعلقة في Awaiting Paytrail payment. أما فروق المبالغ والمشكلات الأخرى فتذهب دائمًا إلى Paytrail payment on hold.

متقدم

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

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

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

الدفع

في خطوة الدفع يختار العميل وسيلة الدفع (افتراضيًا Paytrail) ويؤكد. تُنشئ الوحدة دفعة Paytrail بإجمالي السلة باليورو، وترسل معها بنود الطلب: المنتجات بعد قواعد السلة، والشحن، وتغليف الهدايا، لكل منها معدل ضريبته حتى منزلة عشرية واحدة. ويتطابق مجموع البنود دائمًا مع مبلغ الدفع؛ ويُضاف فرق التقريب إلى أحد البنود أو يُرسل كبند Rounding. ولا تُرسل عناوين الفوترة والتوصيل إلا عندما تكون مكتملة، وتُختصر القيم الطويلة وفق حدود Paytrail. ولغة صفحة الدفع هي الفنلندية أو السويدية أو الإنجليزية، وفقًا للغة السلة. ولا يوجد طلب في هذه المرحلة.

يُوجَّه العميل إلى صفحة الدفع في Paytrail، فيختار وسيلة دفع مفعّلة لحساب Paytrail الخاص بك ويدفع. ثم تؤكد Paytrail الدفع مرتين: تُعيد العميل إلى متجرك، وتستدعي عنوان callback URL من خادم إلى خادم. ولا يُقبل أي من التأكيدين إلا بتوقيع صالح أُنشئ ببيانات اعتماد محاولة الدفع تلك، وفقط لمحاولة أُنشئت لهذه السلة. ويُقارن المبلغ المدفوع بإجمالي السلة. ولا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكد Paytrail ذلك بهذه الطريقة. وتتعامل الوحدة مع حالات Paytrail التالية:

بعد الدفع الناجح يرى العميل صفحة تأكيد الطلب القياسية مع العبارة Your Paytrail payment has been received.. وفي حالة الدفع المعلق تعرض الصفحة Your Paytrail payment is pending confirmation by the payment provider. The order is updated automatically — please do not pay again.. وإذا كان callback يسجّل الدفعة في اللحظة نفسها، تطلب صفحة Payment confirmation من العميل ألا يدفع مرة أخرى، وتعرض زر Check again.

بعد عملية دفع أُلغيت أو فشلت، يعود العميل إلى صفحة الدفع مع الرسالة The Paytrail payment was cancelled or failed. You can try again or choose another payment method.. وإذا لم تكتمل عملية الدفع بعد، فالرسالة هي The Paytrail payment has not been completed yet. You can try again or choose another payment method.. ويُحفظ محتوى السلة. ويعرض الرجوع الذي لا يمكن التحقق منه الرسالة Payment verification failed. دون أي تغيير.

إذا تعذر على Paytrail بدء عملية الدفع، يبقى العميل في صفحة الدفع مع رسالة قصيرة، مثل Could not connect to Paytrail. Please try again in a moment.، أو Paytrail is temporarily unavailable. Please choose another payment method. (بيانات اعتماد خاطئة)، أو Paytrail could not start the payment. Please check your billing details and try again, or choose another payment method.. ويُكتب السبب التقني في السجل. ويعرض الإجمالي الخارج عن حدود Paytrail الرسالة This order total cannot be paid with Paytrail. Please choose another payment method..

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

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

يختار العميل وسيلة الدفع في صفحة Paytrail وليس في صفحة الدفع لديك. ولا تتضمن الوحدة ترميز البطاقات أو البطاقات المحفوظة، أو الاشتراكات، أو shop-in-shop، أو التفعيل اليدوي للفواتير، أو تقارير التسوية.

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

حالات الطلب

لا يوجد طلب بعد: أُرسل العميل إلى Paytrail ولم يدفع، أو لم تؤكد Paytrail الدفع بعد. لا توجد سوى السلة.

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

Awaiting Paytrail payment: الدفع معلق لدى مزوّد الخدمة (فاتورة أو دفع مؤجل). ينتقل الطلب إلى حالة المدفوع عندما تؤكد Paytrail الدفع، أو إلى Payment error إذا فشل.

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

Payment error: فشلت دفعة معلقة أو أُلغيت.

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

لا تُنشئ الاستدعاءات المتكررة أو المتوازية طلبًا ثانيًا أبدًا، ولا ملاحظات مكررة. وإذا دُفعت محاولة ثانية لسلة مدفوعة بالفعل، فلا يتغير الطلب؛ وتطلب منك ملاحظة Duplicate payment استرداد هذه الدفعة في لوحة تاجر Paytrail.

كتلة دفع Paytrail

تعرض صفحة الطلب كتلة Paytrail payment تتضمن معرّف المعاملة، والوضع (شارة TEST mode لدفعات الاختبار)، وطريقة الدفع، وحالة Paytrail، والمبلغ المدفوع والمسترد، ونموذج الاسترداد، وسجل الاسترداد، ومحاولات الدفع الخاصة بالسلة، وPaytrail notes الخاصة بالطلب.

الاستردادات

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

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

قد يكتمل الاسترداد فورًا أو تتم معالجته لاحقًا. وتُضاف تأكيدات Paytrail اللاحقة كملاحظة. وإذا تعذّر على Paytrail إتمام الاسترداد، تذكر ملاحظة أن المال لم يُعَد إلى العميل، ولا يُحتسب الاسترداد بعد ذلك كمسترد؛ استرد المبلغ للعميل بطريقة أخرى. وإذا رفضت Paytrail الاسترداد فورًا، تعرض الكتلة الخطأ ولا يُسجَّل أي استرداد. ويضبط الاسترداد الكامل حالة الطلب على Refunded. أما الاسترداد الجزئي فلا يغيّر الحالة.

لا تُنشئ الوحدة إشعارات دائنة. ولا تُعيد أزرار الاسترداد القياسية في PrestaShop المالَ عبر Paytrail. ولا تُزامَن عمليات الاسترداد التي تتم في لوحة تاجر Paytrail مع PrestaShop.

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

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

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

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

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

لا تظهر Paytrail في صفحة الدفع: تحقق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن Test mode مفعّل أو أن Merchant ID وSecret key مملوءان (وليس حساب الاختبار العام 375917). تحقق من أن عملة السلة هي EUR. وفي Payment > Preferences تحقق من أن الوحدة مسموح بها لعملة السلة وبلد العميل ومجموعة العميل. تعرض صفحة الإعدادات تحذيرًا عند غياب بيانات الاعتماد أو خطأ عملة المتجر.

تمت عملية الدفع لكن لم يُنشأ أي طلب: لم يصل callback إلى متجرك، ولم يعد العميل إلى المتجر. يجب أن يكون Callback URL الظاهر في قسم الطلبات متاحًا عبر الإنترنت (دون مصادقة أساسية أو جدار ناري يعترض الطريق).

يرد callback أو الرجوع بالرسالة Payment verification failed.: التوقيع غير صالح، أو لا تنتمي الدفعة إلى محاولة دفع لهذه السلة. لا يتغير شيء. تحقق من أن Secret key صحيح وينتمي إلى Merchant ID.

يرد callback بالرسالة Temporarily unavailable: كان الطلب يُؤكَّد من طلب آخر في اللحظة نفسها، أو تعذّر إنشاء الطلب (مثلًا لأن الوحدة معطّلة). ستعيد Paytrail الاتصال. انظر إلى حقل Log لمعرفة السبب.

يرى العميل خطأ عند اختيار Paytrail: انظر إلى حقل Log في صفحة الوحدة. فمثلًا تعني Paytrail API error (401) بيانات اعتماد خاطئة. فعّل Debug log لمزيد من التفاصيل.

لا يُحفظ Merchant ID: يجب أن يحتوي على أرقام فقط. انسخه من جديد من لوحة تاجر Paytrail.

الطلب في حالة Paytrail payment on hold: اقرأ الملاحظات في كتلة Paytrail payment. والسبب هو مبلغ مدفوع مختلف، أو دفعة بعد الإلغاء، أو دفعة اختبار في الوضع الحي.

يفشل الاسترداد: اقرأ الرسالة. تعني This order has no confirmed Paytrail payment. Refund it manually. أنه لا توجد دفعة Paytrail مؤكدة لاستردادها. وتعني The live Paytrail credentials used for this payment are missing. Enter them in the Paytrail settings. أن الدفعة تمت في الوضع الحي ولم تُضبط بيانات الاعتماد الحية. وتعني Invalid refund amount: at most … أن المبلغ أكبر مما تبقّى للاسترداد. وإذا كانت وسيلة الدفع تدعم الاسترداد عبر البريد الإلكتروني فقط، فيحتاج الطلب إلى البريد الإلكتروني للعميل.

خطّاف للمطورين: يعدّل الخطّاف actionWcpPaytrailPaymentRequest طلب الدفع قبل توقيعه وإرساله.

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

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

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