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

المتطلبات

OpenCart: الإصدار 3.0.x (تم الاختبار على 3.0.5.0) أو 4.0.2 وما بعده (تم الاختبار على 4.1.0.3).

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

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

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

Currency: يجب أن يدفع العميل بعملة يقبلها بلد حسابك: المكسيك — MXN أو USD، كولومبيا — COP أو USD، بيرو — PEN أو USD. وبالنسبة إلى العملات الأخرى تُخفى طريقة الدفع عند الدفع.

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

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

التثبيت

التنزيل ملف zip واحد يضم الحزم الخاصة بإصداري OpenCart. فُكّه على جهاز الكمبيوتر الخاص بك. ويحتوي على README.txt، وحزمة OpenCart 3 wcp_openpay_gateway-oc3-(version).ocmod.zip، وحزمة OpenCart 4 wcp_openpay_gateway.ocmod.zip. ثبّت الحزمة الخاصة بإصدار OpenCart لديك فقط. مفتاح الترخيص هو نفسه للإصدارين.

OpenCart 3

1. في لوحة الإدارة انتقل إلى Extensions > Installer، وانقر على Upload، واختر الملف wcp_openpay_gateway-oc3-(version).ocmod.zip. لا يحتوي الامتداد على تعديلات OCMOD، لذلك لا حاجة إلى تحديث Extensions > Modifications. وبدلًا من أداة التثبيت، يمكنك أيضًا نسخ محتوى المجلد upload في هذه الحزمة إلى المجلد الجذر لمتجرك.

2. انتقل إلى Extensions > Extensions واختر النوع Payments. ابحث عن VibeFox OpenPay Gateway وانقر على Install (زر + الأخضر). يحتاج مستخدم الإدارة لديك إلى صلاحية تعديل قائمة امتدادات الدفع.

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

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

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

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

OpenCart 4

1. في لوحة الإدارة انتقل إلى Extensions > Installer، وانقر على Upload، واختر الملف wcp_openpay_gateway.ocmod.zip. لا تُغيّر اسم الملف: يأخذ OpenCart 4 رمز الامتداد من اسم الملف، ولا تعمل الحزمة بعد إعادة تسميتها.

2. تظهر الحزمة في قائمة الامتدادات المثبَّتة في الصفحة نفسها. انقر على Install (زر + الأخضر) بجوارها.

3. انتقل إلى Extensions > Extensions واختر النوع Payments. ابحث عن VibeFox OpenPay Gateway وانقر على Install (زر + الأخضر)، ثم على Edit (زر القلم).

4. أدخل مفتاح الترخيص ومفاتيح OpenPay وWebhook كما في الخطوات من 3 إلى 6 الخاصة بـ OpenCart 3. صفحة الإعدادات وحقولها متطابقة في الإصدارين، ويختلف فقط عنوان Webhook (انظر Webhook).

يبدأ التثبيت الجديد بطريقة الدفع معطّلة ووضع بيئة الاختبار مفعّلًا.

الإعداد

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

عند الحفظ، تُتحقق المفاتيح. يمكن أن يحتوي Merchant ID على أحرف وأرقام فقط، ويجب أن يبدأ المفتاح الخاص بـ sk_ والمفتاح العام بـ pk_. لا تُحفظ القيمة غير الصالحة: تبقى القيمة السابقة ويظهر خطأ، مثل Sandbox: The private key must start with sk_. ويسري الأمر نفسه على Sort Order إذا لم يكن عددًا صحيحًا (Sort Order must be a whole number — the previous value was kept.)، وعلى Total إذا لم يكن رقمًا أكبر من 0 أو يساويه. تُحفظ الحقول الأخرى. وإذا كانت طريقة الدفع مفعّلة لكن مفاتيح الوضع الحالي غير مكتملة، فستظهر لك أيضًا رسالة تفيد بأن البوابة ستبقى مخفية في صفحة الدفع. يُرفض Title الفارغ أو الذي يتجاوز 128 حرفًا برسالة Enter a title for the payment method (1 to 128 characters).، ولا يُحفظ عندها أي شيء.

OpenPay

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

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

Description: النص الذي يظهر فوق نموذج البطاقة في خطوة Confirm Order. الافتراضي: Pay securely with your credit or debit card. قد يطلب منك البنك تأكيد الدفع (3D Secure).

Sort Order: ترتيب OpenPay بين طرق الدفع في صفحة الدفع. اتركه فارغًا أو أدخل عددًا صحيحًا (الأعداد السالبة مسموح بها).

Geo Zone: اعرض OpenPay فقط لعناوين الدفع الواقعة ضمن المنطقة الجغرافية المحددة. الافتراضي: All zones. تُضبط المناطق الجغرافية في System > Localisation > Geo Zones. في OpenCart 4، عندما لا يطلب المتجر عنوان دفع، يُستخدم عنوان الشحن.

Total: إجمالي الدفع، بعملة المتجر الافتراضية، الذي يجب أن يبلغه الطلب قبل عرض OpenPay. اتركه فارغًا لعرض OpenPay مهما كان الإجمالي.

حساب 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 the saved key on save أسفل الحقل، ثم انقر على Save.

Webhook

لا يُعد Webhook إلزاميًا، لكنه موصى به. فهو يؤكد المدفوعات عندما لا يعود العميل من صفحة 3D Secure، مثل حالة إغلاق المتصفح. في لوحة OpenPay انتقل إلى Settings > Webhooks وأضف عنوان URL المعروض في Webhook URL في هذا القسم. يبدو العنوان في OpenCart 3 هكذا: https://your-store/index.php?route=extension/payment/wcp_openpay_gateway/webhook، وفي OpenCart 4 هكذا: https://your-store/index.php?route=extension/wcp_openpay_gateway/payment/wcp_openpay_gateway.webhook، ويُبنى من عنوان واجهة المتجر في تثبيت OpenCart الخاص بك. انسخه تمامًا كما تعرضه الإعدادات. أضف Webhook في لوحة كل وضع تستخدمه (بيئة الاختبار والإنتاج).

عند إضافة Webhook يرسل OpenPay رمز تحقق إلى هذا العنوان. يظهر الرمز في هذا القسم مع تاريخ وصوله، حتى تتمكن من تأكيد Webhook في لوحة OpenPay. وإلى أن يحدث ذلك يعرض القسم No verification code received yet.

يعالج الامتداد هذه الأحداث:

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

الطلبات

ينشئ OpenCart الطلب في خطوة Confirm Order بدون حالة (طلب مفقود). ولا يحصل الطلب على حالة إلا بعد أن يؤكد OpenPay عملية الخصم. تترك البطاقة المرفوضة أو فشل التحقق بـ 3D Secure الطلب بلا حالة، ويوضح ملاحظة السبب، ويمكن للعميل أن يدفع مرة أخرى. يسرد كل حقل أدناه حالات طلبات OpenCart لديك؛ ويمكنك إنشاء حالاتك الخاصة في System > Localisation > Order Statuses.

Order Status After Payment: أكّد OpenPay عملية الخصم، ويتطابق مبلغها وعملتها مع الطلب. الافتراضي: Processing.

Awaiting OpenPay Payment: عملية الخصم قيد التنفيذ (لم تُحصَّل بعد)؛ يُكملها Webhook أو يفشلها لاحقًا. الافتراضي: Pending.

OpenPay Payment On Hold: خصم OpenPay مبلغًا أو عملة مختلفين عن الطلب، أو اكتملت عملية الخصم بعد إلغاء الطلب. الافتراضي: Pending.

Payment Error Status: فشلت عملية الخصم لطلب ينتظر OpenPay أو معلّق، أو أُلغيت، أو انتهت صلاحيتها. الافتراضي: Failed.

Refunded Status: استُردت عملية الخصم بالكامل من صفحة الطلب. الاستردادات الجزئية تضيف ملاحظة فقط. الافتراضي: Refunded.

متقدم

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

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

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

الاستيراد / التصدير

Export: Download JSON يحفظ الإعدادات في ملف JSON. لا تُصدَّر المفاتيح الخاصة.

Import: الصق ملف JSON مُصدَّرًا سابقًا وانقر على Import لاستعادة الإعدادات. تبقى المفاتيح الخاصة المحفوظة كما هي.

الدفع

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

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

عندما يعود العميل يقرأ الامتداد عملية الخصم من واجهة برمجة تطبيقات OpenPay. ولا يُعلَّم الطلب على أنه مدفوع إلا بعد تأكيد OpenPay: يجب أن تنتمي عملية الخصم إلى هذا الطلب، وأن تكون مكتملة، وأن تتطابق تمامًا مع إجمالي الطلب وعملته. ثم يحصل الطلب على حالته بالطريقة المعتادة في OpenCart، مع رسائل البريد الإلكتروني المعتادة للطلب وتحديث المخزون، ويرى العميل صفحة نجاح الطلب في OpenCart مع الرسالة 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. وتبقى السلة محفوظة. وفي OpenCart 4 تظهر هذه الرسالة فوق صفحة الدفع. ينشئ OpenCart 3 طلبًا جديدًا في كل مرة تظهر فيها خطوة Confirm Order، أما OpenCart 4 فيحتفظ بطلب واحد للدفع ويحدّثه، فيدفع العميل الطلب نفسه مرة أخرى في محاولة جديدة. وقبل أي محاولة جديدة يتحقق الامتداد من عملية الخصم السابقة للسلة: فإذا كانت قد دُفعت فعلًا، يحصل ذلك الطلب على حالته دون خصم ثانٍ؛ وإذا كانت ما زالت قيد التنفيذ، يرى العميل A previous payment for this order is still being processed. Please do not pay again — the order will be updated automatically.؛ وإذا تعذر التحقق من حالتها، فلا يُنفَّذ أي خصم جديد، ويرى العميل We could not confirm the status of your previous payment attempt. Please try again in a few minutes. ولا تُخصم سلة سبق دفعها مرة أخرى أبدًا.

يحتفظ OpenCart 4 بالطلب في صفحة الدفع حتى تظهر صفحة النجاح. وإذا أُغلق ذلك الطلب في الأثناء (مثلًا فشل خصمه بعد أن كان ينتظر الدفع، أو ألغيته أو استرددته)، يُعاد العميل إلى صفحة الدفع مع الرسالة This order can no longer be paid. Please reload the checkout page and confirm the order again.، وعند النقر التالي على Confirm Order يُدفع طلب جديد. وإذا كان لذلك الطلب حالة بالفعل، وكانت السلة تحتوي الآن على منتجات أو كميات أخرى، يُعاد العميل إلى صفحة الدفع أيضًا، وتحصل السلة الجديدة على طلب جديد.

تتلقى البطاقات المرفوضة رسالة واضحة، مثل 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 التقنية على العملاء أبدًا؛ بل تُرسل إلى السجل وملاحظات الطلب.

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

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

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

حالات الطلبات

No status (missing order): العميل في صفحة 3D Secure، أو لم يُكمل الدفع، أو رُفضت البطاقة. وفي Sales > Orders لا تظهر هذه الطلبات إلا عند ضبط مرشح Order Status على Missing Orders.

في OpenCart 4 يمكن أن يحصل طلب الدفع غير المدفوع على الحالة Voided، التي يضبطها OpenCart 4 عندما يعود العميل إلى خطوة Confirm Order. يعامل الامتداد هذا الطلب كطلب بلا حالة، ويُؤكده لاحقًا أي دفع يأتي بعد ذلك.

Order Status After Payment (default Processing): تم تأكيد الدفع. تعرض ملاحظة معرّف عملية الخصم في OpenPay والوضع (الإنتاج أو بيئة الاختبار).

Awaiting OpenPay Payment (default Pending): يُبلغ OpenPay بأن عملية الخصم قيد التنفيذ (لم تُحصَّل بعد). ينتقل الطلب إلى Order Status After Payment عند اكتمال عملية الخصم، أو إلى Payment Error Status إذا فشلت.

OpenPay Payment On Hold (default Pending): يُبلغ OpenPay عن عملية خصم مكتملة بمبلغ أو عملة تختلف عن الطلب (لا يُعلَّم الطلب كمدفوع، وتعرض الملاحظة الفرق)، أو وصلت دفعة لطلب سبق إلغاؤه أو استرداده. تحقق من الطلب ثم نفّذه، أو استرد الدفعة.

Payment Error Status (default Failed): فشلت عملية خصم قيد التنفيذ، أو أُلغيت، أو انتهت صلاحيتها.

Refunded Status (default Refunded): استُردت عملية الخصم بالكامل عبر الامتداد.

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

الملاحظات هي إدخالات في History الطلب لا يراها العميل.

تبويب VibeFox OpenPay Gateway

في Sales > Orders افتح طلبًا دُفع عبر OpenPay. في أسفل صفحة الطلب، بجوار History وAdditional، يعرض التبويب VibeFox OpenPay Gateway معرّف عملية الخصم، وحالتها، والبيئة وبلد الحساب مع التسمية Sandbox لمدفوعات بيئة الاختبار، والمبالغ Charged / order، والمبلغ المسترد، ونموذج الاسترداد، وسجل الاسترداد، وOpenPay notes الخاصة بالطلب. يظهر التبويب للمستخدمين الذين يملكون صلاحية الوصول إلى الامتداد.

الاسترداد

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

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

لا ترد مرتجعات المنتجات في Sales > Returns أي أموال عبر OpenPay.

تصل الاستردادات والنزاعات التي تتم في لوحة OpenPay عبر Webhook وتُضاف إلى الملاحظات مرة واحدة. ولا تتغير حالة الطلب تلقائيًا؛ حدّثها يدويًا عند الحاجة.

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

يعمل الامتداد بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox OpenPay Gateway هي أول كتلة في Extensions > Extensions > Payments > VibeFox OpenPay Gateway > Edit، فوق الإعدادات. الصق المفتاح في License key وانقر على Activate. بعد ذلك تعرض الكتلة المفتاح مخفيًا جزئيًا، والحالة (مثل تاريخ انتهاء صلاحية الترخيص ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وتحتها السطر Product: opencart-payment-openpay والرابط Manage licenses and domains in your account الذي يفتح حسابك في vibefox.net. لا يستطيع تغيير المفتاح إلا مستخدمو الإدارة الذين يملكون صلاحية Modify للامتداد. وتتبع نصوص الكتلة لغة لوحة الإدارة (وتشمل الإنجليزية والروسية).

إذا لم يُقبل المفتاح، تبيّن الكتلة السبب، مثل Key not found، أو This key belongs to another product، أو Domain limit reached، أو License expired on مع تاريخ. بعد تغيير عنوان المتجر، أو بعد تحرير خانة نطاق في حسابك، انقر على Check now. وإذا تعذّر الوصول إلى خادم التراخيص، يستمر الامتداد في العمل بآخر حالة معروفة.

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

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

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

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

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

تم الدفع لكن الطلب بقي بلا حالة: لم يعد العميل من صفحة 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 لمعرفة السبب.

يعرض عنوان Webhook في المتصفح invalid body: هذا طبيعي. يقبل العنوان الإشعارات الصادرة من OpenPay فقط.

يرى العميل 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: استُخدمت بطاقة اختبار من بيئة الاختبار بينما وضع بيئة الاختبار متوقف.

يرى العميل Billing email is required for OpenPay: ليس للطلب بريد إلكتروني صالح.

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

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

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

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

انتقل إلى Extensions > Extensions، واختر النوع Payments، ثم انقر على Uninstall (الزر الأحمر −) بجوار VibeFox OpenPay Gateway. يُحذف مفتاح ترخيص هذا الامتداد وحالة الترخيص دائمًا. ويحذف OpenCart دائمًا إعدادات الامتداد الخاصة به: Enable / Disable، وSort Order، وGeo Zone، وTotal، وحالات الطلبات في قسم Orders، التي تعود إلى قيمها الافتراضية عند إعادة التثبيت. كما يُحذف حدث OpenCart الخاص بالامتداد (وفي OpenCart 4 أيضًا أحداثه وإجراء بدء التشغيل الخاص به، الذي يسمح بمرور Webhook وعودة 3D Secure في وضع الصيانة). وإذا كان Delete data on uninstall مفعّلًا، تُحذف بقية إعدادات البوابة (العنوان، والوصف، وبلد الحساب، ووضع بيئة الاختبار، والمفاتيح، وتسجيل الأحداث)، ورمز التحقق المحفوظ لـ Webhook، والسجل. وإذا كان معطّلًا، تُحفظ لاستخدامها عند إعادة التثبيت لاحقًا. تُحفظ سجلات عمليات الخصم والاسترداد في OpenPay دائمًا، لذلك يمكن استرداد الطلبات المدفوعة سابقًا بعد إعادة التثبيت. وتحتفظ الطلبات الحالية بملاحظات الدفع الخاصة بها.

في OpenCart 4، ولحذف ملفات الامتداد أيضًا، انتقل إلى Extensions > Installer بعد إلغاء التثبيت، وانقر على Uninstall (زر − البرتقالي) بجوار VibeFox OpenPay Gateway في قائمة الامتدادات المثبَّتة، ثم على Delete (زر سلة المهملات الأحمر) لحذف الحزمة المرفوعة.

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