سترايب (Stripe)
يتيح سترايب لمتجرك قبول مدفوعات البطاقات عبر صفحة Checkout المستضافة لديه. تربط حسابك الخاص في سترايب، فتصل الأموال إليك مباشرة.
التكامل للبطاقات فقط عن قصد — المحافظ وطرق الدفع المحلية غير مفعّلة — وبتحصيل تلقائي: تُسحب الأموال عند إتمام المشتري للدفع دون خطوة تحصيل منفصلة.
الربط
الإعدادات ← المدفوعات ← سترايب.
| البيانات | مطلوبة | من أين تحصل عليها |
|---|---|---|
| المفتاح السري | نعم | لوحة تحكم سترايب ← Developers ← API keys. يبدأ بـ sk_. |
| المفتاح العام | نعم | المكان نفسه. يبدأ بـ pk_. |
| مفتاح الويب هوك | نعم عمليًا | يُنشأ عند إضافة عنوان الويب هوك أدناه. يبدأ بـ whsec_. |
الحقل اختياري في الحفظ، لكن لا تستطيع TakeTheme التحقق من توقيع سترايب بدونه فتتجاهل الأحداث الواردة — وبما أن الطلبات الإلكترونية يُنشئها الويب هوك، فإن النتيجة هي عدم إنشاء أي طلب. اضبطه قبل قبول مدفوعات حقيقية.
الإعدادات
| الإعداد | الافتراضي | الوظيفة |
|---|---|---|
| إرسال بريد تأكيد الدفع | مفعّل | يرسل بريدًا للعميل عند نجاح الدفع |
| التنبيه عند فشل الدفع (عناوين بريد) | فارغ | ينبّه هذه العناوين عند فشل عملية دفع لدى سترايب |
| تعليم الطلبات كمدفوعة تلقائيًا | مفعّل | غير مُفعَّل حاليًا — أي دفع مؤكَّد يجعل الطلب مدفوعًا على أي حال |
مسار الدفع
- يختار المشتري سترايب عند إتمام الشراء ويؤكد.
- تُنشئ TakeTheme جلسة Checkout تحتوي بنود الطلب والشحن والضريبة، وتحوّله إلى صفحة سترايب المستضافة.
- يدفع بالبطاقة.
- يرسل سترايب حدث ويب هوك، ويُنشأ الطلب في هذه اللحظة وهو مدفوع بالفعل.
- يعود المشتري إلى صفحة النجاح أو الإلغاء في متجرك.
تنتهي صلاحية جلسات Checkout بعد ساعة واحدة من إنشائها. والمشتري الذي يترك الصفحة مفتوحة أطول من ذلك عليه البدء من جديد.
إذا ترك المشتري صفحة سترايب دون دفع، فلن يُنشأ شيء — وتظهر المحاولة ضمن السلات المتروكة. راجع كيف تعمل المدفوعات.
أما عند تحصيل دفعة على طلب موجود مسبقًا (كفاتورة ترسلها)، فتُربط الجلسة بذلك الطلب منذ البداية ويكتفي الويب هوك بتعليمه كمدفوع.
إعداد الويب هوك
من لوحة تحكم سترايب اذهب إلى Developers ← Webhooks ← Add endpoint وأدخل:
POST https://<your-api-host>/v1/webhooks/stripe
ثم انسخ مفتاح التوقيع الناتج إلى حقل مفتاح الويب هوك أعلاه.
تتعامل TakeTheme مع ثلاثة أحداث:
| الحدث | ما يحدث |
|---|---|
checkout.session.completed | تُعلَّم الدفعة كمدفوعة ويُنشأ الطلب |
payment_intent.succeeded | تُعلَّم الدفعة كمدفوعة ويُنشأ الطلب ويُحدَّث السجل الزمني |
payment_intent.payment_failed | تُعلَّم الدفعة كفاشلة مع تسجيل سبب الرفض من سترايب |
أما بقية الأحداث فتُقبل وتُتجاهل.
يُتحقق من التوقيع في كل حدث، وتُرفض الأحداث الأقدم من خمس دقائق — فلا يمكن إعادة تشغيل حدث مُلتقَط ضد متجرك لاحقًا. التوقيع المفقود أو غير الصالح يعيد 400، وما عدا ذلك يُقبل بالرمز 200 حتى لا يعيد سترايب المحاولة على مشكلة لا يستطيع حلها.
تحمل الأحداث هوية متجرك، فلا يمكن أبدًا لحدث يخص متجرًا أن يمسّ طلبات متجر آخر.
الاسترداد
الاسترداد في TakeTheme يسجّل العملية على الطلب، ولا يستدعي واجهة الاسترداد لدى سترايب. نفّذ الاسترداد من لوحة تحكم سترايب ثم سجّله على الطلب حتى تتطابق تقاريرك. راجع الاسترداد.
الاختبار قبل الإطلاق
استخدم وضع الاختبار في سترايب مع بطاقة اختبار مثل 4242 4242 4242 4242، ونفّذ عملية شراء حقيقية من متجرك. هذه هي الطريقة الوحيدة لاختبار المسار كاملًا: جلسة ← ويب هوك ← طلب.
وإذا كنت تشغّل الـ API محليًا، يمكن لأداة Stripe CLI تمرير الأحداث إلى جهازك:
stripe listen --forward-to localhost:8080/v1/webhooks/stripe
الصق مفتاح whsec_… الذي تطبعه الأداة في حقل مفتاح الويب هوك حتى ينجح التحقق.
انتبه إلى أن أحداث stripe trigger … بيانات وهمية بلا متجر مرتبط: تتحقق TakeTheme من التوقيع ثم لا تفعل شيئًا عن قصد. المطلوب هو عملية شراء حقيقية في وضع الاختبار.
حل المشكلات
دفع المشتري ولم يظهر أي طلب. هي مشكلة ويب هوك في الغالب: لا يوجد مفتاح محفوظ، أو العنوان خاطئ، أو المفتاح يخص بيئة سترايب أخرى. راجع Developers ← Webhooks في سترايب لترى محاولات الإرسال واستجاباتها.
الويب هوك أعاد 200 ولم يحدث شيء.
الحدث لم يحمل هوية متجر — وهو أمر معتاد في أحداث Stripe CLI — أو أن المتجر لا يملك إعداد سترايب مطابقًا. تقبل TakeTheme الحدث لإيقاف إعادة المحاولة وتسجّل السبب.
المبالغ في سترايب تبدو أكبر بمئة ضعف. سترايب يعمل بأصغر وحدة للعملة (السنتات/القروش). المبلغ المخصوم صحيح.
مدفوعات الاختبار تعمل والمباشرة لا. مفاتيح الاختبار والإنتاج غير متبادلة، ولكل بيئة مفتاح ويب هوك خاص بها. بدّل البيانات الثلاثة معًا.