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

المتطلبات

OpenCart: 3.0.x (تم الاختبار على الإصدار 3.0.5.0) أو 4.0.2 والإصدارات الأحدث (تم الاختبار على الإصدار 4.1.0.3).

PHP: 8.0 أو أحدث.

العملة: يجب أن يكون الطلب بعملة يقبلها 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. يعمل المفتاح الواحد على نطاق واحد فقط.

التثبيت

التنزيل ملف zip واحد يحتوي على حزم الإصدارين من OpenCart. فكّه على جهاز الكمبيوتر الخاص بك. يحتوي على README.txt وحزمة OpenCart 3 wcp_paystack_payment-oc3-(version).ocmod.zip وحزمة OpenCart 4 wcp_paystack_payment.ocmod.zip. ثبّت الحزمة الخاصة بإصدار OpenCart لديك فقط. مفتاح الترخيص واحد للإصدارين.

OpenCart 3

1. في لوحة الإدارة، انتقل إلى Extensions > Installer، ثم انقر على Upload واختر الملف wcp_paystack_payment-oc3-(version).ocmod.zip. لا تحتوي الإضافة على تعديلات OCMOD، لذلك لا حاجة إلى تحديث Extensions > Modifications. وبدلًا من أداة التثبيت يمكنك أيضًا نسخ محتويات المجلد upload من هذه الحزمة إلى المجلد الجذر لمتجرك.

2. انتقل إلى Extensions > Extensions واختر النوع Payments. ابحث عن VibeFox Paystack Payment وانقر على Install (الزر الأخضر +). يحتاج مستخدم الإدارة لديك إلى صلاحية تعديل قائمة إضافات الدفع.

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

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

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

OpenCart 4

1. في لوحة الإدارة انتقل إلى Extensions > Installer، ثم انقر على Upload واختر الملف wcp_paystack_payment.ocmod.zip. لا تُغيّر اسم الملف: يستمد OpenCart 4 رمز الإضافة من اسم الملف، والحزمة التي يُعاد تسميتها لا تعمل.

2. تظهر الحزمة في قائمة الإضافات المثبتة في الصفحة نفسها. انقر على Install (الزر الأخضر +) بجوارها.

3. انتقل إلى Extensions > Extensions واختر النوع Payments. ابحث عن VibeFox Paystack Payment، وانقر على Install (الزر الأخضر +)، ثم على Edit (زر القلم الرصاص).

4. أدخل مفتاح الترخيص ومفاتيح Paystack والـ webhook كما في الخطوات 3 إلى 5 لـ OpenCart 3. صفحة الإعدادات وحقولها متطابقة في الإصدارين. العنوان الوحيد المختلف هو عنوان الـ webhook (راجع Webhook).

تبدأ عملية التثبيت الجديدة وطريقة الدفع معطّلة ووضع الاختبار مفعّلًا.

الإعدادات

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

عند الحفظ، لا يجوز أن يكون Title فارغًا أو أطول من 128 حرفًا، ويجب أن يكون Sort Order عددًا صحيحًا، ويجب أن يكون Total رقمًا أكبر من 0 أو يساويه، ويجب أن تكون المنطقة الجغرافية (geo zone) وحالات الطلبات موجودة؛ وإلا فلن يُحفظ شيء. ولا تمنع مشكلات المفاتيح الحفظ، إذ يذكرها مربع الحالة.

Paystack

يبدأ القسم بملاحظة قصيرة: البطاقات والتحويلات المصرفية وUSSD والنقود عبر الهاتف المحمول في صفحة الدفع التي تستضيفها Paystack، وكل دفعة تُؤكَّد على الخادم عبر واجهة Paystack البرمجية، والعملات المقبولة.

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

Title: اسم طريقة الدفع الذي يراه العميل في صفحة الدفع. وهو أيضًا الاسم المحفوظ لطريقة الدفع في الطلب. الافتراضي: Paystack. حقل إلزامي، بحد أقصى 128 حرفًا.

Description: النص الذي يظهر للعميل في خطوة Confirm Order، فوق زر التأكيد. الافتراضي: Pay securely using your debit card, credit card, or bank account via Paystack.

Sort Order: ترتيب Paystack بين طرق الدفع في صفحة الدفع. اتركه فارغًا أو أدخل عددًا صحيحًا.

Geo Zone: اعرض Paystack فقط لعناوين الدفع الواقعة في المنطقة الجغرافية المحددة. الافتراضي: All zones. تُضبط المناطق الجغرافية في System > Localisation > Geo Zones.

Total: إجمالي صفحة الدفع، بالعملة الافتراضية للمتجر، الذي يجب أن يبلغه الطلب قبل عرض Paystack. اتركه فارغًا لعرض Paystack مهما كان المبلغ.

مفاتيح API

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

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

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

Live Secret Key: مفتاحك السري للإنتاج في Paystack. يبدأ بـ sk_live_.

لا تُعرض المفاتيح المحفوظة مرة أخرى أبدًا. يبقى الحقل فارغًا ويعرض الرسالة محفوظ — اتركه فارغًا للإبقاء عليه. اكتب قيمة جديدة فقط إذا أردت تغييرها. ولحذف مفتاح محفوظ، ضع علامة على Clear the saved value أسفل الحقل ثم انقر على Save.

Webhook

يُخبر الـ webhook متجرك بأن الدفعة قد تمت، حتى لو لم يعد العميل إلى المتجر. في لوحة تحكم Paystack، على الصفحة Settings > API Keys & Webhooks، اضبط العنوان المعروض في Webhook URL في هذا القسم كقيمة لكل من Test Webhook URL وLive Webhook URL. في OpenCart 3 يبدو العنوان هكذا: https://your-store/index.php?route=extension/payment/wcp_paystack_payment/webhook، وفي OpenCart 4 هكذا: https://your-store/index.php?route=extension/wcp_paystack_payment/payment/wcp_paystack_payment.webhook. ويُبنى من عنوان الواجهة الأمامية لمتجر OpenCart الذي تملكه. انسخ العنوان تمامًا كما تعرضه الإعدادات.

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

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

الطلبات

ينشئ OpenCart الطلب في خطوة Confirm Order دون حالة (طلب مفقود، missing order). لا يحصل الطلب على حالة إلا بعد أن تؤكد Paystack الدفعة عبر واجهتها البرمجية. ويعرض كل حقل حالة أدناه حالات طلبات OpenCart لديك.

Autocomplete Order: عند التفعيل، تحصل الطلبات المدفوعة على Complete Order Status بدلًا من Paid Order Status. الافتراضي: موقوف.

Paid Order Status: الحالة التي تُضبط بعد دفعة مؤكَّدة. الافتراضي: Processing.

Complete Order Status: الحالة التي تُضبط بعد دفعة مؤكَّدة عندما يكون Autocomplete Order مفعّلًا. الافتراضي: Complete.

Awaiting Payment Status: عاد العميل بينما كانت Paystack ما زالت تعالج الدفعة (تحويل مصرفي أو USSD أو نقود عبر الهاتف المحمول). يحتفظ الطلب بهذه الحالة حتى يؤكد الـ webhook الدفعة. الافتراضي: Pending.

On Hold (Review) Status: تحتاج الدفعة إلى مراجعتك (راجع حالات الطلبات). الافتراضي: Pending، لأن OpenCart لا يملك حالة On hold. يمكنك إنشاء حالتك الخاصة في System > Localisation > Order Statuses واختيارها هنا.

Failed Status: فشلت دفعة كانت Paystack ما زالت تعالجها لطلب في حالة الانتظار. الافتراضي: Failed.

Refunded Status: استُرد المبلغ كاملًا من صفحة الطلب. الافتراضي: Refunded.

متقدم

Debug log: يكتب أحداث Paystack واستدعاءات الواجهة البرمجية في paystack_p_debug.log.php داخل مجلد سجلات OpenCart (storage/logs). لا يمكن فتح الملف من الويب، وعند بلوغه 5 MB يُنقل إلى paystack_p_debug.old.log.php. تُسجَّل الأخطاء والتحذيرات دائمًا. لا تُسجَّل المفاتيح وبيانات العملاء أبدًا. الافتراضي: موقوف.

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

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

الاستيراد / التصدير

Export: Download JSON يحفظ الإعدادات في ملف JSON. لا تُصدَّر المفاتيح السرية.

Import: الصق ملف JSON صُدِّر سابقًا وانقر على Import لاستعادة الإعدادات. تبقى المفاتيح السرية المحفوظة كما هي.

الدفع

في خطوة Payment Method يختار العميل طريقة الدفع (افتراضيًا Paystack). وفي خطوة Confirm Order يرى العميل وصفك والملاحظة سيتم تحويلك إلى صفحة Paystack الآمنة لإكمال الدفع. ينشئ OpenCart الطلب في هذه الخطوة، ولا يزال بلا حالة. وفي OpenCart 4 يختار العميل طريقة الدفع بزر Choose في كتلة طريقة الدفع، ضمن النافذة Payment method options، وينقر على Confirm Order في أسفل صفحة الدفع. عندما ينقر العميل على Confirm Order، تبدأ الإضافة معاملة Paystack بمبلغ الطلب الإجمالي بعملة الطلب، مع البريد الإلكتروني للعميل، وترسل العميل إلى صفحة الدفع التي تستضيفها Paystack. هناك يدفع العميل بإحدى القنوات المفعّلة في حسابك لدى Paystack. تتضمن الدفعة رقم الطلب واسم العميل.

بعد الدفع يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكده Paystack: عندما يعود العميل وعندما يصل الـ webhook، تقرأ الإضافة المعاملة من واجهة Paystack البرمجية وتتحقق من المرجع والحالة والمبلغ والعملة. ثم يحصل الطلب على حالته بالطريقة القياسية في OpenCart، مع رسائل البريد المعتادة للطلب وتحديث المخزون، ويرى العميل صفحة نجاح الطلب في OpenCart.

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

إذا نقر العميل على Cancel payment في صفحة Paystack، أو غادرها دون الدفع، أو رُفضت الدفعة، يبقى الطلب بلا حالة ويُحفظ السلة. يعود العميل إلى صفحة الدفع مع رسالة: تم إلغاء الدفعة. يمكنك المحاولة مرة أخرى أو اختيار طريقة دفع أخرى. أو لم تكتمل الدفعة. يمكنك المحاولة مرة أخرى أو اختيار طريقة دفع أخرى. أو تم رفض دفعتك. يمكنك المحاولة مرة أخرى أو اختيار طريقة دفع أخرى. في OpenCart 4 تُعرض هذه الرسائل أعلى صفحة الدفع.

كل محاولة جديدة (في OpenCart 3 ينشئ OpenCart طلبًا جديدًا في كل مرة تُعرض فيها خطوة Confirm Order، وفي OpenCart 4 يُحدَّث طلب الدفع) تبدأ معاملة Paystack جديدة. وتظل صفحة الدفع القديمة صالحة: إذا دُفعت لاحقًا قُبلت الدفعة. وقبل بدء دفعة جديدة، تُراجَع المحاولات المفتوحة لنفس السلة خلال آخر 24 ساعة مع Paystack. إذا كانت السلة مدفوعة بالفعل، أو قيد المراجعة، أو في انتظار تحويل مصرفي، ينتقل العميل مباشرة إلى صفحة النجاح ولا تُبدأ دفعة ثانية. وإذا دُفع طلب آخر من السلة نفسها على أي حال، يبقى ذلك الطلب بلا حالة، ويتلقى الطلب المدفوع ملاحظة بضرورة استرداد الدفعة المكررة. ويُعدّ أي تغيير في السلة، بما في ذلك الكمية الجديدة، سلةً جديدة تحتاج إلى دفعة خاصة بها.

في OpenCart 4 يبقى الطلب في صفحة الدفع إلى أن تُعرض صفحة النجاح. وإذا أُغلق هذا الطلب دون دفع في الأثناء (مثلًا عند إلغائه)، يُعاد العميل إلى صفحة الدفع مع الرسالة Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order. وتدفع خطوة Confirm Order التالية طلبًا جديدًا. وإذا كان هذا الطلب قد دُفع لسلة سابقة وتغيّرت السلة منذ ذلك الحين، يُعاد العميل إلى صفحة الدفع، وتدفع خطوة Confirm Order التالية طلبًا جديدًا للسلة الحالية. ولا يُعرض طلب مغلق أبدًا على أنه مدفوع.

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

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

يعمل الـ webhook أيضًا والمتجر في وضع الصيانة، لأن OpenCart يسمح بمرور طلبات إضافات الدفع (في OpenCart 4 تضيف الإضافة إجراء بدء التشغيل الخاص بها لهذا الغرض، وهو يسمح أيضًا بعودة العميل من Paystack).

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

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

حالات الطلبات

بلا حالة (طلب مفقود): أُرسل العميل إلى Paystack ولم يدفع، أو غادر صفحة Paystack، أو لم تؤكد Paystack الدفعة بعد. وفي Sales > Orders لا تظهر هذه الطلبات إلا عند ضبط عامل التصفية Order Status على Missing Orders.

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

Paid Order Status (الافتراضي Processing) أو Complete Order Status: تم تأكيد الدفعة. تُستخدم حالة الاكتمال عندما يكون Autocomplete Order مفعّلًا. يعرض ملاحظة تُظهر المبلغ، ومرجع Paystack، ورقم المعاملة، والوضع (اختبار أو حقيقي)، وقناة الدفع، ونوع البطاقة وآخر أرقامها في مدفوعات البطاقات، وأي رسوم لـ Paystack دفعها العميل.

On Hold (Review) Status (الافتراضي Pending): المبلغ المدفوع أو العملة يختلفان عن الطلب (الملاحظة Paystack amount or currency mismatch)، أو وصلت الدفعة بعد إلغاء الطلب أو نقله إلى حالة أخرى دون دفع. وتشرح الملاحظة ما يجب التحقق منه. أكمل الطلب أو استرد الدفعة.

Failed Status (الافتراضي Failed): تُبلغ Paystack بأن آخر محاولة دفع لطلب في حالة الانتظار قد فشلت أو عُكست. فشل محاولة أقدم لا يغيّر الطلب.

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

الملاحظات هي مدخلات في History الخاص بالطلب، ولا يراها العميل.

تبويب VibeFox Paystack Payment

في Sales > Orders افتح طلبًا دُفع عبر Paystack. في أسفل صفحة الطلب، بجوار History وAdditional، يعرض تبويب VibeFox Paystack Payment الرقم المرجعي للمعاملة Transaction reference، والوضع Mode مع التسمية Test للمدفوعات التجريبية، وحالة الدفع Status، ورقم المعاملة Transaction ID، والقناة Channel والبطاقة Card، وتاريخ الدفع، والمبالغ Paid / refunded، ونموذج الاسترداد، وسجل الاستردادات، والملاحظات Paystack notes الخاصة بالطلب. يُعرض التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة.

الاستردادات

في تبويب VibeFox Paystack Payment أدخل Amount (يُملأ المبلغ الذي لم يُسترد بعد)، واختياريًا Reason (optional)، ثم انقر على Refund via Paystack. أكّد السؤال هل تريد استرداد هذا المبلغ عبر Paystack؟ لا يمكن التراجع عن هذا الإجراء. الاستردادات الكاملة والجزئية مدعومة. تحتاج إلى صلاحية تعديل الإضافة (تُضبط في System > Users > User Groups). يُرسل الاسترداد إلى المعاملة التي دفعت الطلب، باستخدام المفتاح السري للوضع (اختبار أو حقيقي) الذي تمت فيه الدفعة، لذلك يجب ضبط ذلك المفتاح. تُنفَّذ الاستردادات بالمبلغ والعملة اللذين خصمتهما Paystack؛ لذلك في حالة طلب قيد المراجعة بعد اختلاف في المبلغ أو العملة، يمكنك الاسترداد حتى المبلغ الذي دفعه العميل فعلًا، لا إجمالي الطلب. وفي XOF وRWF يجب أن تكون الاستردادات مبالغ صحيحة.

تضع Paystack الاستردادات في قائمة انتظار: تُظهر الملاحظة وسجل الاستردادات الحالة التي أعادتها Paystack، مثل pending، ومعرّف الاسترداد. إذا لم تقبل Paystack الاسترداد، يعرض التبويب Paystack refund failed: مع السبب، ولا يُسجَّل أي استرداد. ويضبط الاسترداد الكامل الطلب على Refunded Status دون إشعار العميل ودون إعادة المنتجات إلى المخزون، تمامًا مثل تغيير الحالة يدويًا. ولا يغيّر الاسترداد الجزئي الحالة. وتصبح الاستردادات متاحة بعد أن تؤكد Paystack الدفعة.

لا تعيد مرتجعات المنتجات في Sales > Returns أي أموال عبر Paystack. ولا تُزامَن مع OpenCart الاستردادات التي تُجرى في لوحة تحكم Paystack، ولا الحالة النهائية للاستردادات التي تضعها Paystack في قائمة الانتظار. وإذا لزم الأمر، سجّلها يدويًا.

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

تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox Paystack Payment هي أول كتلة في Extensions > Extensions > Payments > VibeFox Paystack Payment > Edit، فوق الإعدادات. الصق المفتاح في License key وانقر على Activate. بعد ذلك تعرض الكتلة المفتاح مُخفى الأجزاء، والحالة (مثل تاريخ انتهاء الترخيص ونطاقك)، والأزرار Check now لإعادة فحص الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وتحتها السطر Product: opencart-payment-paystack والرابط Manage licenses and domains in your account الذي يفتح حسابك على vibefox.net. لا يستطيع تغيير المفتاح إلا مستخدمو الإدارة الذين لديهم صلاحية Modify للإضافة. تتبع نصوص الكتلة لغة لوحة الإدارة (وتشمل الإنجليزية والروسية).

إذا لم يُقبل المفتاح، تذكر الكتلة السبب، مثل Key not found أو This key belongs to another product أو Domain limit reached أو License expired on مع تاريخ. بعد تغيير عنوان المتجر، أو بعد تحرير خانة نطاق في حسابك، انقر على Check now. وإذا تعذر الوصول إلى خادم التراخيص، تواصل الإضافة العمل بآخر حالة معروفة.

يعمل المفتاح الواحد على نطاق واحد: عنوان المتجر من إعدادات OpenCart. ولا يؤدي حذف المفتاح من المتجر إلى تحرير خانة النطاق. حرّر الخانة من حسابك على vibefox.net.

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

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

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

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

تمت الدفعة، لكن الطلب يبقى بلا حالة: لم يصل الـ 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 updated, retry later: تعذّرت قراءة المعاملة من واجهة Paystack البرمجية في تلك اللحظة، أو كانت السلة تُعالَج بعودة العميل في الوقت نفسه، أو تعذّر ضبط حالة الطلب. ستعيد Paystack إرسال الـ webhook. ويُظهر السجل السبب.

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

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

يرى العميل الرسالة Payment gateway is not properly configured: المفتاح السري للوضع الحالي مفقود أو غير صحيح. صححه كما يوضح مربع الحالة أعلى الإعدادات. أما الرسالة This payment method is not available. بعد Confirm Order فتعني أن طريقة الدفع أُوقفت في الأثناء، أو أن صفحة الدفع لم تعد تطابق الطلب: على العميل إعادة تحميل صفحة الدفع.

الطلب في حالة المراجعة بعد الدفع: اقرأ الملاحظات في تبويب VibeFox Paystack Payment (راجع حالات الطلبات)، ثم أكمل الطلب أو استرد الدفعة.

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

لا يظهر نموذج الاسترداد في التبويب: يذكر التبويب السبب: الدفعة غير مؤكدة بعد، أو مستردة بالكامل، أو مجموعة المستخدمين لديك لا تملك صلاحية تعديل الإضافة، أو المفتاح السري لوضع الدفعة مفقود.

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

للمطورين: تُطلق الإضافة أحداث OpenCart paystack_p_payment_request (طلب المعاملة)، وpaystack_p_supported_currencies، وpaystack_p_currency_decimals.

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

انتقل إلى Extensions > Extensions، واختر النوع Payments، ثم انقر على Uninstall (الزر الأحمر −) بجوار VibeFox Paystack Payment. يُحذف مفتاح ترخيص هذه الإضافة وحالة الترخيص دائمًا. ويحذف OpenCart دائمًا إعدادات الإضافة الخاصة به: Enable/Disable وSort Order وGeo Zone وTotal وحالات الطلبات في قسم Orders، وتعود هذه إلى قيمها الافتراضية عند إعادة التثبيت. كما يُحذف حدث OpenCart الخاص بالإضافة (وفي OpenCart 4 تُحذف أيضًا أحداثها وإجراء بدء التشغيل الخاص بها، الذي يسمح بمرور الـ webhook وعودة العميل في وضع الصيانة). وإذا كان Delete data on uninstall مفعّلًا، تُحذف بقية إعدادات البوابة (العنوان والوصف ووضع الاختبار والمفاتيح والإكمال التلقائي وتسجيل الأحداث) والسجل. وإذا كان موقوفًا، تُحفظ لإعادة التثبيت لاحقًا. تُحفظ بيانات دفع Paystack للطلبات والاستردادات دائمًا، لذلك يمكن استرداد الطلبات المدفوعة سابقًا بعد إعادة التثبيت. وتحتفظ الطلبات الموجودة بملاحظات الدفع الخاصة بها.

في OpenCart 4، لحذف ملفات الإضافة أيضًا، انتقل إلى Extensions > Installer بعد إلغاء التثبيت، وانقر على Uninstall (الزر البرتقالي −) بجوار VibeFox Paystack Payment في قائمة الإضافات المثبتة، ثم على Delete (زر سلة المهملات الأحمر) لحذف الحزمة المرفوعة.

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