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

المتطلبات

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

PHP: الإصدار 8.0 أو أحدث.

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

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

التثبيت

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

OpenCart 3

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

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

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

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

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

OpenCart 4

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

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

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

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

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

الإعداد

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

عند الحفظ، يجب أن يتكون Title من 1 إلى 128 حرفًا، ويجب أن يكون Sort Order عددًا صحيحًا، ويجب أن يكون Total رقمًا يساوي 0 أو أكبر. وإذا لم تبدأ مفتاح أو سرّ بالبادئة المتوقعة، تُحفظ الإعدادات ويظهر فوقها تحذير يذكر الحقل المعني.

Stripe Checkout

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

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

Description: النص الذي يراه العميل في خطوة Confirm Order فوق زر التأكيد. الافتراضي: Pay securely with your credit or debit card via Stripe.

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

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

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

مفاتيح API

انسخ المفاتيح السرية من Stripe Dashboard > Developers > API keys (تحتوي الصفحة على رابط إليها). مفاتيح الاختبار ومفاتيح الإنتاج منفصلة. يستخدم وضع الاختبار مفاتيح الاختبار فقط، ويستخدم وضع الإنتاج مفاتيح الإنتاج فقط.

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

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 the saved value on save أسفل الحقل، وانقر على Save.

Webhook

يُخبر webhook متجرك بأن دفعة قد تمت. في Stripe Dashboard > Developers > Webhooks أضف نقطة نهاية في وضع الاختبار وأخرى في وضع الإنتاج. استخدم الرابط الظاهر في Endpoint URL في هذا القسم. في OpenCart 3 يبدو هكذا: https://your-store/index.php?route=extension/payment/wcp_stripe_gateway/webhook، وفي OpenCart 4 يبدو هكذا: https://your-store/index.php?route=extension/wcp_stripe_gateway/payment/wcp_stripe_gateway.webhook. ويُبنى من عنوان الواجهة الأمامية لتثبيت OpenCart لديك. انسخ الرابط تمامًا كما تعرضه الإعدادات.

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

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

الطلبات

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

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

Awaiting Payment Status: دفعة مؤجلة: انتهت صفحة الدفع، لكن Stripe لم تؤكد المبلغ بعد. الافتراضي: Pending.

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

Failed Payment Status: فشلت دفعة مؤجلة. الافتراضي: Failed.

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

متقدم

Logging: يكتب طلبات Stripe وwebhooks في strg_debug.log.php داخل مجلد سجلات OpenCart (storage/logs). لا يمكن فتح الملف من الويب، وعند بلوغه 5 ميغابايت يُنقل إلى strg_debug.old.log.php. لا تُسجَّل المفاتيح وبيانات العملاء. الافتراضي: معطّل. وما دام معطّلًا لا يُكتب أي شيء، ولا حتى الأخطاء.

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

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

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

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

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

صفحة الدفع

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

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

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

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

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

يعمل webhook أيضًا أثناء وضع الصيانة في المتجر، لأن OpenCart يسمح بمرور طلبات إضافات الدفع.

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

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

حالات الطلب

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

Order Status After Payment (الافتراضي Processing): تم تأكيد الدفع. تُظهر ملاحظة دفعة Stripe (pi_...) والجلسة وكيفية تأكيدها (webhook أو العودة).

Awaiting Payment Status (الافتراضي Pending): أنهى العميل الطلب بطريقة دفع مؤجلة. عندما تؤكد Stripe الدفع ينتقل الطلب إلى Order Status After Payment؛ وعندما يفشل الدفع ينتقل إلى Failed Payment Status. يُبلغ OpenCart العميل بهذه التغييرات.

On Hold (Review) Status (الافتراضي Pending): أبلغت Stripe بمبلغ أو عملة يختلفان عن إجمالي الطلب، أو وصلت الدفعة بعد أن أُلغي الطلب أو تغيّرت حالته. تشرح الملاحظة ذلك. تحقق من الطلب ونفّذه، أو استرد الدفعة.

Refunded Status (الافتراضي Refunded): استُرد الدفع بالكامل عبر الإضافة.

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

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

تبويب VibeFox Stripe Gateway

في Sales > Orders افتح طلبًا دُفع عبر Stripe. في أسفل صفحة الطلب، بجوار History وAdditional، يعرض تبويب VibeFox Stripe Gateway معرّف دفعة Stripe (مرتبطًا بالدفعة في Stripe Dashboard) مع تسمية Test mode للدفعات التجريبية، وCheckout Session، وStatus الدفعة، والمبالغ Paid / refunded، ونموذج الاسترداد، وسجل الاستردادات، وStripe notes الخاصة بالطلب. يظهر التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة.

الاستردادات

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

لا تعيد المرتجعات في Sales > Returns الأموال عبر Stripe.

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

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

تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox Stripe Gateway هي الكتلة الأولى في Extensions > Extensions > Payments > VibeFox Stripe Gateway > Edit، فوق الإعدادات. الصق المفتاح في License key وانقر على Activate. بعد ذلك تعرض الكتلة المفتاح مقنّعًا، والحالة (مثل تاريخ انتهاء صلاحية الترخيص ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وتحتها السطر Product: opencart-payment-stripe والرابط 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.

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

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

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

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

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

يرى العميل خطأ بعد Confirm Order: فعّل Logging وانظر إلى الحقل Log في صفحة الإضافة. تعني الرسالة This payment method is not available. Please reload the checkout page. أن جلسة الدفع لم تعد تطابق الطلب، أو أن طريقة الدفع أُوقفت في هذه الأثناء: يعيد العميل تحميل صفحة الدفع. يعطي المفتاح الخاطئ رسالة بأن طريقة الدفع غير مُعدّة بشكل صحيح. ولا يمكن دفع طلب إجماليه أقل من الحد الأدنى لـ Stripe بالعملة (مثلًا 0.50 EUR) عبر Stripe.

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

الطلب في حالة المراجعة بعد الدفع: اقرأ الملاحظات في تبويب VibeFox Stripe Gateway (انظر حالات الطلب)، ثم نفّذ الطلب أو استرد الدفعة.

لا يوجد نموذج استرداد في التبويب: يذكر التبويب السبب: الدفعة لم تُؤكَّد بعد، أو استُردت بالكامل، أو ليس لمجموعة المستخدمين لديك صلاحية تعديل الإضافة.

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

للمطورين: قبل إنشاء جلسة Stripe تُطلق الإضافة حدث OpenCart strg_checkout_session_params مع معاملات الجلسة والطلب.

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

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

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

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