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

المتطلبات

WordPress: الإصدار 6.0 أو أحدث.

WooCommerce: الإصدار 7.6 أو أحدث، مثبت ونشط. ترفض الإضافة التفعيل بدونه.

PHP: الإصدار 8.0 أو أحدث.

العملة: تقبل GoPay العملات CZK وEUR وPLN وUSD وGBP وHUF وRON وBGN. عند استخدام عملة أخرى، تُخفى طريقة الدفع في صفحة الدفع.

حساب GoPay: تحتاج إلى GoID وClient ID وClient Secret لحساب التاجر لدى GoPay. تجدها في إعدادات التكامل للحساب. لحساب بيئة الاختبار (sandbox) بيانات اعتماد خاصة به. لا يلزم إعداد أي شيء في حساب GoPay للإشعارات، لكن يجب أن يكون متجرك متاحًا عبر الإنترنت.

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

التثبيت

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

2. انقر Activate.

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

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

5. أدخل GoID وClient ID وClient Secret لبيئة الاختبار، واترك Test Mode مفعّلًا، ثم فعّل Enable/Disable.

6. أنشئ طلبًا تجريبيًا. بعد التأكد من عمل كل شيء، أدخل بيانات اعتماد الإنتاج وأزل علامة الاختيار عن Test Mode.

الإعداد

توجد جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > GoPay. أسفل وصف بوابة الدفع، تعرض الصفحة Sandbox mode — test payments only أو Production mode — real payments. وتعرض تحذيرًا عند غياب GoID أو Client ID أو Client Secret للوضع الحالي، أو عندما لا تقبل GoPay عملة المتجر. في الحالتين، لا تُعرض GoPay في صفحة الدفع. وتُبيّن قائمة طرق الدفع أن إعداد البوابة مطلوب إلى أن تُضاف بيانات اعتماد الوضع الحالي. عند الحفظ، تُمسح رموز الوصول إلى GoPay المخزنة مؤقتًا، فتُستخدم بيانات الاعتماد الجديدة فورًا.

Enable/Disable: يشغّل Enable GoPay payment gateway طريقة الدفع أو يوقفها. الافتراضي: معطّل.

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

Description: وصف طريقة الدفع الذي يظهر عند إتمام الدفع. الافتراضي: Pay securely via GoPay - cards, wallets, bank transfers.

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

تظهر GoID وClient ID وClient Secret في حساب التاجر لدى GoPay (إعدادات التكامل). لحساب الاختبار (sandbox) بيانات اعتماد خاصة به. وثائق API متاحة على doc.gopay.com.

Test Mode: يرسل Enable sandbox/test mode المدفوعات إلى gw.sandbox.gopay.com باستخدام بيانات اعتماد الاختبار. لا تُحصّل أموال حقيقية. أزل علامة الاختيار لقبول مدفوعات حقيقية باستخدام بيانات اعتماد الإنتاج (gate.gopay.cz). الافتراضي: مفعّل.

Sandbox GoID: GoID لحساب GoPay التجريبي (sandbox).

Sandbox Client ID: OAuth Client ID لحساب الاختبار.

Sandbox Client Secret: OAuth Client Secret لحساب الاختبار.

Production GoID: معرّف التاجر لدى GoPay (GoID).

Production Client ID: OAuth Client ID من GoPay.

Production Client Secret: OAuth Client Secret من GoPay.

يتكون GoID من أرقام فقط، مثل 8123456789. إذا أدخلت قيمة أخرى، تعرض الصفحة خطأ وتحتفظ بالقيمة السابقة.

الدفع

Payment Page Language: لغة صفحة الدفع لدى GoPay. الافتراضي: Automatic (site language, then billing country). يستخدم الوضع التلقائي لغة موقعك؛ وإذا لم تكن متاحة لدى GoPay، فيُحدّد بلد الفوترة اللغة، وإلا تُستخدم الإنجليزية. يمكنك أيضًا اختيار واحدة من 19 لغة ثابتة: التشيكية أو الإنجليزية أو السلوفاكية أو الألمانية أو البولندية أو المجرية أو الرومانية أو البلغارية أو الكرواتية أو السلوفينية أو الإستونية أو اللاتفية أو الليتوانية أو الفرنسية أو الإيطالية أو الإسبانية أو البرتغالية أو الأوكرانية أو الروسية.

Order Status After Payment: حالة الطلب التي تُعيّن عند تأكيد الدفع. تُعيّن فورًا بتغيير واحد للحالة وإرسال رسالة بريد إلكتروني واحدة للعميل.

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

يُعلم الإشعار متجرك بإتمام الدفع. يُرسل عنوان URL للإشعار إلى GoPay مع كل دفعة، لذلك لا يلزم إعداد أي شيء في حساب GoPay. يعرض الإعداد عنوان URL، ويكون بالشكل https://your-site/?gopay-api=gopay_payment_notification. يجب أن يكون متاحًا عبر الإنترنت، من دون حماية بكلمة مرور أو وضع صيانة أو جدار حماية أمامه.

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

إعدادات متقدمة

Logging: يكتب Enable logging أحداث GoPay في WooCommerce > Status > Logs ضمن المصدر wcp_gopay_gateway. تُسجّل الأخطاء دائمًا. لا تُسجّل أبدًا بيانات الاعتماد أو الرموز أو بيانات البطاقات أو البريد الإلكتروني أو الهاتف أو العنوان الخاص بالعميل. الافتراضي: معطّل.

Delete Data on Uninstall: الخيار Delete plugin settings, cached access tokens and log files when uninstalled. عند تفعيله، تؤدي إزالة الإضافة إلى حذف إعدادات البوابة ورموز الوصول إلى GoPay المخزنة مؤقتًا والسجلات. الافتراضي: معطّل.

إتمام الدفع

يختار العميل طريقة الدفع (والافتراضية هي GoPay) ثم يقدّم الطلب. تنشئ الإضافة دفعة GoPay بإجمالي الطلب وبعملته، مع المنتجات والشحن والرسوم، ثم ترسل العميل إلى صفحة الدفع لدى GoPay. تعرض GoPay هناك طرق الدفع المفعّلة في حسابك، مثل بطاقات الدفع وApple Pay وGoogle Pay والتحويلات المصرفية. تُرسل إلى GoPay بيانات اسم الفوترة والبريد الإلكتروني والهاتف والعنوان الخاص بالعميل؛ ولا تُرسل الحقول الفارغة. يظهر الدفع لدى GoPay باسم Order ورقم الطلب.

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

إذا لم يكتمل الدفع أو أُلغي أو انتهت صلاحيته، يُنقل العميل إلى صفحة Pay for order مع الرسالة The GoPay payment was not completed. You can try again or choose another payment method. أو The GoPay payment was cancelled or has expired. You can try again or choose another payment method. ويمكن للعميل إعادة دفع الطلب غير المدفوع من تلك الصفحة. أما الطلب المدفوع بالفعل فلا تُنشأ له دفعة GoPay ثانية.

إذا تعذّر على GoPay بدء الدفع، تظهر للعميل رسالة قصيرة، مثل GoPay could not accept the payment details. Please check your billing details (e-mail, phone, address) or choose another payment method. أو GoPay is temporarily unavailable. Please try again in a moment or choose another payment method. ويُضاف السبب التقني إلى ملاحظات الطلب.

تعمل طريقة الدفع في صفحة الدفع الكلاسيكية وكتلتي Cart وCheckout وصفحة Pay for order. في وضع الاختبار، تعرض كتلة Checkout الرسالة Sandbox mode: no real payment will be made. وهي متوافقة مع WooCommerce High-Performance Order Storage (HPOS).

يختار العميل طريقة الدفع في صفحة GoPay؛ ولا يمكن اختيارها في WooCommerce. لا تدعم الإضافة الاشتراكات أو المدفوعات المتكررة، ولا البطاقات المحفوظة أو نموذج الدفع المضمّن، ولا تحصيل التفويضات المسبقة أو إبطالها من WooCommerce.

الطلبات والمبالغ المستردة

حالات الطلب

Pending payment: أُرسل العميل إلى GoPay ولم يدفع بعد، أو لم تؤكد GoPay الدفع بعد.

Processing or Completed: تم تأكيد الدفع. تتبع الحالة إعداد Order Status After Payment. تعرض ملاحظة الطلب معرّف دفعة GoPay وأداة الدفع. معرّف المعاملة هو معرّف دفعة GoPay.

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

Failed: أُلغيت آخر دفعة GoPay لطلب غير مدفوع أو انتهت صلاحيتها.

Refunded: استُردت دفعة GoPay الخاصة بالطلب بالكامل، مثلًا من حساب GoPay.

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

المبالغ المستردة

افتح الطلب، وانقر Refund، وأدخل المبلغ، ثم انقر Refund via GoPay. تتوفر الاستردادات الكاملة والجزئية. لا تقبل GoPay الاستردادات الجزئية إلا بعد مرور 24 ساعة على الدفع. يُرسل الاسترداد في الوضع الذي أُجري فيه الدفع (بيئة الاختبار أو الإنتاج)، لذا يجب إعداد بيانات اعتماد ذلك الوضع. إذا رفضت GoPay الاسترداد، يعرض WooCommerce رسالتها ولا يُسجّل أي استرداد. يُضاف الاسترداد الناجح إلى ملاحظات الطلب. ويُشار أيضًا إلى أن GoPay قبلت الاسترداد للمعالجة لاحقًا.

تصل المبالغ المستردة من حساب GoPay عبر الإشعارات. يغيّر الاسترداد الكامل حالة الطلب إلى مسترد، بينما يضيف الاسترداد الجزئي ملاحظة. ولا تُسجّل تلقائيًا على أنها استردادات WooCommerce.

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

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

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

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

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

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

لا تظهر GoPay عند إتمام الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن بيانات GoID وClient ID وClient Secret للوضع الحالي مدخلة، وأن العملة إحدى CZK أو EUR أو PLN أو USD أو GBP أو HUF أو RON أو BGN. في صفحة Pay for order تُستخدم عملة الطلب. تعرض صفحة الإعدادات تحذيرًا عند خطأ بيانات الاعتماد أو العملة.

تم الدفع، لكن حالة الطلب ما زالت Pending payment: تعذّر على GoPay الوصول إلى عنوان URL للإشعار المعروض في الإعدادات، ولم يعد العميل إلى المتجر. أزل حماية كلمة المرور أو وضع الصيانة أو قواعد جدار الحماية التي تحظر عنوان URL. تحقق من إعداد بيانات اعتماد الوضع الذي أُجري فيه الدفع، إذ يُتحقق من كل إشعار باستخدامها. راجع WooCommerce > Status > Logs للمصدر wcp_gopay_gateway. تعيد GoPay إرسال الإشعارات التي لم تتلقّ ردًا ناجحًا.

يرد الإشعار بالرسالة Order not found: لم يُنشأ الدفع بواسطة هذا المتجر أو حُذف الطلب المرتبط به.

يرد الإشعار بالرسالة Payment state could not be verified: تعذّر الوصول إلى واجهة GoPay البرمجية أو أن بيانات اعتماد ذلك الوضع غير صحيحة. تعيد GoPay إرسال الإشعار.

يرى العميل خطأ عند تقديم الطلب: افتح ملاحظات الطلب أو فعّل Logging. تعرض الملاحظة خطأ GoPay. غالبًا ما يكون السبب بيانات اعتماد خاطئة أو بيانات اعتماد الوضع الآخر. تعني الرسالة المتعلقة ببيانات الفوترة أن GoPay لم تقبل البريد الإلكتروني أو الهاتف أو العنوان.

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

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

فشل الاسترداد: اقرأ رسالة GoPay. لا يمكن إجراء استرداد جزئي إلا بعد مرور 24 ساعة على الدفع. تعني الرسالة المتعلقة بالوضع أن الدفع أُجري في بيئة الاختبار أو الإنتاج، وأن بيانات اعتماد ذلك الوضع غير مضبوطة.

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

للمطورين: يغيّر المرشح gopay_p_payment_payload طلب الدفع، ويغيّر gopay_p_icon أيقونة طريقة الدفع.

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

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

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