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

المتطلبات

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

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

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

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

التثبيت

1. في الواجهة الخلفية (back office) انتقل إلى Modules > Module Manager واضغط Upload a module. اختر ملف ZIP الخاص بالوحدة.

2. عند انتهاء الرفع اضغط Configure، أو ابحث لاحقًا عن VibeFox Stripe Gateway في قائمة الوحدات واضغط Configure.

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

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

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

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

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Stripe Gateway > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كاملة. فوق الحقول تحذرك الصفحة عندما لا يحتوي الوضع الحالي على مفتاح سري (فتُخفى طريقة الدفع عندئذٍ في الدفع) أو على سر توقيع الـ webhook (فلا تُؤكَّد الطلبات إلا عند عودة العميل إلى المتجر)، وتعرض وضع الاختبار مفعّل: لا يتم تحصيل أي مدفوعات حقيقية. ما دام وضع الاختبار مفعّلًا.

Stripe Checkout

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

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

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

مفاتيح API

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

Test Mode: يستخدم مفاتيح الاختبار الخاصة بـ Stripe. لا يُخصم أي مبلغ حقيقي؛ ادفع ببطاقات الاختبار الخاصة بـ Stripe مثل 4242 4242 4242 4242. Default: on. أوقفه لقبول مدفوعات حقيقية. وما دام مفعّلًا يرى العملاء أسفل طريقة الدفع العبارة وضع الاختبار: لا يتم تحصيل أي دفعة حقيقية.

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

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

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

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

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

Clear saved secrets: حدّد مفتاحًا أو سرًا واضغط Save لإزالته. الحقل الفارغ يُبقي القيمة المحفوظة.

Webhook

يُبلغ الـ webhook متجرك بأن دفعة قد تمت. في Stripe Dashboard > Developers > Webhooks أضف نقطة نهاية في وضع الاختبار وأخرى في الوضع الحي. استخدم الرابط الظاهر في Endpoint URL في هذا القسم. مع الروابط الودية يكون بالشكل https://your-shop/module/wcp_stripe_gateway/webhook، وقد يحتوي على رمز لغة مثل /en/. انسخ الرابط تمامًا كما تعرضه الإعدادات، لأن Stripe لا يتبع عمليات إعادة التوجيه.

حدّد هذه الأحداث لكل نقطة نهاية (وهي مدرجة أيضًا في هذا القسم):

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

الطلبات

Order Status After Payment: حالة الطلب التي تُضبط بعد الدفع الناجح.

تنتظر الدفعات المؤجلة في Awaiting Stripe payment. وتذهب حالات عدم تطابق المبلغ أو العملة دائمًا إلى Stripe payment on hold.

متقدم

Logging: يكتب طلبات Stripe والـ webhooks في logs/strg_debug.log.php داخل مجلد الوحدة. لا يمكن فتح الملف من الويب. لا تُسجَّل المفاتيح ولا بيانات العملاء. Default: off. عند إيقافه لا يُكتب أي شيء.

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

Delete Data on Uninstall: عند التفعيل يؤدي إلغاء تثبيت الوحدة إلى حذف إعدادات البوابة والسجل. تبقى معاملات Stripe والاستردادات وحالات الطلبات الخاصة بالوحدة دائمًا، فتستمر الطلبات الحالية في العمل. Default: off.

الدفع

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

بعد الدفع يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكد Stripe الدفع: عبر الـ webhook الموقَّع، أو عبر طلب من الخادم إلى Stripe عندما يعود العميل. عندئذٍ يُنشأ الطلب ويرى العميل صفحة تأكيد الطلب القياسية مع الرسالة تم استلام دفعتك عبر Stripe. وبالنسبة إلى دفعة مؤجلة تعرض الصفحة يجري تأكيد دفعتك من Stripe. ستتلقى رسالة بريد إلكتروني فور تأكيدها. وإذا فشلت الدفعة المؤجلة لاحقًا تعرض الصفحة لم تكتمل دفعتك عبر Stripe. يُرجى التواصل معنا بخصوص هذا الطلب. وإذا لم تؤكد Stripe الدفع عند عودة العميل، تعرض صفحة Payment confirmation النص نفسه وزر Check again، ويُنشئ الـ webhook الطلب فور وصوله.

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

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

إذا توقف كوبون في السلة عن أن يكون صالحًا بين الدفع وتأكيده، يزيله PrestaShop من الطلب. وينتقل الطلب عندئذٍ إلى Stripe payment on hold مع ملاحظة، لأن العميل دفع السعر بالخصم.

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

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

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

حالات الطلب

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

Payment accepted, Delivered or Stripe payment on hold: تم تأكيد الدفع. تتبع الحالة Order Status After Payment. تُسجَّل الدفعة بمعرّف دفعة Stripe (pi_...) كمعرّف للمعاملة، ويعرض الملاحظة دفعة Stripe والجلسة وطريقة التأكيد (الـ webhook أو العودة).

Awaiting Stripe payment: أنهى العميل الدفع بطريقة دفع مؤجلة. ينتقل الطلب إلى حالة مدفوع عندما تؤكد Stripe الدفعة.

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

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

Refunded: استُردّت الدفعة بالكامل عبر الوحدة.

إذا وصلت دفعة ثانية لطلب مدفوع بالفعل، لا يتغير الطلب. تطلب منك ملاحظة مراجعتها واسترداد المكرر في Stripe Dashboard.

كتلة Stripe payment

تعرض صفحة الطلب كتلة Stripe payment تتضمن معرّف دفعة Stripe (مرتبطًا بالدفعة في Stripe Dashboard)، وCheckout Session، وحالة الدفع، والمبلغ الذي حصّلته Stripe والمبلغ المسترد، وشارة Test mode لدفعات الاختبار، وسجل الاستردادات، وStripe notes الخاصة بالطلب.

الاستردادات

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

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

تصل الاستردادات التي تتم في Stripe Dashboard عبر الـ webhook من نوع charge.refunded، وتُضاف إلى الملاحظات مع إجمالي المبلغ المسترد في Stripe. لا تتغير حالة الطلب ولا الإشعارات الدائنة تلقائيًا. حدّثها يدويًا عند الحاجة.

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

تعمل الوحدة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox Stripe Gateway هي الكتلة الأولى في Modules > Module Manager > VibeFox Stripe Gateway > Configure، فوق الإعدادات. الصق المفتاح في License key وانقر على Activate. بعد ذلك تعرض الكتلة المفتاح مخفيًا جزئيًا، والحالة (مثل تاريخ انتهاء الترخيص ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وتحتها السطر Product: presta-payment-stripe والرابط Manage licenses and domains in your account الذي يفتح حسابك في vibefox.net. لا يستطيع تغيير المفتاح إلا الموظفون الذين لديهم صلاحية Configure للوحدة. تتبع نصوص الكتلة لغة back office (وتشمل الإنجليزية والروسية).

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

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

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

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

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

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

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

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

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

يرد الـ webhook بالنص Busy, retry: كان طلب آخر يؤكد الطلب في الوقت نفسه، أو تعذّر إنشاء الطلب (مثلًا لأن الوحدة معطّلة). تعيد Stripe إرسال الـ webhook تلقائيًا. فعّل Logging لمعرفة السبب.

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

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

يرى العميل خطأ عند اختيار Stripe: فعّل Logging وراجع حقل Log في صفحة الوحدة. يعطي المفتاح الخاطئ رسالة بأن طريقة الدفع غير مُعدّة بشكل صحيح. ولا يمكن دفع طلب بإجمالي أقل من الحد الأدنى لـ Stripe في العملة (مثلًا 0.50 EUR) عبر Stripe.

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

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

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

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

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

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