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

المتطلبات

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

PHP: 8.0 أو أحدث.

العملة: الجنيه الفلبيني (PHP). يظهر PayMongo في صفحة الدفع فقط عندما يدفع العميل بالجنيه الفلبيني ويكون الإجمالي 100.00 ₱ على الأقل. أضف العملة في System > Localisation > Currencies إذا لم تكن موجودة في متجرك. إذا لم تكن العملة الافتراضية لمتجرك هي PHP، تعرض صفحة الإعدادات تحذيرًا، ويجب على العملاء التبديل إلى PHP لرؤية PayMongo.

حساب PayMongo: تحتاج إلى مفاتيح API السرية لحساب PayMongo الخاص بك وإلى ويب هوك لكل وضع (راجع الإعدادات). تُستخدم فقط المفاتيح السرية (sk_test_...، sk_live_...) وأسرار توقيع الويب هوك (whsk_...). المفاتيح العامة غير مطلوبة لأن صفحة الدفع تستضيفها PayMongo. يجب تفعيل طرق الدفع التي تقدمها في حساب PayMongo الخاص بك.

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

التثبيت

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

OpenCart 3

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

2. انتقل إلى Extensions > Extensions واختر النوع Payments. ابحث عن VibeFox PayMongo Payment Gateway وانقر على Install (زر + الأخضر).

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

4. الصق المفاتيح السرية لـ PayMongo، وأنشئ الويب هوك في PayMongo، والصق أسرار التوقيع الخاصة بها (راجع الإعدادات).

5. اختر طرق الدفع، وفعّل Enable/Disable، وانقر على Save. اختبر دفعة مع تشغيل Test mode، ثم أوقفه.

OpenCart 4

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

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

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

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

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

الإعدادات

جميع الإعدادات موجودة في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox PayMongo Payment Gateway > Edit. تُعرض الأقسام في الجهة اليسرى؛ وزر Save أسفل القائمة يحفظ الصفحة كاملة. فوق الإعدادات تحذّرك الصفحة عندما تكون العملة الافتراضية للمتجر غير PHP، أو عندما لا يحتوي الوضع الحالي على مفتاح سري (فلا يظهر PayMongo في الدفع عندئذٍ)، أو لا يحتوي على سر ويب هوك (فلا تُؤكَّد المدفوعات إلا عند عودة العميل إلى متجرك)، وتعرض Test mode is on: no real payments are made. ما دام وضع الاختبار مفعّلًا.

عند الحفظ، لا يمكن أن يكون Title فارغًا (حتى 128 حرفًا)، ويجب أن يكون Sort Order عددًا صحيحًا (الأعداد السالبة مسموحة)، وTotal عددًا أكبر من أو يساوي 0، ويجب أن تكون المنطقة الجغرافية وحالات الطلبات المختارة موجودة؛ وإلا فلن يُحفظ شيء وتشير الصفحة إلى الحقل. لا يُحفظ المفتاح ذو البادئة الخاطئة، لكن الحقول الأخرى تُحفظ (راجع مفاتيح API).

PayMongo

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

Title: اسم طريقة الدفع الذي يراه العميل في الدفع. وهو أيضًا اسم طريقة الدفع المحفوظ في الطلب. الافتراضي: PayMongo (Card, GCash, GrabPay, Maya). مطلوب، حتى 128 حرفًا.

Description: النص الذي يراه العميل في خطوة Confirm Order فوق زر التأكيد. الافتراضي: You will be redirected to PayMongo to pay securely with your card, GCash, GrabPay or Maya.

Payment methods: الطرق المعروضة في صفحة دفع PayMongo. اختر فقط الطرق المفعّلة في حساب PayMongo الخاص بك، وإلا فسترفض PayMongo الدفع. إذا لم تُختر أي طريقة، تُستخدم القيم الافتراضية. الافتراضي: Cards وGCash وGrabPay وMaya.

Sort Order: موضع PayMongo بين طرق الدفع في الدفع. اتركه فارغًا أو أدخل عددًا صحيحًا.

Geo Zone: اعرض PayMongo فقط لعناوين الدفع الواقعة في المنطقة الجغرافية المختارة. الافتراضي: All zones. تُعرَّف المناطق الجغرافية في System > Localisation > Geo Zones.

Total: إجمالي الدفع، بالعملة الافتراضية للمتجر، الذي يجب أن يصل إليه الطلب قبل عرض PayMongo، بالإضافة إلى الحد الأدنى لـ PayMongo وهو 100.00 ₱. اتركه فارغًا إذا لم تكن تريد حدًا أدنى إضافيًا.

مفاتيح API

انسخ المفاتيح السرية من PayMongo Dashboard > Developers > API keys (توجد هناك روابط إلى هذا القسم). المفاتيح العامة غير مطلوبة. يجب أن يبدأ كل مفتاح بالبادئة المتوقعة. القيمة ذات البادئة الخاطئة، مثل مفتاح فعلي وُضع في حقل اختبار، لا تُحفظ: تعرض الصفحة أن الحقل يجب أن يبدأ بالبادئة، وThe previous value was kept.

Test mode: Enable test mode (no real payments). تستخدم المدفوعات الجديدة مفاتيح الاختبار. تحتفظ المدفوعات السابقة بالوضع الذي تمت فيه، لذلك تستخدم فحوصات الحالة والاسترداد المفتاح المطابق. الافتراضي: مفعّل. أوقفه لقبول مدفوعات فعلية. وما دام مفعّلًا يرى العميل في خطوة Confirm Order الرسالة Test mode: no real payment will be made.

Test secret key: المفتاح السري لوضع الاختبار. يبدأ بـ sk_test_.

Test webhook secret: سر توقيع الويب هوك لوضع الاختبار. يبدأ بـ whsk_.

Live secret key: المفتاح السري للوضع الفعلي. يبدأ بـ sk_live_.

Live webhook secret: سر توقيع الويب هوك للوضع الفعلي. يبدأ بـ whsk_.

لا تُعرض المفاتيح والأسرار المحفوظة مرة أخرى. يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا كنت تريد تغييرها. لإزالة قيمة محفوظة، فعّل Clear the saved value on save أسفل الحقل وانقر على Save.

Webhook

يُخبر الويب هوك متجرك بأن الدفعة تمت، حتى عندما يغلق العميل المتصفح بعد الدفع. أنشئ ويب هوك في PayMongo Dashboard (أو عبر واجهة PayMongo البرمجية) لكل وضع، الاختبار والفعلي، مع الرابط المعروض في Webhook URL في هذا القسم. في OpenCart 3 يبدو الرابط هكذا: https://your-store/index.php?route=extension/payment/wcp_paymongo_payment_gateway/webhook، وفي OpenCart 4: https://your-store/index.php?route=extension/wcp_paymongo_payment_gateway/payment/wcp_paymongo_payment_gateway.webhook ويُبنى من عنوان واجهة متجرك في تثبيت OpenCart. انسخ الرابط تمامًا كما تعرضه الإعدادات.

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

انسخ سر التوقيع (whsk_...) لكل ويب هوك إلى Test webhook secret أو Live webhook secret. تُرفض الويب هوكات التي لا تحمل توقيعًا صالحًا. يُتحقق من التوقيع بسر وضعه، ويجب أن يطابق وضع الحدث هذا الوضع، لذلك لا يؤكد ويب هوك الاختبار أبدًا دفعة فعلية. تُعاد مراجعة كل حدث عبر واجهة PayMongo البرمجية بالمفتاح السري لوضع الدفعة قبل تغيير أي طلب. تُتجاهل أحداث الدفعات التي لم تبدأ في هذا المتجر. وبدون الويب هوك لا يُؤكَّد الطلب إلا عندما يعود العميل إلى المتجر بعد الدفع.

الطلبات

ينشئ OpenCart الطلب في خطوة Confirm Order دون حالة (طلب مفقود). ولا يحصل الطلب على حالة إلا بعد أن تؤكد PayMongo الدفعة. لا توجد في OpenCart حالة On hold: افتراضيًا تكون حالة الانتظار وحالة التعليق كلتاهما Pending، ويفرّق بينهما تبويب PayMongo وملاحظات الطلب. يمكنك إنشاء حالاتك الخاصة في System > Localisation > Order Statuses واختيارها هنا. يسرد كل حقل أدناه حالات طلبات OpenCart الخاصة بك.

Order status after payment: الحالة التي تُضبط بعد نجاح الدفع. الافتراضي: قيد المعالجة. تناسب Complete السلع الافتراضية أو القابلة للتنزيل التي لا تحتاج إلى شحن.

Awaiting PayMongo payment: أنهى العميل الخطوات في صفحة PayMongo، لكن الدفعة لا تزال قيد المعالجة (مثل التحويل المصرفي عبر الإنترنت). يكمل الويب هوك أو الفحص التالي الطلب. الافتراضي: Pending.

PayMongo payment on hold: عدم تطابق المبلغ أو العملة، أو دفعة اختبار على متجر فعلي، أو دفعة وصلت بعد إلغاء الطلب. تشرح ملاحظة السبب. الافتراضي: Pending.

Failed status: فشلت دفعة معلّقة لاحقًا (payment.failed). تترك محاولة فاشلة لطلب دون حالة الطلب بلا حالة، ويمكن للعميل الدفع مجددًا. الافتراضي: Failed.

Cancelled status: الحالة التي تمنحها لطلب ملغى. تضع الدفعة التي تصل لاحقًا الطلب في حالة التعليق بدلًا من إكماله. الافتراضي: Canceled.

Refunded status: تُضبط بعد استرداد الدفعة كاملة من تبويب الطلب. الافتراضي: Refunded.

متقدم

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

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

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

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

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

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

الدفع

في خطوة Payment Method يختار العميل طريقة الدفع (افتراضيًا PayMongo (Card, GCash, GrabPay, Maya)). في خطوة Confirm Order يرى العميل وصفك والملاحظة After you confirm the order you will be redirected to PayMongo to complete the payment. ينشئ OpenCart الطلب في هذه الخطوة، ما يزال دون حالة. في OpenCart 4 يختار العميل طريقة الدفع بزر Choose في كتلة طريقة الدفع، في نافذة Payment method options، وينقر على Confirm Order أسفل صفحة الدفع.

عندما ينقر العميل على Confirm Order، تنشئ الإضافة جلسة دفع PayMongo (Checkout Session) بإجمالي الطلب بالجنيه الفلبيني، مع سطر Order # ورقم الطلب، وتوجّه العميل إلى صفحة دفع PayMongo. يُمرَّر اسم العميل وبريده الإلكتروني وهاتفه وعنوان الفوترة إلى PayMongo. هناك يختار العميل إحدى الطرق المحددة ويدفع. تسجّل ملاحظة في الطلب جلسة دفع PayMongo.

بعد الدفع يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكد PayMongo ذلك: تسأل الإضافة واجهة PayMongo البرمجية عن الدفعة عندما يعود العميل وعندما يصل الويب هوك. ثم يحصل الطلب على حالته بالطريقة المعيارية في OpenCart، مع رسائل الطلب المعتادة وتحديث المخزون، ويرى العميل صفحة نجاح الطلب في OpenCart مع الرسالة Your PayMongo payment has been received. إذا كانت PayMongo ما تزال تعالج الدفعة عند عودة العميل، يحصل الطلب على حالة الانتظار وتعرض الصفحة PayMongo is still processing your payment. Your order will be updated as soon as PayMongo confirms it — please do not pay again. وبالنسبة إلى طلب في حالة التعليق تعرض Your payment was received and is being reviewed. We will update your order shortly. إذا تعذّر الوصول إلى PayMongo عند عودة العميل، تقول صفحة Payment confirmation: Your payment is being confirmed by PayMongo. You will receive an e-mail as soon as it is confirmed — please do not pay again. مع زر Check again؛ ويضبط الويب هوك حالة الطلب بمجرد وصوله. عندما ينتقل الطلب من حالة الانتظار إلى حالة مدفوع أو حالة فشل الدفع، يتلقى العميل رسالة تغيّر الحالة المعتادة من OpenCart.

إذا ألغى العميل في صفحة PayMongo أو لم يُكمل الدفع، يعود إلى الدفع مع الرسالة You cancelled the PayMongo payment. You can try again or choose another payment method. أو Your PayMongo payment was not completed. You can try again or choose another payment method. تُحفظ السلة. في OpenCart 4 تظهر هذه الرسائل فوق صفحة الدفع. تتحقق المحاولة الجديدة (ينشئ OpenCart 3 طلبًا جديدًا في كل مرة تُعرض فيها خطوة Confirm Order، ويُحدِّث OpenCart 4 طلب الدفع) أولًا من السابقة: إذا دُفعت في هذه الأثناء، تُؤكَّد الدفعة دون دفع جديد؛ وإلا تنتهي صلاحية رابط دفع PayMongo السابق، فلا يمكن دفع السلة مرتين. وما دامت الدفعة السابقة قيد المعالجة يرى العميل Your previous PayMongo payment for this order is still being processed. Please wait a few minutes before trying again. إذا كان طلب آخر من السلة نفسها قد دُفع أو ينتظر الدفع، يُنقل العميل إلى صفحة النجاح. يُعامَل أي تغيير في السلة، بما في ذلك كمية جديدة، كسلة جديدة تحتاج إلى دفعة خاصة بها.

يُبقي OpenCart 4 الطلب في الدفع حتى تُعرض صفحة النجاح. إذا أُغلق هذا الطلب في هذه الأثناء (مثلًا ألغيته)، أو دُفع لسلة أخرى، يُعاد العميل إلى الدفع مع الرسالة Your previous order is already closed. Please confirm the order again: the cart will be paid with a new order. ويدفع الزر Confirm Order التالي طلبًا جديدًا. لا يظهر الطلب المدفوع أبدًا كمدفوع لسلة مختلفة.

إذا تعذّر على PayMongo بدء الدفع، يبقى العميل في خطوة Confirm Order مع رسالة قصيرة فوق الزر، مثل The payment could not be started. Please try again or choose another payment method. أو PayMongo could not be reached. Please try again in a moment. يُكتب السبب التقني في السجل.

يعمل الويب هوك أيضًا والمتجر في وضع الصيانة، لأن OpenCart يسمح بمرور طلبات إضافات الدفع (في OpenCart 4 تضيف الإضافة إجراء بدء تشغيل خاصًا بها لهذا الغرض، يسمح أيضًا بعودة العميل من PayMongo).

تقبل الإضافة المدفوعات لمرة واحدة في صفحة PayMongo. لا توجد حقول بطاقة في صفحة الدفع الخاصة بك، ولا بطاقات محفوظة، ولا اشتراكات أو مدفوعات متكررة، ولا تقسيط، ولا فصل بين التفويض والتحصيل.

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

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

بلا حالة (طلب مفقود): أُرسل العميل إلى PayMongo ولم يدفع، أو لم تؤكد PayMongo الدفعة بعد. في Sales > Orders لا تظهر هذه الطلبات إلا عند ضبط المرشّح Order Status على Missing Orders.

حالة الطلب بعد الدفع (الافتراضي قيد المعالجة): تم تأكيد الدفعة. تعرض ملاحظة دفعة PayMongo والمبلغ والطريقة والوضع وكيفية تأكيدها (ويب هوك أو عودة أو إعادة محاولة دفع).

دفعة PayMongo قيد الانتظار (الافتراضي Pending): عاد العميل بينما كانت PayMongo ما تزال تعالج الدفعة. ينتقل الطلب إلى حالة المدفوع عندما تؤكد PayMongo.

دفعة PayMongo في حالة التعليق (الافتراضي Pending): المبلغ المدفوع أو العملة يختلف عن إجمالي الطلب؛ أو دُفعت الدفعة في وضع الاختبار بينما المتجر في الوضع الفعلي، فلم تصل أي أموال؛ أو وصلت الدفعة بعد إلغاء الطلب. تشرح الملاحظة ذلك. راجع الطلب وعالجه أو استرد الدفعة.

حالة الفشل (الافتراضي Failed): أبلغ ويب هوك payment.failed موقَّع أن آخر محاولة دفع لطلب قيد الانتظار قد فشلت. تعرض الملاحظة رمز فشل PayMongo ورسالته. إذا نجحت الدفعة نفسها لاحقًا، ينتقل الطلب إلى حالة المدفوع.

حالة الاسترداد (الافتراضي Refunded): استُردت الدفعة كاملة عبر الإضافة.

إذا وصلت دفعة ثانية لطلب مدفوع بالفعل، أو لطلب آخر من سلة مدفوعة بالفعل، فلا يتغير الطلب المدفوع. تطلب منك ملاحظة استرداد الدفعة المكررة في PayMongo Dashboard. لا يُعاد فتح طلب دُفع ثم أُلغي أو استُرد أبدًا.

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

تبويب VibeFox PayMongo Payment Gateway

في Sales > Orders افتح طلبًا دُفع عبر PayMongo. في أسفل صفحة الطلب، بجوار History وAdditional، يعرض تبويب VibeFox PayMongo Payment Gateway الحقول PayMongo payment وPayMongo payment intent وPayMongo checkout وPayMongo mode مع التسمية Test mode للدفعات التجريبية، وStatus، والمبالغ Paid / refunded، ونموذج الاسترداد، وسجل الاستردادات، وNotes الطلب. يُعرض التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة.

الاستردادات

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

لا ترسل مرتجعات المنتجات في Sales > Returns أي أموال عبر PayMongo. لا تُبلَّغ إلى OpenCart الاستردادات التي تتم في PayMongo Dashboard. استرد من تبويب الطلب بدلًا من ذلك، أو حدّث الطلب يدويًا.

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

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

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

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

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

لا يظهر PayMongo في الدفع: تحقق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن الوضع الحالي لديه مفتاح سري (Test secret key في وضع الاختبار، وLive secret key في الوضع الفعلي)، وأن العميل يدفع بالجنيه الفلبيني، وأن الإجمالي 100.00 ₱ على الأقل. تحقق أيضًا من أن عنوان الدفع يقع ضمن Geo Zone المختارة، وأن الطلب يبلغ Total المحدد في الإعدادات.

تمت الدفعة لكن الطلب يبقى دون حالة: الويب هوك لا يعمل ولم يعد العميل إلى المتجر. في PayMongo Dashboard تحقق من وجود ويب هوك في الوضع الذي تستخدمه، وأن عنوانه هو نفس العنوان المعروض في Webhook URL تمامًا، وأن الأحداث الثلاثة محددة. وتحقق من أن سر توقيعه موجود في الحقل المناسب (Test webhook secret أو Live webhook secret).

يرد الويب هوك بـ Invalid signature: سر التوقيع لذلك الوضع مفقود أو يتبع ويب هوك آخر. الصق سر توقيع الويب هوك في حقل وضعه.

يرد الويب هوك بـ Mode mismatch: وُقِّع حدث اختبار كحدث فعلي أو العكس. تحقق من أن كل ويب هوك يتبع الوضع الصحيح.

يرد الويب هوك بـ Temporary error: تعذّر التحقق من الدفعة عبر واجهة PayMongo البرمجية، مثلًا لأن المفتاح السري لوضع الدفعة مفقود. تعيد PayMongo محاولة الويب هوك تلقائيًا.

يرد الويب هوك بـ Busy, retry: كان طلب آخر يؤكد الطلب في اللحظة نفسها، أو تعذّر ضبط حالة الطلب. تعيد PayMongo محاولة الويب هوك تلقائيًا. السبب موجود في Log.

يرد الويب هوك بـ Ignored: الحدث يتبع دفعة لم تبدأ في هذا المتجر، أو وضعًا آخر. لا يتغير شيء.

يعرض رابط الويب هوك في المتصفح Method not allowed: هذا طبيعي. يقبل الرابط طلبات PayMongo فقط.

لم تُحفظ القيمة: لُصق مفتاح في الحقل الخطأ. تبدأ المفاتيح السرية بـ sk_test_ أو sk_live_، وأسرار الويب هوك بـ whsk_.

يرى العميل خطأ بعد Confirm Order: انظر إلى حقل Log في صفحة الإضافة. يعطي المفتاح السري الخاطئ رسالة بأن طريقة الدفع غير متاحة مؤقتًا. تؤدي طريقة دفع غير مفعّلة في حساب PayMongo الخاص بك إلى رفض PayMongo للدفع؛ أزلها من Payment methods. This payment method is not available. Please reload the checkout page. تعني أن جلسة الدفع لم تعد تطابق الطلب، أو أن طريقة الدفع أُوقفت في هذه الأثناء.

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

الطلب في حالة التعليق بعد الدفع: اقرأ الملاحظات في تبويب VibeFox PayMongo Payment Gateway (راجع حالات الطلبات)، ثم عالج الطلب أو استرد الدفعة.

لا يوجد نموذج استرداد في التبويب: الدفعة لم تُؤكَّد بعد، أو استُردت كاملة، أو مجموعة المستخدمين لديك لا تملك صلاحية تعديل الإضافة.

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

للمطورين: قبل إنشاء جلسة الدفع تُطلق الإضافة حدث OpenCart paymongo_p_checkout_session_data مع بيانات الجلسة والطلب.

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

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

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

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