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

المتطلبات

WordPress: 6.2 أو أحدث.

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

PHP: 8.0 أو أحدث.

HTTPS: تشترط IntaSend استخدام HTTPS للمدفوعات الفعلية وwebhooks. تُظهر صفحة الإعدادات تحذيرًا عند تفعيل وضع الإنتاج وكان عنوان المتجر لا يستخدم HTTPS.

حساب IntaSend: تحتاج إلى المفتاح العام (ISPubKey_...) والمفتاح السري (ISSecretKey_...) لحساب IntaSend، سواء للبيئة التجريبية أو للإنتاج أو لكليهما، وإلى webhook مع عبارة تحقق في لوحة تحكم IntaSend (راجع الإعدادات). يُنشئ المفتاح العام صفحة الدفع. ويُستخدم المفتاح السري على خادمك فقط للاستعلام من IntaSend عن حالة الدفع.

عملة المتجر: KES أو USD أو EUR أو GBP أو UGX أو TZS أو NGN أو GHS أو XAF أو XOF. وبالنسبة إلى العملات الأخرى تُخفى طريقة الدفع.

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

التثبيت

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

2. انقر Activate.

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

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

5. الصق مفاتيح IntaSend الخاصة بالبيئة التجريبية و/أو الإنتاج، وأضف الـ webhook في لوحة تحكم IntaSend، وأدخل عبارة التحقق نفسها في الإضافة (راجع الإعدادات).

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

الإعدادات

جميع الإعدادات موجودة في صفحة واحدة: WooCommerce > Settings > Payments > IntaSend. يعرض مربع الحالة فوق الحقول الرسالة Test mode: IntaSend sandbox, no real money is charged. أو Live mode: real payments are accepted. كما يحذّر إذا كانت مفاتيح الوضع الحالي مفقودة أو غير صحيحة (فتُخفى طريقة الدفع عند الدفع)، أو إذا كانت عملة المتجر غير مدعومة، أو إذا لم تُحدَّد عبارة تحقق الـ webhook، أو إذا استُخدم وضع الإنتاج دون HTTPS. وفي قائمة طرق الدفع، يظهر IntaSend بعبارة «يحتاج إلى إعداد» إلى أن تصبح مفاتيح الوضع الحالي صحيحة. تُزال المسافات الزائدة من المفاتيح الملصقة عند الحفظ.

عام

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

Title: اسم طريقة الدفع الذي يراه العملاء عند الدفع. الافتراضي: IntaSend (M-Pesa, card).

Description: النص الذي يظهر أسفل طريقة الدفع عند الدفع. الافتراضي: You will be redirected to IntaSend to pay securely with M-Pesa, card or another available method.

مفاتيح API

احصل على المفاتيح من لوحة تحكم IntaSend، في Settings > API Keys، بشكل منفصل في لوحة البيئة التجريبية (sandbox) ولوحة الإنتاج. يستخدم وضع الاختبار مفاتيح sandbox وواجهة sandbox API، ويستخدم وضع الإنتاج المفاتيح الفعلية وواجهة الإنتاج. تتحقق الإضافة من أن المفتاح العام يبدأ بـ ISPubKey_، وأن المفتاح السري يبدأ بـ ISSecretKey_، وأن المفاتيح تنتمي إلى الوضع الحالي: مفاتيح sandbox تحتوي على _test، ومفاتيح الإنتاج تحتوي على _live. وإذا لم يتحقق ذلك، تُخفى طريقة الدفع ويوضح مربع الحالة السبب.

Test mode: Use the IntaSend sandbox (no real money is charged). الافتراضي: مفعّل. ألغِ تحديده لقبول المدفوعات الفعلية بمفاتيح الإنتاج. وما دام وضع الاختبار مفعّلًا، تعرض صفحة الدفع أسفل طريقة الدفع الرسالة TEST MODE - IntaSend sandbox, no real money is charged.

Sandbox publishable key: يبدأ بـ ISPubKey_test. يُعرّف نشاطك التجاري عند إنشاء صفحة دفع.

Sandbox secret key: يبدأ بـ ISSecretKey_test. يُستخدم فقط على خادمك لتأكيد المدفوعات عبر Payment Status API.

Live publishable key: يبدأ بـ ISPubKey_live.

Live secret key: يبدأ بـ ISSecretKey_live. يُستخدم فقط على خادمك لتأكيد المدفوعات.

Webhook

يُخبر الـ webhook متجرك بأن الدفع قد تم، حتى عندما لا يعود العميل إلى المتجر (أغلق المتصفح، أو تأخر تأكيد M-Pesa). في لوحة تحكم IntaSend، للبيئة التجريبية وللإنتاج، افتح Webhooks وأضف الرابط المعروض في هذا القسم من الإعدادات. يبدو هكذا: https://your-site/wc-api/intasend_pay/. أدخل هناك عبارة تحقق، والصق العبارة نفسها في الإضافة. استخدم عبارة تحقق واحدة للبيئة التجريبية والإنتاج.

Webhook challenge: عبارة التحقق نفسها الموجودة في لوحة تحكم IntaSend. تُرفض الـ webhooks التي تحمل عبارة مختلفة. وما دام هذا الحقل فارغًا، لا تُعالج الـ webhooks، ولا تُؤكَّد المدفوعات إلا عند عودة العميل إلى المتجر. وتتلقى هذه الـ webhooks الرد Ignored بدلًا من خطأ، حتى لا تعطّل IntaSend الـ webhook قبل أن تُدخل عبارة التحقق.

تتفاعل الإضافة مع حالات الدفع التالية التي يبلغ عنها IntaSend. وقبل تعديل أي طلب، تستعلم عبر Payment Status API عن الحالة الفعلية في كل مرة:

تُستقبل الإشعارات التي لا تمثل مدفوعات صفحة الدفع في هذا المتجر، مثل روابط الدفع أو أحداث إرسال الأموال من الحساب نفسه في IntaSend، بالرد OK وتُتجاهل، حتى لا تعطّل IntaSend الـ webhook.

متقدم

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

Delete data on uninstall: Delete the gateway settings and logs when the plugin is deleted. تُعد مراجع IntaSend المحفوظة في الطلبات سجلًّا للمدفوعات، ولذلك تُحفظ دائمًا. وإلغاء تفعيل الإضافة لا يحذف شيئًا أبدًا. الافتراضي: معطّل.

الدفع

يختار العميل طريقة الدفع (افتراضيًا IntaSend (M-Pesa, card)) ويُتم الطلب. تُنشئ الإضافة صفحة دفع لدى IntaSend بمبلغ الطلب الإجمالي وبعملة الطلب، وتنقل العميل إلى صفحة الدفع المستضافة لدى IntaSend. هناك يدفع العميل عبر M-Pesa أو البطاقة أو طريقة أخرى مفعّلة في حسابك لدى IntaSend. وتُمرَّر بيانات الفوترة من بريد إلكتروني واسم وعنوان وهاتف وبلد إلى IntaSend عندما تطابق قواعد حقولها. أما الحقول الفارغة أو غير المناسبة فتُحذف.

بعد الدفع، يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد تأكيد IntaSend: تستعلم الإضافة عبر Payment Status API عندما يعود العميل وعندما يصل الـ webhook. وإذا لم يُؤكَّد الدفع بعد، تعرض صفحة استلام الطلب الرسالة Your payment is being confirmed by IntaSend (M-Pesa confirmations can take a minute). You will receive an e-mail as soon as it is confirmed. وإذا وُضع الطلب «في الانتظار»، تعرض Your payment was received and your order is being reviewed. We will contact you if anything is needed.

إذا فشل الدفع أو عاد العميل دون أن يدفع، يعود إلى صفحة الدفع (أو صفحة Pay for order) مع الرسالة The payment was not successful. Please try again or choose another payment method. (مع سبب من IntaSend إن وُجد) أو The payment was not completed. Please try again or choose another payment method. ويمكن للعميل إعادة دفع الطلب. ويحصل كل محاولة على مرجع IntaSend خاص بها.

إذا تعذّر على IntaSend بدء الدفع، يرى العميل IntaSend could not start the payment: مع السبب الذي قدمته IntaSend، أو IntaSend is temporarily unavailable. Please try again in a moment or choose another payment method. وتُكتب التفاصيل في السجل.

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

تقبل الإضافة المدفوعات لمرة واحدة فقط. لا تُرسل الاستردادات من WooCommerce إلى IntaSend، ولا تتضمن بطاقات محفوظة أو اشتراكات أو نموذج دفع مضمّنًا (منبثقًا). ولا يمكن إلغاء روابط الدفع القديمة للطلب نفسه لدى IntaSend.

الطلبات

حالات الطلب

Pending payment: أُرسل العميل إلى IntaSend ولم يدفع بعد، أو لم يؤكد IntaSend الدفع بعد.

Processing or Completed: تم تأكيد الدفع. يضبط WooCommerce الحالة المعتادة للطلب المدفوع. تعرض ملاحظة الطلب فاتورة IntaSend، وطريقة الدفع لدى IntaSend، والمبلغ، والوضع (البيئة التجريبية أو الإنتاج)، وطريقة التأكيد (webhook أو عودة العميل). ومعرّف المعاملة هو معرّف فاتورة IntaSend.

On hold: أبلغ IntaSend عن مبلغ أو عملة تختلف عن إجمالي الطلب، أو عن دفع جزئي، أو عن دفع وصل بعد إلغاء الطلب. وتشرح ملاحظة الطلب ذلك. تحقّق من الدفع في لوحة تحكم IntaSend، ثم نفّذ الطلب أو استرد المبلغ.

Failed: فشلت آخر محاولة دفع. وتعرض الملاحظة سبب IntaSend. ويمكن للعميل المحاولة مجددًا.

إذا وصل دفع ثانٍ لطلب مدفوع بالفعل، لا يتغير الطلب مرة أخرى. وإذا كان الدفع مكررًا، تطلب منك ملاحظة استرداده في لوحة تحكم IntaSend. ويضيف الدفع لطلب مُسترَد ملاحظة دون إعادة فتح الطلب.

الاستردادات

لا تُرسل الاستردادات من WooCommerce إلى IntaSend. استرد المدفوعات في لوحة تحكم IntaSend، وسجّل الاسترداد يدويًا في WooCommerce.

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

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

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

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

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

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

لا يظهر IntaSend في صفحة الدفع: تحقّق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن مفاتيح الوضع الحالي مملوءة وتنتمي إلى ذلك الوضع: مفاتيح sandbox (التي تحتوي على _test) في وضع الاختبار، ومفاتيح الإنتاج (التي تحتوي على _live) في وضع الإنتاج. ويجب أن تكون عملة المتجر مدعومة. ويوضح مربع الحالة أعلى صفحة الإعدادات ما الخطأ.

تم الدفع لكن الطلب ما زال في Pending payment: قد تستغرق تأكيدات M-Pesa بعض الوقت. يؤكد الـ webhook الطلب عندما يبلغ IntaSend عن الحالة النهائية. تحقّق من أن رابط الـ webhook في لوحة تحكم IntaSend (البيئة التجريبية أو الإنتاج، حسب الوضع الذي تستخدمه) مطابق تمامًا للرابط الموجود في الإعدادات، وأن عبارة التحقق فيه مطابقة لـ Webhook challenge.

يرد الـ webhook بـ Ignored: webhook challenge not configured: حقل Webhook challenge فارغ. أدخل عبارة التحقق من لوحة تحكم IntaSend.

يرد الـ webhook بـ Invalid challenge: عبارة التحقق في IntaSend وفي الإضافة مختلفتان.

يرد الـ webhook بـ Verification unavailable, retry later أو Busy, retry later: تعذّر الوصول إلى IntaSend في تلك اللحظة، أو كان الطلب يُؤكَّد بواسطة طلب آخر. وسيعيد IntaSend محاولة الـ webhook.

يرد الـ webhook بـ Invoice not verified أو Invoice does not match the reference: لم يؤكد IntaSend أن هذه الفاتورة تخص الطلب. ولن يتغير الطلب.

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

يرى العميل خطأً عند إتمام الطلب: فعّل Debug log وراجع WooCommerce > Status > Logs، المصدر wcp_intasend_pay. يجب أن يكون إجمالي الطلب أكبر من صفر. وإذا ذكر السجل أن عنوان الرجوع يحتوي على رموز لا يقبلها IntaSend، فالسبب هو عنوان المتجر أو معامل اللغة فيه.

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

الإلغاء والحذف

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

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