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

المتطلبات

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

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

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

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

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

التثبيت

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

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

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

4. أدخل GoID وClient ID وClient Secret الخاصة بـ sandbox، واترك Test Mode مفعّلًا، وفعّل Enable/Disable، ثم انقر على Save.

5. أجرِ طلب اختبار. عندما يعمل كل شيء، أدخل بيانات اعتماد الإنتاج وألغِ تفعيل Test Mode.

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

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox GoPay Gateway > Configure. لكل قسم زر Save خاص به، ويحفظ الصفحة كاملة. وفوق الحقول تعرض الصفحة Sandbox mode — test payments only أو Production mode — real payments. وتُظهر تحذيرًا عند غياب GoID أو Client ID أو Client Secret للوضع الحالي، وعندما لا تقبل GoPay عملة المتجر الافتراضية. وفي الحالتين لا تُعرض 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: يرسل المدفوعات إلى gw.sandbox.gopay.com باستخدام بيانات اعتماد sandbox. لا يُخصم أي مبلغ حقيقي. ألغِ تفعيله لقبول مدفوعات حقيقية ببيانات اعتماد الإنتاج. الافتراضي: مفعّل.

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

Sandbox Client ID: معرّف OAuth Client ID لحساب sandbox.

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

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

Production Client ID: معرّف OAuth Client ID الصادر من GoPay.

Production Client Secret: سر OAuth Client Secret الصادر من GoPay.

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

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

Clear saved client secrets: حدّد الخانة وانقر على Save لحذف كلا سري Client Secret المحفوظين. الحقل الفارغ يُبقي القيمة المحفوظة.

الدفع

Payment Page Language: لغة صفحة الدفع الخاصة بـ GoPay. الافتراضي: Automatic (site language, then billing country). يستخدم الخيار التلقائي لغة سلة العميل؛ فإن لم تتوفر هذه اللغة لدى GoPay، تحدد دولة الفوترة اللغة، وإلا فتُستخدم الإنجليزية. ويمكنك أيضًا تثبيت إحدى اللغات التسع عشرة الثابتة: Czech وEnglish وSlovak وGerman وPolish وHungarian وRomanian وBulgarian وCroatian وSlovenian وEstonian وLatvian وLithuanian وFrench وItalian وSpanish وPortuguese وUkrainian وRussian.

Order Status After Payment: حالة الطلب التي تُعيَّن عند تأكيد الدفع.

المدفوعات التي لا تطابق الطلب، والمدفوعات التي تأتي بعد الإلغاء، والمدفوعات المفوّضة مسبقًا تذهب دائمًا إلى GoPay payment on hold.

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

يُخبر الإشعار متجرك بأن الدفع قد تم. ويظهر Notification URL في هذا القسم ويُرسل إلى GoPay مع كل دفعة، لذلك لا يلزم إعداد أي شيء في حساب GoPay. وعند استخدام الروابط الودية يبدو هكذا: https://your-shop/module/wcp_gopay_gateway/webhook، وقد يسبقه رمز لغة مثل /en/. يجب أن يكون متاحًا من الإنترنت: دون حماية بكلمة مرور أو جدار ناري أمامه. ويعمل أثناء وضع الصيانة للمتجر، ولا تحجبه قيود الدولة في متجرك.

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

متقدم

Logging: يكتب أحداث GoPay في logs/gopay_p_debug.log.php داخل مجلد الوحدة. لا يمكن فتح الملف من الويب. تُسجَّل الأخطاء والتحذيرات دائمًا. ولا تُسجَّل بيانات الاعتماد أو الرموز أو بيانات البطاقات أو بريد العميل الإلكتروني واسمه أبدًا. الافتراضي: معطّل.

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

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

الدفع

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

بعد الدفع يعود العميل إلى متجرك. ولا يُعلَّم الطلب كمدفوع إلا بعد تأكيد GoPay: عبر الإشعار أو عبر طلب إلى واجهة GoPay البرمجية عند عودة العميل. ويُعالج الإشعار والرجوع اللذان يصلان في اللحظة نفسها واحدًا تلو الآخر، فلا يُنشأ إلا طلب واحد. ثم يرى العميل صفحة تأكيد الطلب القياسية. وإذا انتقل الطلب إلى GoPay payment on hold، تضيف الصفحة الرسالة Your payment is being reviewed. We will contact you if anything else is needed.

إذا لم تكن GoPay قد أكدت الدفعة عند عودة العميل (مثلًا لأن تحويلًا مصرفيًا في الطريق، أو تعذّر الوصول إلى GoPay)، تعرض صفحة Payment confirmation الرسالة GoPay has not confirmed your payment yet. Your order will be created automatically as soon as the payment is confirmed — please do not pay again. مع زر Check again.

إذا لم تكتمل الدفعة أو أُلغيت أو انتهت صلاحيتها، يعود العميل إلى صفحة الدفع مع الرسالة 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. ويُكتب السبب التقني في السجل.

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

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

حالات الطلب

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

Payment accepted or Delivered: تم تأكيد الدفع. وتتبع الحالة Order Status After Payment. يُسجَّل الدفع بمعرّف دفعة GoPay بوصفه معرّف المعاملة، وتعرض ملاحظة معرّف الدفعة وأداة الدفع.

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

Refunded: سُدِّدت دفعة GoPay الخاصة بالطلب بالكامل، إما عبر الوحدة أو في حساب GoPay.

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

كتلة دفع GoPay

تعرض صفحة الطلب كتلة GoPay payment تتضمن معرّف دفعة GoPay، وحالة GoPay وأداة الدفع، ومبلغ الدفعة، والمبلغ المدفوع والمسترد، وشارة Sandbox للدفعات التجريبية، وسبب المراجعة اليدوية، وسجل الاسترداد، وGoPay notes الخاصة بالطلب.

الاسترداد

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

لا تنشئ الوحدة إشعارات دائنة (credit slips). كما أن أزرار الاسترداد القياسية في PrestaShop في صفحة الطلب لا تعيد الأموال عبر GoPay.

تصل عمليات الاسترداد المنفذة في حساب GoPay عبر الإشعار. يحوّل الاسترداد الكامل الطلب إلى Refunded؛ ويضيف الاسترداد الجزئي ملاحظة. ولا تُضاف إلى سجل الاسترداد في الكتلة.

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

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

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

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

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

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

تمت الدفعة لكن لم يُنشأ أي طلب: تعذّر على GoPay الوصول إلى Notification URL المعروض في الإعدادات، ولم يعد العميل إلى المتجر. أزل حماية كلمة المرور أو قواعد الجدار الناري التي تحجب هذا العنوان. تحقق من أن بيانات اعتماد الوضع الذي أُجريت فيه الدفعة مُعدّة، لأن كل إشعار يُتحقق منه بها. فعّل Logging وانظر إلى الحقل Log. تعيد GoPay إرسال الإشعارات التي لم تحصل على رد ناجح.

Notification answers Order not found: لم تُنشئ هذه الدفعة هذا المتجر، أو حُذفت سلتها.

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

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

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

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

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

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

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

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

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

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