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

المتطلبات

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

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

العملة: يجب أن تكون السلة بعملة يقبلها Paystack: NGN أو USD أو GHS أو ZAR أو KES أو XOF أو EGP أو RWF، حسب ما هو مفعّل في حساب Paystack الخاص بك. مع العملات الأخرى تُخفى طريقة الدفع. في XOF وRWF يقبل Paystack المبالغ الصحيحة فقط.

حساب Paystack: تحتاج إلى المفاتيح السرية لحساب Paystack الخاص بك: المفتاح السري للاختبار (sk_test_...) و/أو المفتاح السري للوضع المباشر (sk_live_...). لا تلزم المفاتيح العامة (pk_...) لأن الدفع يتم في صفحة Paystack المستضافة. في لوحة Paystack تقوم أيضاً بضبط عنوان الـ webhook لمتجرك (راجع الإعدادات). يجب أن يكون متجرك متاحاً من الإنترنت لاستقبال الـ webhooks.

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

التثبيت

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

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

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

4. الصق المفاتيح السرية من لوحة Paystack واضبط عنوان الـ webhook في لوحة Paystack (راجع الإعدادات).

5. فعّل Enable/Disable وانقر على Save. أبقِ Test Mode مفعّلاً حتى تُجري دفعة تجريبية، ثم أوقفه لقبول المدفوعات الحقيقية.

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

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Paystack Payment > Configure. لكل قسم يحتوي على حقول زر Save خاص به، وهذا الزر يحفظ الصفحة كاملة. فوق الحقول يعرض مربع الحالة الوضع: وضع الاختبار: لا يتم خصم أي مبلغ حقيقي. أو الوضع المباشر: تُقبل المدفوعات الحقيقية. ويحذّر أيضاً عندما يكون المفتاح السري للوضع الحالي فارغاً، أو عندما يُدخل مفتاح عام (pk_...) في حقل المفتاح السري، أو عندما يحتوي الوضع المباشر على مفتاح اختبار (sk_test_...) أو يحتوي وضع الاختبار على مفتاح مباشر (sk_live_...)، وعندما لا يقبل Paystack العملة الافتراضية لمتجرك. ما دامت هناك مشكلة في المفتاح تكون طريقة الدفع مخفية عند الدفع.

Paystack

القسم الأول عنوانه Paystack وعليه شارة TEST أو LIVE للوضع الحالي.

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

Title: اسم طريقة الدفع الذي يراه العملاء عند الدفع. وهو أيضاً اسم طريقة الدفع المحفوظ في الطلب. الافتراضي: Paystack. مطلوب.

Description: النص الذي يظهر أسفل طريقة الدفع عند الدفع. الافتراضي: Pay securely using your debit card, credit card, or bank account via Paystack.

مفاتيح API

انسخ المفاتيح السرية من لوحة Paystack، صفحة Settings > API Keys & Webhooks. يحتوي القسم على رابط لهذه الصفحة.

Test Mode: يستخدم المفتاح السري للاختبار للمدفوعات الجديدة، ولا يتم خصم أي مبلغ حقيقي. أوقفه لقبول المدفوعات الحقيقية بالمفتاح السري للوضع المباشر. تستمر المدفوعات التي تمت في الوضع الآخر في استخدام مفتاح وضعها الخاص للتحقق والاسترداد. الافتراضي: مفعّل. ما دام مفعّلاً يرى العملاء أسفل طريقة الدفع العبارة وضع الاختبار مفعّل. لن يتم أي خصم حقيقي.

Test Secret Key: المفتاح السري للاختبار في Paystack. يبدأ بـ sk_test_.

Live Secret Key: المفتاح السري للوضع المباشر في Paystack. يبدأ بـ sk_live_.

لا تُعرض المفاتيح المحفوظة مرة أخرى. يبقى الحقل فارغاً ويعرض محفوظ — اتركه فارغاً للإبقاء عليه. أدخل قيمة جديدة فقط إذا أردت تغييره.

Clear saved secrets: حدد مربع مفتاح ثم انقر على Save لحذفه. الحقل الفارغ يُبقي على القيمة المحفوظة.

Webhook

يُخبر الـ webhook متجرك بأن الدفع قد تم، حتى عندما لا يعود العميل إلى المتجر. في لوحة Paystack، في صفحة Settings > API Keys & Webhooks، اضبط الرابط المعروض في Webhook URL في هذا القسم كـ Test Webhook URL وكـ Live Webhook URL. مع الروابط المختصرة يبدو هكذا: https://your-shop/module/wcp_paystack_payment/webhook، وربما مع رمز لغة مثل /en/. انسخ الرابط تماماً كما تعرضه الإعدادات.

يوقّع Paystack كل webhook بمفتاحك السري، لذلك لا يلزم إعداد أي شيء آخر. تُرفض الـ webhooks التي لا تحمل توقيعاً صالحاً. تستخدم الوحدة الحدث charge.success:

تُجاب الأحداث الأخرى بالرد OK وتُتجاهل. بدون الـ webhook لا يُؤكَّد الطلب إلا عندما يعود العميل إلى المتجر بعد الدفع. التحويلات المصرفية ودفعات USSD التي تكتمل لاحقاً لا تُؤكَّد إلا عبر الـ webhook.

الطلبات

Autocomplete Order: عند التفعيل، تحصل الطلبات المدفوعة على الحالة Delivered بدلاً من Payment accepted، بتغيير حالة واحد. الافتراضي: متوقف.

متقدم

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

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

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

الدفع

في خطوة الدفع يختار العميل طريقة الدفع (افتراضياً Paystack) ويؤكد الطلب. تبدأ الوحدة معاملة Paystack بمجموع السلة بعملة السلة، مع بريد العميل الإلكتروني، وتنقل العميل إلى صفحة الدفع المستضافة لدى Paystack. هناك يدفع العميل بإحدى القنوات المفعّلة في حساب Paystack الخاص بك. تعرض صفحة الدفع رقم السلة واسم العميل. في هذه المرحلة لا يوجد طلب بعد.

بعد الدفع يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد تأكيد Paystack: عندما يعود العميل وعندما يصل الـ webhook، تقرأ الوحدة المعاملة من واجهة برمجة Paystack وتتحقق من المرجع والحالة والمبلغ والعملة. عندها يُنشأ الطلب ويرى العميل صفحة تأكيد الطلب المعتادة.

إذا كان الدفع ما زال قيد المعالجة، كتحويل مصرفي مثلاً، يُنشأ الطلب بالحالة Awaiting Paystack payment عند عودة العميل، وتعرض صفحة التأكيد العبارة يجري تأكيد دفعتك من قِبل Paystack. ستتلقى رسالة بريد إلكتروني فور تأكيدها. يُكمل الـ webhook الطلب لاحقاً. إذا تعذّر الوصول إلى Paystack عند عودة العميل، تطلب صفحة Payment confirmation من العميل عدم الدفع مرة أخرى وتعرض Check again وBack to checkout؛ وينشئ الـ webhook الطلب فور وصوله. بالنسبة لطلب في حالة الانتظار تعرض صفحة التأكيد العبارة تم استلام دفعتك وطلبك قيد المراجعة. سنتصل بك إذا لزم أي شيء.

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

تُفتح صفحة تأكيد الطلب في متصفح العميل نفسه فقط. إذا فُتح رابط العودة في مكان آخر، يُتحقق من الدفع مع ذلك، لكن الطلب لا يظهر: يرى الزائر رسالة محايدة عند الدفع.

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

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

لا تحتوي الوحدة في PrestaShop على نموذج دفع مضمّن أو منبثق، ولا بطاقات محفوظة، ولا اشتراكات، ولا مدفوعات مقسّمة أو حسابات فرعية، ولا توفر اختياراً لقنوات الدفع.

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

حالات الطلب

لا يوجد طلب بعد: أُرسل العميل إلى Paystack ولم يدفع، أو غادر صفحة Paystack، أو لم يؤكد Paystack الدفع بعد. الموجود هو السلة فقط.

Awaiting Paystack payment: عاد العميل بينما كان Paystack ما زال يعالج الدفع، مثل التحويل المصرفي أو USSD. ينتقل الطلب إلى حالة المدفوع عندما يؤكد Paystack الدفع. إذا لم يكتمل هذا الدفع أبداً، يبقى الطلب في هذه الحالة إلى أن تغيّره أنت.

Payment accepted أو Delivered: تم تأكيد الدفع. الحالة هي تم التسليم عندما يكون Autocomplete Order مفعّلاً. يُسجَّل الدفع بمرجع Paystack (pscart_...) كمعرّف للمعاملة. تعرض ملاحظة المبلغ والمرجع ورقم المعاملة والوضع (اختبار أو مباشر) وقناة الدفع ونوع البطاقة وآخر أرقامها في مدفوعات البطاقات، وأي رسوم Paystack دفعها العميل.

Paystack payment on hold: المبلغ أو العملة المدفوعة لا يطابقان الطلب (ملاحظة Paystack amount or currency mismatch)، مثلاً لأن السلة عُدّلت بعد بدء الدفع، أو لأن الدفع وصل بعد إلغاء الطلب. توضح الملاحظة ما يجب فحصه. نفّذ الطلب أو استرد الدفع.

خطأ في الدفع: يُبلغ Paystack بأن آخر محاولة دفع لطلب في Awaiting Paystack payment فشلت أو أُلغيت. فشل محاولة أقدم لا يغيّر الطلب.

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

كتلة Paystack payment

تعرض صفحة الطلب كتلة Paystack payment تتضمن المرجع ومعرّف المعاملة والوضع مع شارة Test mode للمدفوعات التجريبية، وحالة الدفع والقناة والبطاقة، وتاريخ الدفع، والمبالغ المدفوعة والمستردة، وسجل الاسترداد، وPayment notes الخاصة بالطلب.

الاسترداد

في كتلة Paystack payment أدخل المبلغ (يُملأ المبلغ الذي لم يُسترد بعد)، واكتب السبب اختيارياً، ثم انقر على Refund via Paystack. أكّد السؤال هل تريد استرداد هذا المبلغ عبر Paystack؟ لا يمكن التراجع عن هذا الإجراء. الاسترداد الكامل والجزئي مدعومان. تحتاج إلى صلاحية تعديل الطلبات؛ الوصول إلى صفحات الوحدات غير مطلوب. يذهب الاسترداد إلى المعاملة التي دفعت الطلب، ويُستخدم المفتاح السري للوضع (اختبار أو مباشر) الذي تمّت فيه المعاملة، لذلك يجب أن يكون ذلك المفتاح مضبوطاً. تتم الاستردادات بالمبلغ والعملة اللذين حصّلهما Paystack، لذلك بالنسبة لطلب في حالة الانتظار بعد اختلاف في المبلغ أو العملة يمكنك الاسترداد حتى المبلغ الذي دفعه العميل فعلياً، لا إجمالي الطلب. في XOF وRWF يجب أن تكون الاستردادات مبالغ صحيحة. يضع Paystack الاستردادات في قائمة انتظار: تعرض الملاحظة وسجل الاسترداد الحالة التي يعيدها Paystack، مثل pending، ومعرّف الاسترداد. إذا لم يقبل Paystack الاسترداد، تعرض الكتلة فشل الاسترداد عبر Paystack: مع السبب، ولا يُسجَّل أي استرداد. الاسترداد الكامل يضع الطلب في الحالة Refunded. الاسترداد الجزئي لا يغيّر الحالة. الاستردادات متاحة بعد أن يؤكد Paystack الدفع.

لا تُنشئ الوحدة إشعارات دائنة. أزرار الاسترداد القياسية في PrestaShop في صفحة الطلب لا تعيد الأموال عبر Paystack.

الاستردادات التي تُجرى في لوحة Paystack، والحالة النهائية للاستردادات التي يضعها Paystack في قائمة الانتظار، لا تتم مزامنتها مرة أخرى مع PrestaShop. إذا لزم الأمر، سجّلها يدوياً.

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

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

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

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

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

لا يظهر Paystack عند الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن الوضع الحالي لديه مفتاح سري صحيح (Test Secret Key بالمفتاح sk_test_... في وضع الاختبار، وLive Secret Key بالمفتاح sk_live_... في الوضع المباشر)، وأن عملة السلة مقبولة من Paystack. يحدد مربع الحالة في أعلى الإعدادات المشكلة. في Payment > Preferences تحقق من أن الوحدة مسموح بها لعملة السلة ولدولة العميل ولمجموعة العميل.

تم الدفع لكن لم يُنشأ أي طلب: لم يصل الـ webhook إلى متجرك ولم يعد العميل. في لوحة Paystack تحقق من أن Test Webhook URL وLive Webhook URL مطابقان تماماً للرابط الظاهر في Webhook URL، وأنه لا يوجد جدار حماية أو حماية بكلمة مرور تمنعه. فعّل Debug log وراجع الحقل Log للاطلاع على الـ webhooks المرفوضة.

يرد الـ webhook بـ Invalid signature: لم يُوقَّع الـ webhook بالمفتاح السري للاختبار أو المباشر المُدخل في الإعدادات، مثلاً لأن المفاتيح تنتمي إلى حساب Paystack آخر. أدخل مفاتيح الحساب الذي يُرسل الـ webhook.

يرد الـ webhook بـ Secret key not configured: لم يُضبط أي مفتاح سري. أدخل المفاتيح السرية في الإعدادات.

يرد الـ webhook بـ Verification failed أو Busy أو retry later أو Order could not be created, retry later: تعذّرت قراءة المعاملة من واجهة برمجة Paystack في تلك اللحظة، أو كانت السلة تُعالج في الوقت نفسه بعودة العميل، أو تعذّر إنشاء الطلب (مثلاً لأن الوحدة معطّلة). يُعيد Paystack إرسال الـ webhook. يعرض السجل السبب.

يرد الـ webhook بـ OK - unknown reference: لم يُجرَ الدفع لسلة من هذا المتجر، مثلاً صفحة دفع Paystack أو تكامل آخر على الحساب نفسه. يُتجاهل.

يعرض رابط الـ webhook Empty body في المتصفح: هذا طبيعي. يقبل الرابط الطلبات الصادرة من Paystack فقط.

يرى العميل الرسالة «بوابة الدفع غير مُعدّة بشكل صحيح»: المفتاح السري للوضع الحالي مفقود أو خاطئ. أصلحه باتباع مربع الحالة في أعلى الإعدادات.

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

يبقى الطلب في حالة Awaiting Paystack payment: لم يؤكد Paystack الدفع بعد. تحقق من المعاملة في لوحة Paystack ومن إعدادات الـ webhook. إذا لم يُكمل العميل الدفع أبداً، فغيّر الحالة يدوياً.

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

يمكن للمطورين تغيير طلب المعاملة وقائمة العملات باستخدام خطافات الوحدة actionWcpPaystackPaymentRequest وactionWcpPaystackSupportedCurrencies وactionWcpPaystackCurrencyDecimals.

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

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

Paystack علامة تجارية مسجلة لمالكها. هذه الوحدة غير تابعة لـ Paystack ولا يعتمدها Paystack.