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

المتطلبات

WordPress: 6.0 أو أحدث.

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

PHP: 8.0 أو أحدث.

العملة: البيزو الفلبيني (PHP). تُخفى طريقة الدفع عندما تكون عملة المتجر، أو عملة الطلب في صفحة Pay for order، غير PHP.

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

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

التثبيت

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

2. انقر على Activate.

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

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

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

6. اختر طرق الدفع، وفعّل Enable/Disable، ثم احفظ. اختبر دفعة مع تفعيل Test mode، ثم ألغِ تحديده.

الإعداد

توجد جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > PayMongo. تعرض الصفحة فوق الحقول تحذيرًا عندما لا تكون عملة المتجر 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_.

Webhook

يُبلغ الـ webhook متجرك بأن الدفع قد تم، حتى عندما يغلق العميل المتصفح بعد الدفع. أنشئ webhook في لوحة تحكم PayMongo (أو عبر واجهة برمجة تطبيقات PayMongo) لكل وضع، التجريبي والفعلي، باستخدام عنوان URL الظاهر في هذا القسم من الإعدادات. يبدو هكذا: https://your-site/?wc-api=paymongo_p_webhook.

اختر هذه الأحداث:

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

الطلبات

حالة الطلب بعد الدفع: حالة الطلب التي تُعيَّن بعد الدفع الناجح. تُعيَّن الحالة فورًا، من دون تغيير ثانٍ للحالة.

متقدم

Debug log: يكتب Log API calls and webhook events هذه الأحداث في WooCommerce > Status > Logs، بالمصدر wcp_paymongo_payment_gateway. تُسجَّل الأخطاء دائمًا. لا تُسجَّل المفاتيح أو بيانات العملاء أبدًا. الافتراضي: معطّل.

Delete data on uninstall: Delete the settings and logs when the plugin is deleted. تبقى معرّفات PayMongo المحفوظة على الطلبات، لأنها لازمة للاستردادات والمحاسبة. الافتراضي: معطّل.

الدفع

يختار العميل طريقة الدفع (وهي PayMongo (Card, GCash, GrabPay, Maya) افتراضيًا) ويقدم الطلب. في الوضع التجريبي تعرض صفحة الدفع Test mode: no real payment will be made. تنشئ الإضافة جلسة دفع PayMongo بإجمالي الطلب بالبيزو الفلبيني، مع سطر Order # ورقم الطلب، وتنقل العميل إلى صفحة الدفع لدى PayMongo. تُمرَّر إلى PayMongo بيانات العميل: الاسم والبريد الإلكتروني والهاتف وعنوان الفوترة. وهناك يختار العميل إحدى الطرق المحددة ويدفع.

لا تُعرض طريقة الدفع إلا للطلبات التي تبلغ ₱100.00 على الأقل. ولا يمكن دفع إجمالي أقل من ذلك عبر PayMongo.

بعد الدفع، يعود العميل إلى صفحة استلام الطلب في متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكد PayMongo ذلك: تستعلم الإضافة من واجهة برمجة تطبيقات PayMongo عن الدفعة عند عودة العميل وعند وصول الـ webhook. وإذا كانت PayMongo ما زالت تعالج الدفع أو تعذّر الوصول إليها، يصل العميل إلى صفحة استلام الطلب على أي حال، ويُكمل الـ webhook الطلب لاحقًا.

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

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

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

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

حالات الطلب

Pending payment: أُرسل العميل إلى PayMongo ولم يدفع بعد، أو لم تؤكد PayMongo الدفع بعد. تسجّل ملاحظة كل جلسة دفع لدى PayMongo أُنشئت للطلب. وبينما تعالج PayMongo دفعة، تُشير ملاحظة إلى ذلك.

Processing أو Completed: تم تأكيد الدفع. تتبع الحالة الإعداد Order status after payment. تعرض ملاحظة الطلب الدفعة لدى PayMongo والمبلغ والطريقة والوضع. معرّف المعاملة هو معرّف الدفعة لدى PayMongo (pay_...). وتعرض شاشة الطلب جلسة الدفع ونية الدفع والوضع لدى PayMongo أسفل عنوان الفوترة.

On hold: المبلغ أو العملة المدفوعان لا يطابقان الطلب (ملاحظة amount/currency mismatch)؛ أو دُفعت دفعة في الوضع التجريبي بينما المتجر في الوضع الفعلي، فلم يُستلم أي مال؛ أو وصلت الدفعة بعد إلغاء الطلب، مثلًا بسبب انتهاء مهلة حجز المخزون. وتوضح ملاحظة الطلب ذلك. راجع الطلب وعالجه، أو استرد الدفعة.

Failed: أبلغ webhook موقّع من نوع payment.failed بأن آخر محاولة دفع لطلب معلّق قد فشلت. تعرض الملاحظة رمز الفشل ورسالته من PayMongo. يمكن للعميل أن يدفع مرة أخرى.

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

الاستردادات

افتح الطلب، وانقر على Refund، وأدخل المبلغ، ثم انقر على Refund via PayMongo (Card, GCash, GrabPay, Maya) (يعرض الزر عنوان طريقة الدفع لديك). الاستردادات الكاملة والجزئية مدعومة. يُرسل الاسترداد بالمفتاح السري للوضع الذي تمت فيه الدفعة (التجريبي أو الفعلي)، لذلك يجب أن يكون هذا المفتاح مضبوطًا. إذا لم تقبل PayMongo الاسترداد، يعرض WooCommerce الخطأ ولا يُسجَّل أي استرداد. ويُضاف الاسترداد الناجح إلى ملاحظات الطلب مع معرّف الاسترداد لدى PayMongo وحالته.

الاستردادات التي تتم في لوحة تحكم PayMongo لا تُنسخ إلى WooCommerce. استرد من طلب WooCommerce، أو أنشئ استردادًا يدويًا في WooCommerce.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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