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

المتطلبات

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

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

HTTPS: يجب أن يستخدم متجرك HTTPS، لأن نموذج البطاقة موجود في صفحة الدفع لديك.

حساب OpenPay: حساب OpenPay من المكسيك أو كولومبيا أو بيرو. تحتاج إلى Merchant ID الخاص به والمفتاح الخاص (sk_...) والمفتاح العام (pk_...). للوحتَي البيئة التجريبية والإنتاج معرّفات Merchant ID ومفاتيح مختلفة، وتحتفظ الوحدة النمطية بها منفصلة.

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

تُدخل البطاقة في صفحة الدفع لديك، لكنها تُقرأ وتُحوَّل إلى رمز في المتصفح بواسطة openpay.js. حقول البطاقة بلا اسم ولا تُرسل إلى خادمك أبدًا. ولأن نموذج البطاقة موجود في صفحتك، فإن نطاق PCI DSS الخاص بك هو SAQ A-EP؛ استشر البنك المُعالج (acquirer).

التثبيت

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

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

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

4. اختر Account country وأدخل مفاتيح البيئة التجريبية والإنتاج (انظر الإعدادات).

5. موصى به: أضف عنوان URL الخاص بالـ webhook في لوحة OpenPay (انظر الإعدادات).

6. فعّل Enable / Disable وانقر على Save. جرّب دفعة بالبطاقات التجريبية لبيئة OpenPay التجريبية، ثم أوقف Sandbox mode لقبول مدفوعات حقيقية.

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

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة النمطية: Modules > Module Manager > VibeFox OpenPay Gateway > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كاملة. وفوق الحقول، تحذّرك الصفحة عندما تكون مفاتيح الوضع الحالي غير مكتملة (فتُخفى طريقة الدفع عندئذٍ عند الدفع)، وعندما لا يقبل بلد الحساب المختار العملة الافتراضية لمتجرك، وتعرض Sandbox mode is enabled — no real charges are made. ما دام وضع البيئة التجريبية مفعّلًا.

عند الحفظ تُفحص المفاتيح. يجوز أن يحتوي Merchant ID على أحرف وأرقام فقط، ويجب أن يبدأ المفتاح الخاص بـ sk_ والمفتاح العام بـ pk_. لا تُحفظ القيم غير الصالحة: تبقى القيمة السابقة ويظهر خطأ، مثل Sandbox: The private key must start with sk_. وإذا كانت طريقة الدفع مفعّلة لكن مفاتيح الوضع الحالي غير مكتملة، فستظهر لك رسالة تفيد بأن البوابة ستبقى مخفية عند الدفع. ولا يُقبل Title الفارغ، فتظهر رسالة Enter a title for the payment method.

OpenPay

Enable / Disable: Enable OpenPay card payments يُفعّل طريقة الدفع أو يُوقفها. الافتراضي: متوقف.

Title: اسم طريقة الدفع الذي يراه العملاء عند الدفع، وهو أيضًا الاسم المحفوظ في الطلب. الافتراضي: Credit or debit card (OpenPay). مطلوب.

Description: النص الذي يظهر فوق نموذج البطاقة عند الدفع. الافتراضي: Pay securely with your credit or debit card. Your bank may ask you to confirm the payment (3D Secure).

حساب OpenPay

يوجد Merchant ID والمفتاح الخاص (sk_) والمفتاح العام (pk_) في لوحة OpenPay الخاصة بك ضمن Settings (Configuración). يحتوي القسم على روابط للوحات البيئة التجريبية والإنتاج في المكسيك وكولومبيا وبيرو.

Account country: بلد حساب OpenPay الخاص بك. يحدد واجهة OpenPay البرمجية، ومكتبة openpay.js لذلك البلد، والعملات المقبولة. الافتراضي: Mexico.

Sandbox mode: يستخدم البيئة التجريبية لـ OpenPay (مفاتيح اختبار، دون خصومات حقيقية) ويحوّل المفاتيح والواجهة البرمجية معًا إلى البيئة التجريبية. تظهر شارة SANDBOX MODE عند الدفع ما دام الوضع مفعّلًا. الافتراضي: مفعّل. أوقفه لقبول مدفوعات حقيقية.

Sandbox Merchant ID: معرّف Merchant ID من لوحة البيئة التجريبية، Settings (Configuración)، مفاتيح API.

Sandbox Private Key: المفتاح الخاص للبيئة التجريبية. يبدأ بـ sk_. يُستخدم على الخادم فقط؛ لا تشاركه أبدًا.

Sandbox Public Key: المفتاح العام للبيئة التجريبية. يبدأ بـ pk_. يستخدمه openpay.js في المتصفح لتحويل البطاقة إلى رمز.

Live Merchant ID: معرّف Merchant ID من لوحة الإنتاج، Settings (Configuración)، مفاتيح API.

Live Private Key: المفتاح الخاص للإنتاج (sk_...).

Live Public Key: المفتاح العام للإنتاج (pk_...).

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

Clear saved secrets: ضع علامة على مفتاح خاص وانقر على Save لحذفه. الحقل الفارغ يُبقي القيمة المحفوظة.

Webhook

الـ webhook غير إلزامي، لكنه موصى به. فهو يؤكد المدفوعات عندما لا يعود العميل من صفحة 3D Secure، مثلًا بعد إغلاق المتصفح. في لوحة OpenPay اذهب إلى Settings > Webhooks وأضف العنوان الظاهر في Webhook URL في هذا القسم. مع الروابط الودية يكون بالشكل https://your-shop/module/wcp_openpay_gateway/webhook، وقد يحتوي على رمز لغة مثل /en/. انسخه تمامًا كما تعرضه الإعدادات. أضف الـ webhook في لوحة كل وضع تستخدمه (البيئة التجريبية والإنتاج).

عند إضافة الـ webhook، ترسل OpenPay رمز تحقق إلى هذا العنوان. يظهر الرمز في هذا القسم مع تاريخ وصوله، حتى تتمكن من تأكيد الـ webhook في لوحة OpenPay.

حدد هذه الأحداث (وهي مدرجة في هذا القسم أيضًا):

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

متقدم

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

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

Delete data on uninstall: عند التفعيل، يؤدي إلغاء تثبيت الوحدة النمطية إلى حذف إعدادات البوابة ورمز تحقق الـ webhook المحفوظ والسجلات. أما سجلات الخصم في OpenPay الخاصة بالطلبات فهي سجل مدفوعات وتبقى دائمًا، لذا يمكن استرداد الطلبات حتى بعد إعادة التثبيت. الافتراضي: متوقف.

الدفع

في خطوة الدفع يختار العميل طريقة الدفع (افتراضيًا Credit or debit card (OpenPay)) ويملأ Cardholder name وCard number وExpiry (MM/YY) وCard code (CVV). في وضع البيئة التجريبية يعرض النموذج SANDBOX MODE — Test environment. No real charges will be made. عندما يؤكد العميل، يحوّل openpay.js البطاقة إلى رمز لمرة واحدة داخل المتصفح، وتضيف مكتبة مكافحة الاحتيال معرّف جلسة الجهاز. لا يُرسل إلى متجرك سوى هاتين القيمتين ومعرّف السلة. إذا كان النموذج غير مكتمل، يظهر أسفله Please fill in all card fields.

ثم تنشئ الوحدة النمطية الخصم بـ 3D Secure لإجمالي السلة بعملة السلة، وترسل العميل إلى صفحة 3D Secure الخاصة ببنكه، والتي تقدمها OpenPay. تحصل كل محاولة على مرجع طلب خاص بها في OpenPay. وصف الخصم هو Cart # ورقم السلة واسم متجرك. يُمرَّر اسم العميل وبريده الإلكتروني وهاتفه إلى OpenPay، ولا يُنشأ حساب عميل في OpenPay. لا يوجد طلب في هذه المرحلة.

عندما يعود العميل، تقرأ الوحدة النمطية الخصم من واجهة OpenPay البرمجية. لا يُوسم الطلب كمدفوع إلا بعد تأكيد OpenPay: يجب أن ينتمي الخصم إلى هذه السلة، وأن يكون مكتملًا، وأن يطابق إجمالي السلة وعملتها تمامًا. عندها يُنشأ الطلب، ويرى العميل صفحة تأكيد الطلب مع Your card payment has been received. إذا أبلغت OpenPay أن الخصم قيد المعالجة، يُنشأ الطلب في Awaiting OpenPay payment، وتعرض الصفحة We are confirming your card payment with OpenPay. The order will be updated automatically — please do not pay again. إذا لم تكن النتيجة معروفة بعد، تظهر صفحة Payment confirmation بالنص نفسه مع زر Check again وزر Back to checkout، ويُنشئ الـ webhook الطلب فور وصوله. إذا فشل خصم قيد المعالجة لاحقًا، تعرض صفحة تأكيد الطلب Your OpenPay card payment was not completed. Please contact us about this order.

إذا رُفضت البطاقة أو فشل 3D Secure، يعود العميل إلى الدفع مع The card payment was not completed (declined or 3-D Secure failed). Please try again or use another card. ويمكنه الدفع مجددًا. تُحفظ السلة. قبل أي محاولة جديدة، تتحقق الوحدة النمطية من الخصم السابق للسلة: إذا كان مدفوعًا فعلًا، يُنشأ الطلب منه دون خصم ثانٍ؛ وإذا كان لا يزال قيد المعالجة، يُنشأ الطلب في Awaiting OpenPay payment؛ وإذا تعذر التحقق من حالته، فلا يُجرى أي خصم جديد ويرى العميل We could not confirm the status of your previous payment attempt. Please try again in a few minutes. ولا تُخصم سلة لديها طلب مجددًا أبدًا.

تتلقى البطاقات المرفوضة رسالة واضحة، مثل The card has insufficient funds. Please use another card. أو The card has expired. Please use another card. أو The security code (CVV) is not valid. Please check it and try again. لا تُعرض أخطاء OpenPay التقنية على العملاء أبدًا، بل تذهب إلى السجل.

إذا توقف كوبون في السلة عن الصلاحية بين الدفع وتأكيده، يُزال من الطلب. ينتقل الطلب عندئذٍ إلى OpenPay payment on hold مع ملاحظة، لأن العميل دفع السعر بالخصم.

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

تقبل الوحدة النمطية مدفوعات البطاقات فقط، مع تحصيل فوري. ولا تتضمن البطاقات المحفوظة، ولا الاشتراكات، ولا الأقساط بدون فوائد (MSI) أو التقسيط، ولا الدفع بنقاط البطاقة، ولا الدفع النقدي أو عبر SPEI أو PSE أو CoDi، ولا التفويض والتحصيل المنفصلان.

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

حالات الطلب

لا يوجد طلب بعد: العميل في صفحة 3D Secure، أو لم يُكمل الدفع، أو رُفضت البطاقة. يوجد السلة فقط.

Payment accepted: تم تأكيد الدفع. يُسجَّل الدفع بمعرّف خصم OpenPay كمعرّف للمعاملة، وتعرض ملاحظة معرّف الخصم والوضع (الإنتاج أو البيئة التجريبية).

Awaiting OpenPay payment: تُبلغ OpenPay أن الخصم قيد المعالجة (لم يُحصَّل بعد). ينتقل الطلب إلى Payment accepted عند اكتمال الخصم، أو إلى Payment error إذا فشل.

OpenPay payment on hold: تُبلغ OpenPay عن خصم مكتمل بمبلغ أو عملة مختلفين عن السلة (لا يُوسم الطلب كمدفوع، وتعرض الملاحظة الفرق)، أو أُزيل كوبون، أو وصل دفع لطلب سبق إلغاؤه أو استرداده (يُسجَّل الدفع). راجع الطلب ونفّذه، أو استرد الدفع من لوحة OpenPay.

Payment error: فشل خصم قيد المعالجة أو أُلغي أو انتهت صلاحيته.

Refunded: تم استرداد الخصم بالكامل عبر الوحدة النمطية.

إذا وصل خصم ثانٍ مكتمل لطلب مدفوع أصلًا، فلا يتغير الطلب. وتطلب منك ملاحظة تبدأ بـ WARNING استرداد الخصم المكرر من لوحة OpenPay.

كتلة الدفع في OpenPay

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

الاستردادات

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

لا تدعم OpenPay Colombia استرداد البطاقات عبر الواجهة البرمجية، كما في الإضافات الرسمية لـ OpenPay. وبالنسبة لخصومات كولومبيا، لا تقدم الكتلة نموذج استرداد؛ استرد الخصم من لوحة OpenPay.

لا تُنشئ الوحدة النمطية إشعارات دائنة. أزرار الاسترداد القياسية في PrestaShop في صفحة الطلب لا تعيد الأموال عبر OpenPay.

تصل الاستردادات والاعتراضات التي تتم في لوحة OpenPay عبر الـ webhook، وتُضاف إلى الملاحظات مرة واحدة. لا تتغير حالة الطلب ولا الإشعارات الدائنة تلقائيًا. حدّثها يدويًا إذا لزم الأمر.

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

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

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

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

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

لا تظهر OpenPay عند الدفع: تحقق من أن الترخيص نشط، وأن Enable / Disable مفعّل، وأن الوضع الحالي لديه المفاتيح الثلاثة: مفاتيح البيئة التجريبية في وضع البيئة التجريبية، ومفاتيح الإنتاج في وضع الإنتاج. تحقق من أن عملة السلة مقبولة من Account country (المكسيك: MXN وUSD؛ كولومبيا: COP وUSD؛ بيرو: PEN وUSD). تعرض صفحة الإعدادات تحذيرًا في كل حالة من هذه الحالات. وفي Payment > Preferences تحقق من أن الوحدة مسموح بها لعملة السلة وبلد العميل ومجموعة العملاء.

تمّ الدفع، لكن لم يُنشأ أي طلب: لم يعد العميل من صفحة 3D Secure، والـ webhook لا يعمل. تحقق من أن عنوان الـ webhook مضاف في لوحة OpenPay للوضع الذي تستخدمه، تمامًا كما تعرضه الإعدادات، مع الأحداث المذكورة أعلاه. تحقق من أن مفاتيح الوضع الذي تم فيه الدفع مملوءة: بدونها يرد الـ webhook بـ not configured وتعيد OpenPay المحاولة لاحقًا. يُنشأ الطلب أيضًا عندما يعود العميل إلى المتجر أو عندما يحاول دفع السلة نفسها مرة أخرى.

يرد الـ webhook بـ ignored (unknown order): الخصم لم ينشئه هذا المتجر، مثلًا خصم من متجر آخر على حساب OpenPay نفسه. لا يتغير شيء.

يرد الـ webhook بـ verification failed: تعذر الوصول إلى واجهة OpenPay البرمجية لقراءة الخصم. تعيد OpenPay محاولة الـ webhook.

يرد الـ webhook بـ busy: كانت السلة تُحدَّث بطلب آخر في اللحظة نفسها، أو تعذر إنشاء الطلب (مثلًا لأن الوحدة النمطية معطلة). تعيد OpenPay محاولة الـ webhook. فعّل Debug log لمعرفة السبب.

يرى العميل The secure card form could not be loaded: لم يُحمَّل openpay.js أو مكتبة مكافحة الاحتيال الخاصة بـ OpenPay في المتصفح، أو تعذر إنشاء معرّف جلسة الجهاز. اطلب من العميل إعادة تحميل الصفحة والمحاولة مرة أخرى.

يرى العميل The payment could not be processed right now: رفضت OpenPay الطلب أو لم تستجب. السبب مدوّن في السجل. من الأسباب الشائعة Merchant ID أو مفتاح خاص خاطئ. إذا لم تستجب OpenPay، فتحقق من الخصم في لوحة OpenPay قبل أن يدفع العميل مرة أخرى.

يرى العميل This test card cannot be used for real payments: استُخدمت بطاقة اختبار للبيئة التجريبية بينما كان وضع البيئة التجريبية متوقفًا.

الطلب في OpenPay payment on hold بعد الدفع: اقرأ OpenPay notes في الكتلة (انظر حالات الطلب)، ثم نفّذ الطلب أو استرد الدفع.

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

يفشل الاسترداد بالرسالة The order is being updated right now: كان webhook أو طلب آخر يحدّث الطلب في اللحظة نفسها. أعد المحاولة بعد لحظات.

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

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

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