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

المتطلبات

WordPress: 6.0 أو أحدث.

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

PHP: 8.0 أو أحدث.

عملة المتجر: EUR. تقبل Paytrail اليورو فقط. وبالنسبة لأي عملة أخرى، تُخفى وسيلة الدفع عند إتمام الطلب. وتُرسل المبالغ بالسنت.

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

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

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

التثبيت

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

2. انقر على Activate.

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

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

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

6. فعّل خيار Enable/Disable ثم احفظ التغييرات.

الإعدادات

توجد جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > Paytrail. وفوق الحقول، تعرض الصفحة Test mode is active. طالما كان وضع الاختبار قيد التشغيل. وفي الوضع المباشر، تحذرك الصفحة عند فقدان Merchant ID أو Secret key، كما تحذرك عندما لا تكون عملة المتجر EUR. وفي كلتا الحالتين، لا تظهر Paytrail في صفحة إتمام الطلب. وفي قائمة وسائل الدفع، تُميَّز Paytrail بأنها تحتاج إلى إعداد طالما كان الوضع المباشر يفتقر إلى بيانات الاعتماد.

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

General

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

Title: العنوان المعروض للعملاء أثناء إتمام الطلب. القيمة الافتراضية: Paytrail.

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

API credentials

يظهر كل من Merchant ID وSecret key في Paytrail Merchant Panel (تفاصيل الحساب أو التكامل). وتُدعم مدفوعات EUR فقط.

Test mode: خيار Use the Paytrail test account. تستخدم المدفوعات الجديدة حساب الاختبار العام لـ Paytrail (معرّف التاجر 375917) بدلاً من بيانات الاعتماد الخاصة بك. ولا يُخصم أي مال حقيقي. ويرى العملاء Test mode: no real payment will be made. عند إتمام الطلب. وبما أن Secret key لحساب الاختبار عام، يمكن لأي شخص محاكاة عملية دفع لطلب أُنشئ في وضع الاختبار. لذلك لا تترك وضع الاختبار قيد التشغيل أبدًا في متجر مباشر. القيمة الافتراضية: معطّل.

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

Secret key: المفتاح السري الخاص بك في Paytrail. يُستخدم عندما يكون وضع الاختبار معطلاً.

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

Orders

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

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

Advanced

Debug log: خيار Log API requests and callbacks. يُكتب في WooCommerce > Status > Logs، المصدر wcp_paytrail_gateway، بدون بيانات شخصية أو مفاتيح. وتُسجَّل الأخطاء دائمًا. القيمة الافتراضية: معطّل.

Delete data on uninstall: خيار Delete settings, logs and Paytrail order data when the plugin is deleted. إن تعطيل الإضافة لا يحذف أي شيء أبدًا. وبدون بيانات معاملات Paytrail، لن يعود من الممكن استرداد الطلبات القديمة من داخل WooCommerce. القيمة الافتراضية: معطّل.

صفحة الدفع

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

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

بعد الدفع الناجح، يرى العميل صفحة استلام الطلب. وبعد الدفع الملغى أو الفاشل، ينتقل العميل إلى صفحة Pay for order مع الرسالة 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.

إذا لم تتمكن 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 باستخدام Paytrail.

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

تعمل وسيلة الدفع في صفحة الدفع التقليدية، وفي كتلة Checkout، وفي صفحة Pay for order. وهي متوافقة مع تخزين الطلبات عالي الأداء في WooCommerce (HPOS).

يختار العميل وسيلة الدفع في صفحة Paytrail، وليس في صفحة إتمام الطلب بمتجرك. ولا تحتوي الإضافة على ترميز للبطاقات أو حفظها، ولا تدعم WooCommerce Subscriptions، أو المتاجر داخل متجر، أو التفعيل اليدوي للفواتير، أو تقارير التسوية.

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

حالات الطلبات

Pending payment: أُنشئت دفعة Paytrail ولم يدفع العميل بعد. تعرض ملاحظة الطلب معرّف معاملة Paytrail والمبلغ والوضع.

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

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

Failed: فشلت آخر محاولة دفع أو ألغاها العميل. ويمكن للعميل محاولة الدفع مرة أخرى.

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

الاستردادات

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

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

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

لا تُزامن عمليات الاسترداد التي تتم في Paytrail Merchant Panel مع WooCommerce.

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

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

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

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

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

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

لا تظهر Paytrail عند إتمام الطلب: تأكد من أن الترخيص نشط، وأن Enable/Disable قيد التشغيل، وأن Test mode قيد التشغيل أو أن Merchant ID وSecret key ممتلئان. تأكد من أن عملة المتجر (أو عملة الطلب في صفحة Pay for order) هي EUR. وتعرض صفحة الإعدادات تحذيرًا لكل مشكلة من هذه المشكلات.

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

يرد طلب callback أو العودة بـ Payment verification failed.: التوقيع غير صالح، أو أن الدفعة لا تنتمي إلى محاولة دفع خاصة بهذا الطلب. ولا يُعدل الطلب. تأكد من صحة Secret key ومن تبعيته لـ Merchant ID.

لم تُنشأ الدفعة: تعرض ملاحظة الطلب والسجل خطأ Paytrail، على سبيل المثال Paytrail API error (401): … عند استخدام بيانات اعتماد غير صحيحة. شغّل Debug log وراجع WooCommerce > Status > Logs، المصدر wcp_paytrail_gateway.

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

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

فشل الاسترداد: اقرأ الرسالة. تعني This order has no confirmed Paytrail payment. Refund it manually. أنه لا توجد دفعة Paytrail مؤكدة لاستردادها. وتعني رسالة بيانات الاعتماد المباشرة المفقودة أن الدفعة تم إجراؤها في الوضع المباشر ولم تُعيَّن بيانات الاعتماد المباشرة. وإذا كانت وسيلة الدفع تدعم الاستردادات عبر البريد الإلكتروني فقط، فيجب توفر بريد إلكتروني للفوترة في الطلب.

خطافات المطورين: يغير فلتر ptg_payment_request طلب الدفع قبل توقيعه وإرساله؛ بينما يغير فلتر ptg_icon أيقونة إتمام الطلب.

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

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

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

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