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

المتطلبات

WordPress: 5.8 أو أحدث.

WooCommerce: 7.0 أو أحدث، مثبّت ومفعّل. لا يُفعَّل الملحق بدونه.

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 تضبط أيضاً عنوان URL الخاص بالـ webhook لمتجرك (راجع الإعدادات). ويجب أن يكون موقعك متاحاً من الإنترنت لاستلام الـ webhooks.

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

التثبيت

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

2. انقر على Activate.

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

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

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

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

الإعدادات

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

الدفع

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: Enable Test Mode يستخدم المفتاح السري للاختبار للدفعات الجديدة، ولا يتم خصم أي مبلغ حقيقي. ألغِ التحديد لقبول الدفعات الحقيقية بالمفتاح السري للوضع المباشر. تواصل الدفعات التي تمّت في الوضع الآخر استخدام مفتاح وضعها للتحقق والاسترداد. الافتراضي: مفعّل.

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

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

الـ Webhook

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

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

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

الطلبات

Autocomplete Order: Automatically mark orders as completed after successful payment. عند تحديده تنتقل الطلبات المدفوعة إلى مكتمل بدلاً من Processing، بتغيير حالة واحد وبريد إلكتروني واحد للعميل. الافتراضي: إيقاف.

متقدم

Debug log: Log Paystack events and API calls for debugging يكتب التفاصيل في WooCommerce > Status > Logs، المصدر wcp_paystack_payment. تُسجَّل الأخطاء دائماً. لا تُسجَّل المفاتيح وبيانات العملاء أبداً. الافتراضي: إيقاف.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. إلغاء تفعيل الملحق لا يحذف أي شيء. بيانات الدفع المحفوظة في الطلبات تبقى دائماً. الافتراضي: إيقاف.

الدفع

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

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

إذا ألغى العميل في صفحة Paystack أو غادرها دون أن يدفع، يبقى الطلب في انتظار الدفع. يعود العميل إلى صفحة الدفع أو صفحة Pay for order مع رسالة، مثل Payment was cancelled. You can try again or choose another payment method. أو The payment was not completed. You can try again or choose another payment method. أو Your payment was declined. You can try again or choose another payment method. يمكن للعميل أن يدفع الطلب نفسه مرة أخرى. تبقى صفحة الدفع السابقة للطلب صالحة: إذا دُفع عبرها لاحقاً، يُقبل الدفع أيضاً.

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

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

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

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

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

حالات الطلب

Pending payment: نُقل العميل إلى Paystack ولم يدفع بعد، أو غادر صفحة Paystack دون أن يدفع، أو أن الدفعة ما زالت قيد المعالجة لدى Paystack. عندما يعود العميل دون أن يدفع، تُبيّن ملاحظة أن الطلب ما زال في انتظار الدفع.

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

On hold: المبلغ أو العملة المدفوعة يختلفان عن الطلب (ملاحظة Paystack amount or currency mismatch)، أو وصلت الدفعة بعد إلغاء الطلب. تشرح ملاحظة الطلب ما يجب فحصه. جهّز الطلب أو استرد الدفعة.

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

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

المبالغ المستردة

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

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

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

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

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

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

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

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

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

تمت عملية الدفع لكن الطلب ما زال في Pending payment: لم يصل الـ webhook إلى متجرك، ولم يعد العميل. في لوحة تحكم Paystack تحقق من أن Test Webhook URL وLive Webhook URL يطابقان تماماً عنوان URL المعروض في الإعدادات، ومن أن وضع الصيانة أو جدار الحماية أو الحماية بكلمة مرور لا يمنعه. راجع WooCommerce > Status > Logs، المصدر wcp_paystack_payment، لمعرفة الـ webhooks المرفوضة.

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

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

يرد الـ webhook بـ Verification failed أو Busy, retry later: تعذّرت قراءة المعاملة من واجهة Paystack البرمجية في تلك اللحظة، أو كان الطلب يُحدَّث بعودة العميل في الوقت نفسه. لا يتغير الطلب، ويعيد Paystack إرسال الـ webhook.

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

يرى العميل Payment gateway is not properly configured: المفتاح السري للوضع الحالي مفقود أو غير صحيح. صحّحه بالاستعانة بمربع الحالة أعلى الإعدادات.

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

يفشل الاسترداد برسالة متعلقة بالوضع: تمّت الدفعة في وضع الاختبار أو الوضع المباشر، والمفتاح السري لذلك الوضع غير مُعدّ. أدخله وأعد المحاولة. تعني الرسالة No verified Paystack payment was found for this order أن الطلب لم يُدفع عبر معاملة Paystack موثّقة. استرده من لوحة تحكم Paystack.

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

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

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

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