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

المتطلبات

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

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

العملة: البيزو الفلبيني (PHP). تظهر PayMongo في الدفع فقط للسلال المقومة بـ PHP. إذا لم تكن العملة الافتراضية لمتجرك PHP، تنبّهك صفحة الإعدادات، ويجب على العملاء التحويل إلى PHP لرؤية PayMongo.

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

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

التثبيت

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

2. عند اكتمال الرفع، انقر على Configure، أو ابحث لاحقًا عن VibeFox PayMongo Payment Gateway في قائمة الوحدات وانقر على Configure.

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

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

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

عند التثبيت تُنشئ الوحدة حالتين للطلب: Awaiting PayMongo payment وPayMongo payment on hold. في Payment > Preferences، تحقّق من أن الوحدة مسموح بها للبيزو الفلبيني ولدول عملائك ومجموعات عملائك.

الإعدادات

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

PayMongo

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

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

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

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

مفاتيح API

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

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

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

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

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

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

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

Clear saved secrets: ضع علامة على مفتاح أو سر وانقر على Save لإزالته. الحقل الفارغ يُبقي القيمة المحفوظة.

Webhook

يُخبر الـ webhook متجرك بأن الدفعة قد تمت، حتى عندما يغلق العميل المتصفح بعد الدفع. أنشئ webhook في لوحة تحكم PayMongo (أو عبر واجهة برمجة تطبيقات PayMongo) لكل وضع، التجريبي والفعلي، باستخدام الرابط المعروض في Webhook URL في هذا القسم. مع الروابط الودية يبدو كالتالي https://your-shop/module/wcp_paymongo_payment_gateway/webhook، وقد يتضمن رمز لغة مثل /en/. انسخ الرابط تمامًا كما تعرضه الإعدادات.

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

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

الطلبات

Order status after payment: حالة الطلب التي تُعيَّن بعد الدفع الناجح.

المدفوعات التي ما زالت قيد المعالجة تنتظر في Awaiting PayMongo payment. عدم تطابق المبلغ أو العملة، وعمليات الدفع التجريبية في متجر فعلي، تذهب دائمًا إلى PayMongo payment on hold.

متقدم

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

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

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

الدفع

في خطوة الدفع يختار العميل طريقة الدفع (افتراضيًا PayMongo (Card, GCash, GrabPay, Maya)) ويرى وصفها. في الوضع التجريبي يعرض الدفع أيضًا Test mode: no real payment will be made. لا تُعرض PayMongo إلا للسلال المقومة بـ PHP التي يبلغ إجماليها ₱100.00 على الأقل.

بعد التأكيد تُنشئ الوحدة PayMongo Checkout Session بإجمالي السلة بـ PHP، مع سطر واحد Cart # ورقم السلة، وترسل العميل إلى صفحة الدفع لدى PayMongo. تُمرَّر إلى PayMongo بيانات العميل: الاسم والبريد الإلكتروني والهاتف وعنوان الفوترة. هناك يختار العميل إحدى الطرق المحددة ويدفع. لا يوجد طلب في هذه المرحلة.

بعد الدفع يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكد PayMongo ذلك: تستعلم الوحدة واجهة برمجة تطبيقات PayMongo عن الدفعة عندما يعود العميل وعندما يصل الـ webhook. عندئذ يُنشأ الطلب ويرى العميل صفحة تأكيد الطلب القياسية مع Your PayMongo payment has been received. إذا كانت PayMongo ما زالت تعالج الدفعة عند عودة العميل، يُنشأ الطلب في Awaiting PayMongo payment وتعرض الصفحة PayMongo is still processing your payment. Your order will be updated as soon as PayMongo confirms it — please do not pay again. إذا فشلت هذه الدفعة لاحقًا، تعرض الصفحة Your PayMongo payment was not completed. Please contact us about this order. إذا تعذّر الوصول إلى PayMongo عند عودة العميل، تظهر صفحة Payment confirmation تطلب من العميل عدم الدفع مرة أخرى وتعرض زر Check again؛ ويُنشئ الـ webhook الطلب فور وصوله.

إذا ألغى العميل الدفع في صفحة 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. تبقى السلة محفوظة. تتحقق المحاولة الجديدة أولًا من المحاولة السابقة: إذا دُفعت في هذه الأثناء، يُنشأ الطلب دون دفعة جديدة؛ وإلا تنتهي صلاحية رابط الدفع السابق في PayMongo، فلا يمكن دفع السلة مرتين. وما دامت الدفعة السابقة قيد المعالجة، يرى العميل Your previous PayMongo payment for this order is still being processed. Please wait a few minutes before trying again.

إذا تعذّر على PayMongo بدء الدفع، يبقى العميل في صفحة الدفع مع رسالة قصيرة، مثل 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. يُكتب السبب التقني في السجل.

يعمل الـ webhook أثناء وضع الصيانة في المتجر، ولا يُحظر بقيد الدولة في متجرك.

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

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

حالات الطلب

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

Payment accepted or Delivered: تم تأكيد الدفعة. تتبع الحالة Order status after payment. تُسجَّل الدفعة بمعرّف دفعة PayMongo (pay_...) كمعرّف للمعاملة، وتعرض ملاحظة الدفعة والمبلغ وطريقة الدفع والوضع وكيفية التأكيد (عبر webhook أو عند العودة).

Awaiting PayMongo payment: عاد العميل بينما كانت PayMongo ما زالت تعالج الدفعة. ينتقل الطلب إلى حالة الدفع المكتمل عندما تؤكد PayMongo ذلك.

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

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

Refunded: استُرد الدفع بالكامل من خلال الوحدة.

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

كتلة PayMongo payment

تعرض صفحة الطلب كتلة PayMongo payment تتضمن معرّف الدفعة وطريقتها لدى PayMongo، و payment intent، و checkout، والوضع، والحالة، والمبلغ المدفوع والمبلغ المسترد، وشارة Test mode للدفعات التجريبية، وملاحظات PayMongo الخاصة بالطلب، وسجل الاستردادات.

الاستردادات

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

لا تُنشئ الوحدة إشعارات دائنة. أزرار الاسترداد القياسية في PrestaShop على صفحة الطلب لا تعيد الأموال عبر PayMongo. لا تُنسخ الاستردادات التي تتم في لوحة تحكم PayMongo إلى PrestaShop. استرد من كتلة الطلب بدلًا من ذلك، أو حدّث الطلب يدويًا.

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

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

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

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

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

لا تظهر PayMongo في الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن الوضع الحالي لديه مفتاح سري (Test secret key في الوضع التجريبي، وLive secret key في الوضع الفعلي)، وأن السلة بـ PHP، وأن إجمالي السلة ₱100.00 على الأقل. في Payment > Preferences تحقق من أن الوحدة مسموح بها لعملة السلة وبلد العميل ومجموعة العميل.

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

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

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

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

يرد webhook بـ Busy, retry: كان الطلب يُؤكَّد بطلب آخر في الوقت نفسه، أو تعذّر إنشاء الطلب (مثلًا إذا كانت الوحدة معطّلة). تعيد PayMongo محاولة الـ webhook تلقائيًا. السبب موجود في Log.

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

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

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

يرى العميل خطأ عند اختيار PayMongo: راجع حقل Log في صفحة الوحدة. يعطي المفتاح السري الخاطئ رسالة بأن طريقة الدفع غير متاحة مؤقتًا. طريقة دفع غير مفعّلة في حساب PayMongo الخاص بك تجعل PayMongo ترفض الدفع؛ أزلها من Payment methods.

دفعات تجريبية في متجر فعلي: دفعة تجريبية تصل بينما المتجر في الوضع الفعلي تضع الطلب في PayMongo payment on hold مع ملاحظة بأنه لم يُستلم أي مال. تُعرف الدفعات الفعلية دائمًا، حتى بعد العودة إلى الوضع التجريبي، وتُسترد بالمفتاح الفعلي.

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

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

يمكن للمطورين تغيير بيانات Checkout Session باستخدام الخطاف actionPaymongoPCheckoutSessionData.

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

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

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