ربط Stripe: من الإعداد لأول دفعة

الجزء 1: اعمل حساب Stripe وخد مفاتيحك

روح stripe.com وسجّل. هتاخد مفتاحين API: المفتاح القابل للنشر (آمن إنه يظهر في كود الواجهة) والمفتاح السري (متعرضهوش أبداً؛ خليه في .env بس).

Stripe كمان بيديك سر توقيع webhook (بيتستخدم علشان تتحقق إن أحداث الـ webhook جاية من Stripe فعلاً).

خلي دول في ملف .env.local:

NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_...
STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...

الجزء 2: اعمل منتجاتك وأسعارك في Stripe

في لوحة تحكم Stripe، اعمل منتج ("الخطة الاحترافية") وضيف له سعر (99 دولار في الشهر أو 990 في السنة).

هتاخد معرّف سعر (price_1A2b3c4d...). المعرّف دا بيروح لقاعدة بياناتك ولكودك.

أفضل ممارسة: خلي معرّف السعر في قاعدة بياناتك جنب تعريف خطتك. متكتبش معرّفات Stripe ثابتة في الكود. دايماً هاتها من مصدر آمن (قاعدة البيانات أو الإعدادات).

الجزء 3: اعمل جلسة اشتراك

لما المستخدم يدوس "اشترك"، بتعمل جلسة Stripe Checkout. الجلسة دي رابط بتحوّل المستخدم عليه. بيدخل بيانات دفعه على Stripe (آمن) ويرجع لموقعك.

الكود من ناحية الخادم (مسار API في Next.js) بيعمل جلسة فيها إيميل العميل، والعناصر المطلوبة (معرّف السعر)، والوضع (اشتراك)، وروابط النجاح والإلغاء.

الجزء 4: تعامل مع أحداث الـ webhook

لما المستخدم يكمّل الدفع، Stripe بيبعت حدث webhook (checkout.session.completed). الحدث دا بيشغّل خادمك علشان: (1) يتحقق إن الاشتراك نجح. (2) يعمل سجل اشتراك في قاعدة بياناتك. (3) يفعّل حساب المستخدم.

من غير الـ webhooks، ممكن تفوّت بدايات اشتراكات (المستخدم بيكمّل الدفع بس خادمك بيقع قبل الحفظ). الـ webhooks هي الطريقة الموثوقة.

الجزء 5: تعامل مع الفشل وإعادة المحاولة

المستخدمين هيفشلوا في الدفع لأسباب: كارت غير صالح، كارت منتهي، رصيد غير كافي. Stripe بيعيد المحاولة تلقائياً (3 مرات على مدى 5 أيام). بس أنت محتاج تتعامل مع حدث فشل الدفع.

استمع لـ invoice.payment_failed وابعت إيميل للمستخدم: "دفعتك فشلت. حدّث طريقة الدفع من هنا: [رابط]."

دايماً ادي المستخدمين طريقة يحدّثوا بيها طريقة دفعهم (بوابة عملاء Stripe).

الجزء 6: اختبر قبل الإطلاق

استخدم وضع الاختبار في Stripe (المفاتيح بتبدأ بـ pk_test_ وsk_test_). في وضع الاختبار تقدر تشترك من غير كارت حقيقي.

أرقام كروت الاختبار (من توثيق Stripe):

• نجاح: 4242 4242 4242 4242 (أي تاريخ انتهاء مستقبلي، أي CVC)
• مرفوض: 4000 0000 0000 0002 (مرفوض لعدم كفاية الرصيد)
• بيتطلب مصادقة: 4000 0000 0000 3220 (بيتطلب 3D Secure)

اختبر المسار كامل: اشتراك ← نجاح دفع ← تحديث قاعدة البيانات ← تأكد إن الاشتراك اتعمل.

أخطاء شائعة

الخطأ الأول: تعريض المفتاح السري في كود الواجهة. أبداً. خليه في .env.local (الخادم بس).

الخطأ التاني: عدم التحقق من توقيعات الـ webhook. دايماً استدعي stripe.webhooks.constructEvent() للتحقق.

الخطأ التالت: الاعتماد على تأكيد النجاح من العميل بس. دايماً أكّد عن طريق الـ webhook.

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

الخطأ الخامس: كتابة معرّفات الأسعار ثابتة في الكود. خليها في قاعدة البيانات علشان تقدر تغيّر التسعير من غير نشر.