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

المتطلبات

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

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

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

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

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

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

التثبيت

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

2. عند انتهاء الرفع، انقر على Configure، أو ابحث لاحقًا عن VibeFox IntaSend Pay Gateway في قائمة الوحدات وانقر على Configure.

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

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

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

عند التثبيت تُنشئ الوحدة حالة الطلب IntaSend payment on hold. وتوفّر PrestaShop وحدة دفع جديدة لجميع العملات والدول ومجموعات العملاء. ويمكنك تقييدها من Payment > Preferences.

الإعداد

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox IntaSend Pay Gateway > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كاملة. وفوق الحقول يعرض مربع الحالة 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، بينما يستخدم وضع الإنتاج مفاتيح الإنتاج وواجهته. وتتحقق الوحدة من أن المفتاح العام يبدأ بـ ISPubKey_، وأن المفتاح السري يبدأ بـ ISSecretKey_، وأن المفاتيح تنتمي إلى الوضع الحالي: تحتوي مفاتيح الـ sandbox على _test، وتحتوي مفاتيح الإنتاج على _live. وإذا لم يتحقق ذلك، تُخفى طريقة الدفع ويوضّح مربع الحالة السبب.

Test mode: يستخدم sandbox الخاص بـ IntaSend، ولا يُخصم أي مبلغ حقيقي. الافتراضي: مفعّل. أوقفه لقبول المدفوعات الحقيقية بمفاتيح الإنتاج. وما دام وضع الاختبار مفعّلًا، تعرض صفحة الدفع أسفل طريقة الدفع العبارة 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 مرة أخرى. يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط عندما تريد تغييرها.

Webhook

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

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

مسح الأسرار المحفوظة: ضع علامة على Sandbox secret key أو Live secret key أو Webhook challenge وانقر على Save لإزالته. الحقل الفارغ يُبقي القيمة المحفوظة.

تتفاعل الوحدة مع حالات الدفع التالية التي تُبلغ عنها IntaSend. وفي كل مرة تستعلم من Payment Status API عن الحالة الفعلية قبل تغيير أي شيء:

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

متقدم

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

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

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

الدفع

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

بعد الدفع يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكده IntaSend: تستعلم الوحدة من Payment Status API عند عودة العميل وعند وصول الـ webhook. ثم يُنشأ الطلب ويرى العميل صفحة تأكيد الطلب المعتادة. وإذا وُضع الطلب في الانتظار، تعرض الصفحة Your payment was received and your order is being reviewed. We will contact you if anything is needed. وإذا لم يُؤكَّد الدفع بعد، أو تعذّر الوصول إلى IntaSend في تلك اللحظة، تعرض صفحة Payment confirmation الرسالة 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. مع الزرين Check again وBack to checkout. وينشئ الـ webhook الطلب بمجرد أن تؤكد IntaSend الدفع.

إذا فشل الدفع، يعود العميل إلى صفحة الدفع مع الرسالة 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. وتُكتب التفاصيل في السجل. ولا يمكن دفع سلة مجموعها صفر عبر IntaSend.

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

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

الطلبات

حالات الطلب

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

Payment accepted: تم تأكيد الدفع. يُسجَّل الدفع بمعرّف فاتورة IntaSend بوصفه معرّف المعاملة، وتعرض ملاحظة الفاتورة وطريقة الدفع لدى IntaSend والمبلغ والوضع (sandbox أو إنتاج) والطريقة التي أُكِّد بها (الـ webhook أو عودة العميل).

IntaSend payment on hold: أبلغت IntaSend عن مبلغ أو عملة مختلفين عن إجمالي السلة، أو عن دفع جزئي، أو عن دفع وصل بعد إلغاء الطلب. تشرح الملاحظة ذلك، ويُسجَّل المبلغ الذي حصلت عليه IntaSend دفعةً إذا كان بعملة الطلب. تحقّق من الدفع في لوحة تحكم IntaSend ثم أكمل الطلب أو استرد الدفع. وإذا وصل الدفع الصحيح لاحقًا، ينتقل الطلب إلى Payment accepted.

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

كتلة الدفع في IntaSend

تعرض صفحة الطلب كتلة IntaSend payment تضم كل محاولة دفع لسلة الطلب (التاريخ والمرجع وصفحة الدفع لدى IntaSend والبيئة والمبلغ والفاتورة والنتيجة، مع سبب الفشل)، وكذلك Invoices processed (الفاتورة وحالتها لدى IntaSend والمبلغ والنتيجة). وهذه الكتلة للقراءة فقط.

الاسترداد

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

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

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

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

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

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

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

تم الدفع لكن لم يُنشأ أي طلب: قد تستغرق تأكيدات M-Pesa بعض الوقت. ينشئ الـ webhook الطلب عندما تُبلغ IntaSend بالحالة النهائية. تحقّق من أن عنوان URL للـ webhook في لوحة تحكم IntaSend (الـ sandbox أو الإنتاج، حسب الوضع الذي تستخدمه) مطابق تمامًا للعنوان الظاهر في Webhook URL، وأن عبارة التحقق فيه هي نفسها Webhook challenge. ويُنشأ الطلب أيضًا عندما يعود العميل إلى المتجر أو ينقر على Check again.

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

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

يرد الـ webhook بالرسالة Verification unavailable, retry later أو Busy, retry later: تعذّر الوصول إلى IntaSend في تلك اللحظة، أو كانت السلة قيد التأكيد من طلب آخر، أو تعذّر إنشاء الطلب (مثلًا لأن الوحدة معطّلة). ستعيد IntaSend محاولة الـ webhook. والسبب مكتوب في السجل.

يرد الـ webhook بالرسالة Invoice not verified أو Invoice does not match the reference: لم تؤكد IntaSend أن هذه الفاتورة تنتمي إلى السلة. ولا يتغير شيء.

يعرض عنوان URL للـ webhook الرسالة Method not allowed في المتصفح: هذا أمر طبيعي. فالعنوان يقبل الطلبات الصادرة من IntaSend فقط.

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

يرى العميل خطأً عند اختيار IntaSend: انظر إلى حقل Log في صفحة الوحدة (فعّل Debug log للحصول على تفاصيل أكثر). وإذا كانت مفاتيح الوضع الحالي خاطئة، يرى العميل الرسالة IntaSend is not available at the moment. Please choose another payment method or contact the store. وإذا ذكر السجل أن عنوان العودة يحتوي على أحرف لا تقبلها IntaSend، فالسبب هو عنوان المتجر.

يرى العميل الرسالة We could not match this payment to an order: رابط العودة تغيّر أو يخص سلة أخرى. وإذا كان العميل قد دفع، فسينشئ الـ webhook الطلب على أي حال.

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

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

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