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

المتطلبات

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

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

العملة: البيزو الكولومبي (COP) أو الدولار الأمريكي (USD). بالنسبة للسلال بعملات أخرى تُخفى طريقة الدفع في صفحة الدفع.

حساب ePayco: تحتاج إلى المفاتيح الأربعة لحسابك لدى ePayco: P_CUST_ID_CLIENTE وP_KEY وPUBLIC_KEY وPRIVATE_KEY. توجد في لوحة تحكم ePayco ضمن Integrations, API keys. المفاتيح نفسها تعمل في وضع الاختبار ووضع الإنتاج. طرق الدفع التي يمكن للعميل استخدامها (البطاقات وPSE وشبكات الدفع النقدي والمحافظ) هي الطرق المفعّلة في حسابك لدى ePayco.

الموقع العام: يجب أن يكون عنوان URL للتأكيد في متجرك متاحًا من الإنترنت، وألا يحظره جدار حماية أو المصادقة الأساسية.

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

التثبيت

1. في لوحة الإدارة، اذهب إلى Modules > Module Manager واضغط Upload a module. اختر ملف ZIP الخاص بالوحدة.

2. عند انتهاء الرفع، اضغط Configure، أو ابحث لاحقًا عن VibeFox ePayco Payment في قائمة الوحدات واضغط Configure.

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

4. أدخل المفاتيح الأربعة لـ ePayco واختر نوع الدفع (انظر الإعدادات).

5. فعّل Enable/Disable واضغط Save. جرّب دفعة مع تفعيل Test Mode وبطاقات ePayco التجريبية، ثم أوقف Test Mode.

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

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox ePayco Payment > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كاملة. فوق الحقول تحذّرك الصفحة عند عدم إدخال المفاتيح الأربعة (عندها تُخفى طريقة الدفع في صفحة الدفع) وعند عدم كون العملة الافتراضية لمتجرك COP أو USD، وتعرض Test mode is on: customers pay with ePayco test cards and no real money is charged. أثناء تفعيل وضع الاختبار.

ePayco

Enable/Disable: Enable ePayco Payment يفعّل طريقة الدفع أو يعطّلها. الافتراضي: معطّل.

Title: اسم طريقة الدفع الذي يراه العميل في صفحة الدفع. وهو أيضًا اسم طريقة الدفع المحفوظ في الطلب. الافتراضي: ePayco.

Description: النص الذي يظهر أسفل طريقة الدفع في صفحة الدفع. الافتراضي: Pay securely with ePayco.

مفاتيح حساب ePayco

المفاتيح الأربعة موجودة في لوحة تحكم ePayco ضمن Integrations, API keys. يتحقق P_CUST_ID_CLIENTE وP_KEY من تأكيدات الدفع، بينما ينشئ PUBLIC_KEY وPRIVATE_KEY جلسات الدفع. المفاتيح نفسها تعمل في وضع الاختبار ووضع الإنتاج.

Customer ID (P_CUST_ID_CLIENTE): معرّف عميل ePayco الخاص بك (رقمي).

Secret Key (P_KEY): يُستخدم للتحقق من توقيع تأكيدات الدفع من ePayco. احتفظ به سرًّا.

Public Key (PUBLIC_KEY): مفتاح API العام الخاص بك لدى ePayco.

Private Key (PRIVATE_KEY): مفتاح API الخاص بك لدى ePayco. احتفظ به سرًّا.

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

مسح المفاتيح السرية المحفوظة: ضع علامة على Secret Key (P_KEY) أو Private Key (PRIVATE_KEY) واضغط Save لإزالة المفتاح. الحقل الفارغ يُبقي القيمة المحفوظة.

Test Mode: تُنشأ جلسات الدفع كمعاملات اختبار. يدفع العملاء ببطاقات ePayco التجريبية ولا يُخصم أي مبلغ حقيقي. لا تدفع معاملات الاختبار أبدًا للطلبات المُنشأة في وضع الإنتاج. الافتراضي: معطّل. أثناء تفعيله يرى العملاء TEST MODE — use ePayco test cards, no real money is charged. أسفل طريقة الدفع وفي صفحة الدفع.

الدفع

Checkout Type: طريقة فتح صفحة الدفع الخاصة بـ ePayco.

عنوان URL للتأكيد

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

يجب أن يحمل كل تأكيد توقيعًا صالحًا أُنشئ بمفتاحيك P_CUST_ID_CLIENTE وP_KEY. تُرفض التأكيدات التي لا تحمل توقيعًا صالحًا ولا تغيّر أي شيء. ومن دون التأكيد لا يُنشأ الطلب إلا عندما يعود العميل إلى المتجر بعد الدفع.

متقدم

Logging: يكتب أخطاء API وتأكيدات الدفع في logs/epc_p_debug.log.php داخل مجلد الوحدة. لا يمكن فتح الملف من الويب. لا تُسجَّل المفاتيح وبيانات العملاء. الافتراضي: معطّل. تُسجَّل الأخطاء دائمًا حتى وهو معطّل.

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

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

الدفع

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

ثم يرى العميل صفحة ePayco payment مع Thank you for your order. The secure ePayco checkout opens automatically; if it does not, click the button below. تُفتح صفحة دفع ePayco كنافذة منبثقة أو بإعادة توجيه، حسب Checkout Type. تحتوي الصفحة أيضًا على الزر Pay with ePayco والرابط Choose another payment method. كل نقرة على زر الدفع تُنشئ جلسة ePayco جديدة.

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

في حالة الدفع المعلّق (مثل PSE أو الدفع النقدي) يُنشأ الطلب في حالة Awaiting ePayco payment، وتعرض صفحة التأكيد Your ePayco payment is being confirmed. We will e-mail you as soon as it is approved. إذا رُفض الدفع المعلّق أو انتهت صلاحيته لاحقًا، تعرض الصفحة Your ePayco payment was not completed. Please contact us about this order. إذا لم تؤكد ePayco الدفع بعد عند عودة العميل، تظهر صفحة Payment confirmation تعرض We are waiting for ePayco to confirm your payment. This page does not need to stay open. وزر Check again.

إذا رُفض الدفع، يعود العميل إلى صفحة الدفع مع Your ePayco payment was declined or could not be completed. You can try again or choose another payment method. وإذا عاد العميل دون أن يدفع، فالرسالة هي The ePayco payment was not completed. If you already paid, the order will be updated as soon as ePayco confirms it; otherwise you can try again. تُحفظ السلة ولا يُنشأ أي طلب.

إذا لم تتمكن ePayco من بدء الدفع، يبقى العميل في صفحة الدفع مع رسالة قصيرة، مثل We could not connect to ePayco. Please try again in a moment or choose another payment method. ويُكتب السبب التقني في السجل.

تقبل الوحدة المدفوعات لمرة واحدة فقط. لا توجد استردادات من المتجر، ولا بطاقات محفوظة، أو اشتراكات، أو مدفوعات مجزّأة، ولا تستعلم الوحدة ePayco بشكل دوري عن المعاملات المعلّقة: تُحدَّث الطلبات بتأكيد ePayco وعودة العميل.

الطلبات

حالات الطلب

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

Payment accepted: وافقت ePayco على الدفع. يُسجَّل الدفع بمرجع ePayco (ref_payco) كمعرّف للمعاملة، وتعرض ملاحظة المرجع والحالة والمبلغ وطريقة الدفع ورمز الموافقة.

Awaiting ePayco payment: أبلغت ePayco عن الدفع بأنه معلّق أو محتجز، مثل تحويل PSE أو دفع نقدي. يتغير الطلب تلقائيًا عندما توافق ePayco على الدفع أو ترفضه.

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

Payment error: رُفض الدفع المعلّق أو فشل أو انتهت صلاحيته أو أُلغي. تعرض الملاحظة السبب الذي حددته ePayco. تبقى الدفعة الجديدة الموافق عليها للسلة قادرة على دفع الطلب. ولا يغيّر الفشل المتأخر طلبًا مدفوعًا أبدًا.

Refunded: عكست ePayco دفع هذا الطلب.

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

كتلة دفع ePayco

تعرض صفحة الطلب كتلة ePayco payment تحتوي على المرجع (ref_payco) ومعرّف المعاملة والحالة وطريقة الدفع ورمز الموافقة وتاريخ المعاملة وشارة Test mode للمدفوعات التجريبية وePayco notes الخاصة بالطلب. وفي حالة الطلب في ePayco payment on hold تعرض الكتلة تحذيرًا بالتحقق من المعاملة قبل الشحن.

الاستردادات

لا تُدعم الاستردادات من المتجر. استرد الدفع من لوحة تحكم ePayco، ثم حدّث الطلب في PrestaShop يدويًا إن لزم. تؤدي عملية عكس معاملة الدفع التي تبلغ عنها ePayco إلى وضع الطلب في حالة Refunded.

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

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

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

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

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

لا يظهر ePayco في صفحة الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن المفاتيح الأربعة مُدخلة، وأن عملة السلة COP أو USD. تعرض صفحة الإعدادات تحذيرًا عند نقص المفاتيح. في Payment > Preferences تحقق من أن الوحدة مسموح بها لعملة السلة وبلد العميل ومجموعة العميل.

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

يجيب التأكيد بـ «Invalid signature»: Customer ID (P_CUST_ID_CLIENTE) أو Secret Key (P_KEY) لا يطابق حساب ePayco الذي استلم الدفعة. انسخ الاثنين مرة أخرى من لوحة تحكم ePayco.

يجيب التأكيد بـ «Gateway not configured»: P_CUST_ID_CLIENTE أو P_KEY فارغ. أدخلهما في الإعدادات.

يجيب التأكيد بـ «Order not found»: يشير التأكيد إلى سلة ليس لها دفعة ePayco من هذا المتجر.

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

يرى العميل «We could not connect to ePayco»: رفضت ePayco PUBLIC_KEY وPRIVATE_KEY. يعرض السجل رد ePayco. انسخ المفتاحين مرة أخرى.

يرى العميل «ePayco could not start the payment»: لم تُنشئ ePayco جلسة الدفع. اقرأ خطأ ePayco في السجل.

لا تُفتح صفحة دفع ePayco: يرى العميل The ePayco checkout could not be loaded. Please reload the page or choose another payment method. تعذّر تحميل نص صفحة دفع ePayco في صفحة الدفع. يمكن للعميل إعادة تحميل الصفحة أو استخدام Choose another payment method.

لم تدفع دفعة الاختبار الطلب: معاملات الاختبار لا تدفع الطلبات المُنشأة في وضع الإنتاج أبدًا. أنشئ طلب الاختبار أثناء تفعيل Test Mode.

الطلب في حالة ePayco payment on hold: اقرأ الملاحظات في كتلة ePayco payment (انظر حالات الطلب) وتحقق من المعاملة في لوحة تحكم ePayco قبل الشحن.

الإزالة

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

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