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

المتطلبات

WordPress: 5.8 أو أحدث.

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

PHP: 8.0 أو أحدث.

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

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

الموقع العام: يجب أن يكون رابط التأكيد الخاص بمتجرك متاحًا من الإنترنت، وألا يُحجب بوضع الصيانة أو بجدار الحماية أو بالمصادقة الأساسية.

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

التثبيت

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

2. انقر على Activate.

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

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

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

6. فعّل Enable/Disable. جرّب دفعة في Test Mode باستخدام بطاقات ePayco التجريبية، ثم ألغِ تحديد Test Mode.

الإعدادات

جميع الإعدادات موجودة في صفحة واحدة: WooCommerce > Settings > Payments > ePayco. فوق الحقول تنبهك الصفحة عندما لا تُدخل المفاتيح الأربعة (وعندها تُخفى طريقة الدفع في صفحة الدفع)، وعندما لا تكون عملة المتجر 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. احتفظ به سرًّا.

Test Mode: Enable test mode يُنشئ جلسات الدفع كمعاملات اختبار. يدفع العملاء ببطاقات ePayco التجريبية، ولا يُخصم أي مبلغ حقيقي. لا تدفع معاملات الاختبار أبدًا للطلبات المُنشأة في وضع الإنتاج. الافتراضي: معطّل.

الدفع

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

رابط التأكيد

يخبر رابط التأكيد متجرك بنتيجة الدفع. يُرسل تلقائيًا إلى ePayco مع كل عملية دفع، لذا لا يوجد ما يُضبط في لوحة تحكم ePayco. يعرض هذا القسم الرابط، وهو بهذا الشكل تقريبًا: https://your-site/wc-api/epc_p/. يجب أن يكون متاحًا من الإنترنت، وألا يُحجب بوضع الصيانة أو بجدار الحماية أو بالمصادقة الأساسية.

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

متقدم

Logging: Enable logging يكتب أخطاء API وتأكيدات الدفع في WooCommerce > Status > Logs، ضمن المصدر wcp_epayco_payment. لا تُسجَّل المفاتيح ولا بيانات العملاء. الافتراضي: معطّل.

Delete Data on Uninstall: Remove the gateway settings and logs when the plugin is deleted. إلغاء تفعيل الإضافة لا يحذف أي شيء أبدًا. تبقى بيانات ePayco المحفوظة في الطلبات. الافتراضي: معطّل.

الدفع

يختار العميل طريقة الدفع (افتراضيًا ePayco) ويقدّم الطلب. تُنشئ الإضافة جلسة دفع لـ ePayco بإجمالي الطلب بعملة الطلب، مع ضرائب الطلب ورقم الطلب واسم الفوترة وعنوانها وبريدها الإلكتروني ورقم هاتفها. لغة صفحة الدفع هي الإسبانية أو الإنجليزية، حسب لغة الموقع. ثم ينتقل العميل إلى صفحة دفع الطلب، التي تعرض 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. وفي وضع الاختبار، تعرض الصفحة وصفحة الدفع TEST MODE — use ePayco test cards, no real money is charged.

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

إذا لم يُؤكَّد الدفع بعد، تعرض صفحة استلام الطلب We are waiting for ePayco to confirm your payment. This page does not need to stay open. أما للدفعات المعلّقة (مثل PSE أو الدفع النقدي) فتعرض Your ePayco payment is being confirmed. We will e-mail you as soon as it is approved.

إذا رُفض الدفع، يعود العميل إلى صفحة Pay for order مع الرسالة 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. ويُضاف السبب إلى ملاحظات الطلب والسجل.

تعمل طريقة الدفع في الدفع الكلاسيكي، وفي كتلة الدفع، وفي صفحة Pay for order. وهي متوافقة مع HPOS (High-Performance Order Storage) في WooCommerce. والنصوص التي يراها العميل مترجمة إلى الإسبانية.

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

الطلبات

حالات الطلب

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

Processing: قُبل الدفع (الطلبات التي تحتوي على منتجات افتراضية قابلة للتنزيل فقط تنتقل إلى حالة «مكتمل»، وهو الإعداد الافتراضي في WooCommerce). تعرض ملاحظة الطلب مرجع ePayco والحالة والمبلغ وطريقة الدفع ورمز الموافقة. معرّف معاملة الطلب هو مرجع ePayco (ref_payco).

On hold, payment pending: أبلغ ePayco أن الدفع معلّق أو محجوز، مثل تحويل PSE أو دفعة نقدية. يتغير الطلب تلقائيًا عندما يؤكده ePayco أو يرفضه.

On hold, amount/currency mismatch: وافق ePayco على دفعة يختلف مبلغها أو عملتها عن الطلب. لا تشحن قبل التحقق من المعاملة في لوحة تحكم ePayco.

On hold, payment for a cancelled order: وافق ePayco على دفعة بعد إلغاء الطلب. استعِد الطلب أو استرد الدفعة في ePayco.

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

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

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

الاستردادات: الاستردادات من WooCommerce غير مدعومة. استرد الدفعة في لوحة تحكم ePayco، ثم سجّل الاسترداد في WooCommerce باستخدام Refund manually.

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

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

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

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

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

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

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

تمت عملية الدفع لكن الطلب يبقى Pending payment: لا يصل تأكيد ePayco إلى متجرك. تحقق من أن رابط التأكيد المعروض في الإعدادات يُفتح من الإنترنت، وأنه غير محجوب بوضع الصيانة أو بجدار الحماية أو بإضافة أمان أو بالمصادقة الأساسية. فعّل Logging وانظر في WooCommerce > Status > Logs ضمن المصدر wcp_epayco_payment. كما يُحدَّث الطلب عندما يعود العميل إلى المتجر بعد الدفع.

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

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

يرد التأكيد بـ 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 مفعّل.

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

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

للمطوّرين: توثيق الإضافة يسرد الفلاتر epc_p_supported_currencies (العملات التي تُعرض لها طريقة الدفع)، وepc_p_session_payload (البيانات المرسلة إلى ePayco)، وepc_p_icon (أيقونة صفحة الدفع).

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

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

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