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

المتطلبات

WordPress: 6.0 أو أحدث.

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

PHP: 8.0 أو أحدث.

HTTPS: ينبغي أن يستخدم موقعك HTTPS للمدفوعات الفعلية.

حساب Stripe: تحتاج إلى مفاتيح API السرية لحساب Stripe ونقطة نهاية webhook في Stripe Dashboard (راجع الإعدادات). يُستخدم فقط المفاتيح السرية وأسرار توقيع webhook. المفاتيح القابلة للنشر (pk_...) غير مطلوبة، لأن Stripe Checkout صفحة تستضيفها Stripe.

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

التثبيت

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

2. انقر Activate.

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

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

5. الصق مفاتيح Stripe السرية، واضبط webhook في Stripe Dashboard، والصق أسرار التوقيع الخاصة به (راجع الإعدادات).

6. فعّل Enable/Disable. جرّب دفعة في وضع الاختبار باستخدام البطاقة 4242 4242 4242 4242، ثم ألغِ تحديد Test Mode.

الإعدادات

جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > Stripe. فوق الحقول تحذرك الصفحة عندما لا يكون للوضع الحالي مفتاح سري (فتُخفى طريقة الدفع عندئذٍ في صفحة الدفع) أو سر توقيع webhook، وتعرض Test mode is on: no real payments are taken. عندما يكون وضع الاختبار مفعّلًا. وفي قائمة طرق الدفع يُعلَّم Stripe بأنه يحتاج إلى إعداد حتى يكون للوضع الحالي مفتاح سري.

عام

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

Title: اسم طريقة الدفع الذي يراه العملاء في صفحة الدفع. الافتراضي: Stripe.

Description: النص الذي يظهر أسفل طريقة الدفع في صفحة الدفع. الافتراضي: Pay securely with your credit or debit card via Stripe.

مفاتيح API

انسخ المفاتيح السرية من Stripe Dashboard > Developers > API keys. مفاتيح الاختبار والمفاتيح الحية منفصلة. يستخدم وضع الاختبار مفاتيح الاختبار فقط، ويستخدم الوضع الحي المفاتيح الحية فقط. عند الحفظ تحذرك الإضافة إذا كانت القيمة لا تبدأ بالبادئة المتوقعة، كأن يُلصق مفتاح قابل للنشر بدلًا من مفتاح سري.

Test Mode: Enable test mode يستخدم مفاتيح الاختبار الخاصة بـ Stripe. لا يُخصم أي مال حقيقي؛ ادفع ببطاقات الاختبار الخاصة بـ Stripe مثل 4242 4242 4242 4242. الافتراضي: مفعّل. ألغِ التحديد لقبول المدفوعات الحقيقية.

Test Secret Key: المفتاح السري لوضع الاختبار. يبدأ بـ sk_test_ (أو rk_test_ للمفتاح المقيَّد).

Test Webhook Secret: سر توقيع (whsec_...) لنقطة نهاية webhook التي أُنشئت في وضع الاختبار.

Live Secret Key: المفتاح السري للوضع الحي. يبدأ بـ sk_live_ (أو rk_live_ للمفتاح المقيَّد).

Live Webhook Secret: سر توقيع (whsec_...) لنقطة نهاية webhook التي أُنشئت في الوضع الحي.

Webhook

يُخبر webhook متجرك بأن دفعة قد تمت. في Stripe Dashboard > Developers > Webhooks أضف نقطة نهاية في وضع الاختبار وأخرى في الوضع الحي. استخدم الرابط المعروض في هذا القسم من الإعدادات. يبدو على هذا النحو: https://your-site/wc-api/strg_stripe_webhook/. إذا كان موقعك يستخدم بادئة لغة في الروابط، فانسخ الرابط تمامًا كما تعرضه الإعدادات، لأن Stripe لا يتبع عمليات إعادة التوجيه.

اختر هذه الأحداث لكل نقطة نهاية:

بعد إنشاء كل نقطة نهاية، انسخ سر توقيعها (whsec_...) من Stripe والصقه في Test Webhook Secret أو Live Webhook Secret. تُرفض الـ webhooks التي لا تحمل توقيعًا صالحًا. وبدون webhook لا يُؤكَّد الطلب إلا عندما يعود العميل إلى المتجر بعد الدفع.

الطلبات

Order Status After Payment: حالة الطلب التي تُعيَّن بعد الدفع الناجح. تُعيَّن الحالة مرة واحدة، دون تغيير ثانٍ للحالة.

متقدم

Logging: Enable logging يكتب طلبات Stripe وwebhooks في WooCommerce > Status > Logs، بالمصدر wcp_stripe_gateway. لا تُسجَّل المفاتيح وبيانات العملاء. الافتراضي: معطّل.

Delete Data on Uninstall: عند التفعيل، يؤدي حذف الإضافة إلى إزالة إعدادات البوابة وبيانات Stripe المحفوظة في الطلبات والسجلات. الافتراضي: معطّل.

صفحة الدفع

يختار العميل طريقة الدفع (افتراضيًا Stripe) ويُتمّ الطلب. تُنشئ الإضافة جلسة Stripe Checkout بإجمالي الطلب وبعملة الطلب، وتُرسل العميل إلى صفحة الدفع الخاصة بـ Stripe. هناك يدفع العميل ببطاقة ائتمان أو بطاقة خصم. يُمرَّر بريد الفوترة الإلكتروني للعميل إلى Stripe، ويظهر الدفع في صفحة Stripe بعبارة Order # مع رقم الطلب.

بعد الدفع يعود العميل إلى صفحة استلام الطلب في متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد تأكيد Stripe: إما عبر webhook موقَّع أو عبر طلب من جهة الخادم إلى Stripe عندما يصل العميل إلى تلك الصفحة. إذا لم يُؤكَّد الدفع بعد، تعرض الصفحة Your payment is being confirmed by Stripe. You will receive an e-mail as soon as it is confirmed.

إذا ألغى العميل في صفحة Stripe، يُلغى الطلب بالطريقة القياسية في WooCommerce. ويمكن للعميل إعادة دفع طلب غير مدفوع، مثلًا من صفحة Pay for order. تُغلق كل محاولة جديدة جلسة Stripe السابقة، فلا يمكن دفع الطلب مرتين.

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

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

لا تقبل الإضافة إلا مدفوعات البطاقات، وتُحصَّل فورًا في صفحة Stripe. ولا تتضمن بطاقات محفوظة، ولا اشتراكات أو مدفوعات متكررة، ولا نموذج بطاقة على موقعك، ولا أزرار Apple Pay أو Google Pay على موقعك، ولا تفويض وتحصيل منفصلين.

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

حالات الطلب

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

Processing, Completed or On Hold: تم تأكيد الدفع. تتبع الحالة Order Status After Payment. تُظهر ملاحظة الطلب دفعة Stripe وكيف تم تأكيدها (webhook أو عودة). معرّف المعاملة هو معرّف دفعة Stripe (pi_...)، وفي شاشة الطلب يرتبط بالدفعة في Stripe Dashboard.

On hold after payment: أبلغت Stripe عن مبلغ أو عملة مختلفين عن إجمالي الطلب (مثلًا عُدّل الطلب بعد بدء الدفع)، أو وصلت الدفعة بعد إلغاء الطلب. تشرح ملاحظة الطلب ذلك. راجع الطلب وأنجزه أو استرد الدفعة.

Failed: فشلت دفعة مؤجلة.

Cancelled: ألغى العميل في صفحة Stripe، أو أُلغي الطلب من قبلك أو بسبب انتهاء مهلة حجز المخزون في WooCommerce. تُغلق جلسة Stripe المفتوحة للطلب، فلم يعد بالإمكان دفعه.

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

الاستردادات

افتح الطلب، وانقر Refund، وأدخل المبلغ، ثم انقر Refund via Stripe. يُدعم الاسترداد الكامل والجزئي. يُرسل الاسترداد في الوضع الذي تمت فيه عملية الدفع (اختبار أو حي)، لذلك يجب ضبط المفتاح السري لذلك الوضع. إذا لم تقبل Stripe الاسترداد، يعرض WooCommerce الخطأ ولا يُسجَّل أي استرداد. ويُضاف الاسترداد الناجح إلى ملاحظات الطلب مع معرّف الاسترداد في Stripe.

تصل الاستردادات التي تتم في Stripe Dashboard عبر webhook من نوع charge.refunded، وتُضاف إلى ملاحظات الطلب. ولا تُسجَّل تلقائيًا كاستردادات في WooCommerce. وإذا لزم الأمر، فأنشئ استردادًا يدويًا في WooCommerce دون استخدام Refund via Stripe.

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

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

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

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

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

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

لا يظهر Stripe في صفحة الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن الوضع الحالي يحتوي على مفتاح سري: Test Secret Key في وضع الاختبار، وLive Secret Key في الوضع الحي. تعرض صفحة الإعدادات تحذيرًا عند غياب المفتاح.

تمت عملية الدفع لكن الطلب ما زال Pending payment: الـ webhook لا يعمل. في Stripe Dashboard تحقق من وجود نقطة النهاية في الوضع الذي تستخدمه (اختبار أو حي)، ومن أن رابطها مطابق تمامًا للرابط المعروض في الإعدادات، ومن اختيار الأحداث الأربعة. تحقق من أن سر توقيع نقطة النهاية موجود في الحقل المناسب (Test Webhook Secret أو Live Webhook Secret). يعرض Stripe Dashboard رد متجرك على كل webhook. ويُؤكَّد الطلب أيضًا عندما يعود العميل إلى المتجر بعد الدفع.

يرد webhook بالرسالة Webhook secret not configured: لم يُضبط أي من سرّي webhook. الصق سر التوقيع في الإعدادات.

يرد webhook بالرسالة Invalid signature: سر التوقيع يخص نقطة نهاية أخرى أو وضعًا آخر، أو أن ساعة الخادم غير صحيحة. تُقبل توقيعات Stripe في غضون 5 دقائق من وقت الخادم فقط.

يرد webhook بالرسالة Busy, retry: كان الطلب يُؤكَّد في الوقت نفسه بطلب آخر. يعيد Stripe إرسال الـ webhook تلقائيًا.

تحذير عند الحفظ: القيمة لا تبدو صحيحة: لُصق مفتاح في الحقل الخطأ. تبدأ المفاتيح السرية بـ sk_test_ / rk_test_ أو sk_live_ / rk_live_، وأسرار webhook بـ whsec_.

يرى العميل خطأ عند إتمام الطلب: افتح ملاحظات الطلب أو فعّل Logging وراجع WooCommerce > Status > Logs بالمصدر wcp_stripe_gateway. يُظهر المفتاح الخاطئ أو المفقود رسالة بأن طريقة الدفع غير مضبوطة بشكل صحيح. ولا يمكن دفع طلب بإجمالي أقل من الحد الأدنى لـ Stripe في العملة (مثل 0.50 EUR) عبر Stripe.

لا تؤكد دفعات الاختبار طلبًا حيًا: تُفصل دفعات الاختبار عن الدفعات الحية. لا تؤكد دفعة اختبار طلبًا حيًا أبدًا، والعكس صحيح. بدّل Test Mode إلى الوضع الذي تريده، واستخدم مفاتيح ذلك الوضع وwebhook الخاص به.

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

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

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

إزالة التثبيت

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

Stripe علامة تجارية مسجلة لمالكها. هذه الإضافة غير مرتبطة بـ Stripe ولا مُعتمدة من قبلها.