كيفية إضافة الاشتراكات مع Stripe: الخطط والتجارب المجانية والـ Webhooks والمدفوعات الفاشلة
لإضافة الاشتراكات مع Stripe، أنشئ منتجاً بسعر متكرر في لوحة تحكم Stripe، ووجّه العملاء من خادمك إلى Stripe Checkout في وضع الاشتراك، ودع webhook يخبر تطبيقك عند نجاح كل دفعة أو فشلها أو تغيرها أو انتهائها. خزّن حالة الاشتراك مقابل المستخدم، وامنح الوصول بناءً عليها، لا بناءً على صفحة النجاح. وأضف زر إدارة الفوترة الذي يفتح بوابة العميل المستضافة من Stripe، ليتمكن الناس من تغيير البطاقات، وتبديل الخطط، والإلغاء دون أن تبني تلك الشاشات بنفسك.
يعتمد هذا الدليل على كيفية إضافة المدفوعات إلى تطبيقك، الذي يغطي Checkout لمرة واحدة، ووضع الاختبار، والإطلاق الفعلي. وهنا نركز على ما يختلف في الفوترة المتكررة. تفاصيل Stripe مأخوذة من وثائق Stripe اعتباراً من سبتمبر 2026.
لماذا الاشتراكات أصعب من المدفوعات لمرة واحدة
الدفعة لمرة واحدة تحدث أثناء وجود العميل في تطبيقك. أما الاشتراك فيستمر بعد أن يغادر: تجديدات كل شهر، وبطاقات تنتهي صلاحيتها، وترقيات في منتصف الدورة، وإلغاءات تسري في نهاية الفترة. ولا يعرف تطبيقك عن هذه الأشياء إلا عبر الـ webhooks. ومعظم أخطاء الاشتراكات تنشأ من اعتبار الدفعة الأولى هي القصة كاملة.
خياراتك
| الأسلوب | ما الذي تبنيه | الأنسب لـ |
|---|---|---|
| رابط دفع بسعر متكرر | لا شيء سوى الرابط | اختبار الطلب؛ وإدارة الوصول يدوياً |
| Checkout (وضع الاشتراك) + بوابة العميل | مسار على الخادم، وwebhook، وزر فوترة | معظم تطبيقات SaaS والعضويات |
| واجهة Subscriptions البرمجية مع نموذج دفع خاص بك | الكثير أكثر: واجهة الدفع، والمصادقة، وإعادة المحاولة | التطبيقات ذات تدفقات الفوترة غير المعتادة |
| مزوّد تاجر مسجّل (merchant of record) | مشابه لـ Checkout | البائعون الذين يريدون من المزوّد التعامل مع ضريبة المبيعات |
بالنسبة لمعظم التطبيقات، يمثل Checkout مع البوابة المفاضلة الصحيحة. قارن المزوّدين في Stripe مقابل Paddle مقابل Lemon Squeezy إذا كانت معالجة الضرائب تقلقك.
خطّط تسعيرك في Stripe أولاً
في Stripe، المنتج هو ما تبيعه ("خطة Pro")، والسعر هو طريقة تحصيل ثمنه ("20 دولاراً شهرياً"، "200 دولار سنوياً"). يمكن لمنتج واحد أن يملك عدة أسعار. حدد:
- الفئات التي تقدمها، وما الذي تفتحه كل فئة في تطبيقك
- شهرياً، أم سنوياً، أم كليهما
- هل تقدم فترة تجريبية، وهل تحتاج إلى بطاقة مقدماً
أنشئ المنتجات والأسعار في وضع الاختبار، واحتفظ بمعرّفات الأسعار، فتطبيقك يشير إليها. إذا لم تحسم التسعير بعد، فاقرأ كيفية تسعير منتج SaaS والفريميوم مقابل الفترة التجريبية المجانية.
دورة حياة الاشتراك التي يجب أن تعالجها
تعرض نظرة Stripe العامة على الاشتراكات الحالات التي يمكن أن يكون فيها الاشتراك. وأهمها بالنسبة للوصول:
| الحالة | ماذا تعني | هل تمنح الوصول؟ |
|---|---|---|
trialing | في فترة تجريبية | نعم |
active | في وضع جيد | نعم |
incomplete | لم تكتمل الدفعة الأولى بعد؛ وتمنح Stripe العميل 23 ساعة | لا |
incomplete_expired | لم تنجح الدفعة الأولى أبداً | لا |
past_due | فشلت أحدث دفعة أو لم تُحاوَل؛ وقد تتبعها محاولات إعادة | خيارك؛ وكثير من التطبيقات تسمح بفترة سماح قصيرة |
unpaid | انتهت محاولات الإعادة، وتبقى الفواتير مفتوحة دون محاولات أخرى | لا، وتقول وثائق Stripe إنه يجب سحب الوصول |
canceled | انتهى، ولا يمكن إعادة تشغيله | لا |
paused | انتهت فترة تجريبية دون طريقة دفع، وضُبطت على الإيقاف المؤقت | لا |
خزّن الحالة في سجل المستخدم أو الحساب، وابنِ الوصول عليها. وحدّثها في كل مرة يصل فيها webhook ذو صلة.
أحداث الـ webhook التي يجب معالجتها
| الحدث | ما الذي يفعله تطبيقك |
|---|---|
checkout.session.completed | اربط معرّفات عميل Stripe والاشتراك الجديدة بمستخدمك |
invoice.paid | ضع الاشتراك في حالة active وسجّل نهاية الفترة الجديدة |
invoice.payment_failed | أخبر المستخدم أن بطاقته فشلت، واربطه بالبوابة |
invoice.payment_action_required | اطلب من المستخدم إكمال مصادقة البطاقة |
customer.subscription.updated | حدّث الخطة والحالة وأي إلغاء مجدول |
customer.subscription.deleted | أزل الوصول المدفوع |
customer.subscription.trial_will_end | ذكّر المستخدم قبل انتهاء الفترة التجريبية؛ ترسله Stripe قبل ثلاثة أيام |
قواعد معالج الـ webhook من وثائق Stripe ما زالت سارية: تحقق من التوقيع باستخدام الجسم الخام، وأعد استجابة 2xx بسرعة، وتعامل مع الأحداث المكررة والخارجة عن الترتيب، وتوقّع إعادة المحاولة. يشرح دليل ما هو الـ webhook الفكرة، ويسرد دليل المدفوعات القواعد بالتفصيل.
خطوة بخطوة
- أنشئ المنتجات والأسعار في وضع الاختبار في Stripe.
- أضف الأسرار: المفتاح السري، ومعرّفات الأسعار، ولاحقاً سر توقيع الـ webhook. لا تضعها أبداً في كود الواجهة الأمامية.
- صفحة الأسعار: يستدعي زر كل خطة خادمك، الذي ينشئ جلسة Checkout في وضع الاشتراك للمستخدم المسجّل الدخول. مرّر معرّف المستخدم حتى يستطيع الـ webhook مطابقة الدفعة مع الحساب.
- نقطة نهاية الـ webhook: تحقق من التوقيعات، وعالج الأحداث أعلاه، وحدّث سجل اشتراك واحد لكل مستخدم.
- قيّد الميزات بناءً على الحالة والخطة المخزّنة، وتحقق منها على الخادم في كل إجراء محمي، لا بالأزرار المخفية فقط.
- بوابة العميل: هيّئها في لوحة تحكم Stripe (إلى أي خطط يمكن للناس التبديل، وهل يستطيعون الإلغاء)، ثم أضف زر إدارة الفوترة الذي ينشئ جلسة بوابة على الخادم ويعيد التوجيه إليها.
- المدفوعات الفاشلة: في إعدادات الفوترة في Stripe، اختر سلوك إعادة المحاولة وما يحدث بعد المحاولة الأخيرة. اعرض شريطاً داخل التطبيق أثناء
past_due. - اختبر دورة الحياة كاملة، ثم انشر وسجّل الـ webhook الحي.
مطالبات تعطيها لمنشئ التطبيقات بالذكاء الاصطناعي
أضف فوترة الاشتراكات باستخدام Stripe. الخطط: Starter (معرّف السعر في STRIPE_PRICE_STARTER) وPro (STRIPE_PRICE_PRO). تنشئ صفحة الأسعار جلسة Checkout في وضع الاشتراك على الخادم باستخدام STRIPE_SECRET_KEY، مع إرفاق معرّف المستخدم المسجّل الدخول. احفظ معرّف عميل Stripe، ومعرّف الاشتراك، والخطة، والحالة في سجل المستخدم. لا تعرض المفتاح السري أبداً في المتصفح.
أضف POST /api/stripe/webhook. تحقق من التوقيع باستخدام STRIPE_WEBHOOK_SECRET ومن الجسم الخام للطلب. عالج checkout.session.completed وinvoice.paid وinvoice.payment_failed وcustomer.subscription.updated وcustomer.subscription.deleted وcustomer.subscription.trial_will_end. سجّل معرّفات الأحداث المعالجة حتى تُتجاهل المكررات. حدّث حالة المستخدم من كائن الاشتراك، لا من ترتيب وصول الأحداث.
قيّد ميزات Pro على الخادم: اسمح بها فقط عندما تكون الحالة active أو trialing والخطة Pro. اعرض شعار "فشلت الدفعة، حدّث بطاقتك" عندما تكون الحالة past_due. أضف زر إدارة الفوترة الذي يفتح بوابة عميل Stripe لهذا المستخدم.
الترقيات والتخفيضات والتناسب
عندما يبدّل العميل خطته، تقول وثائق Stripe إن التغيير غالباً ينشئ تناسباً (proration): يُطبَّق السعر الجديد على ما تبقّى من فترة الفوترة الحالية. يمكنك معاينة التناسب أو إيقافه. وإذا كانت الخطتان بالفاصل الزمني نفسه، تبقى تواريخ الفوترة كما هي؛ أما الانتقال من شهري إلى سنوي فينقل تاريخ الفوترة إلى يوم التغيير. ودع العملاء يغيرون الخطط في البوابة يوفر عليك كتابة هذا المنطق، لكن قرّر في إعدادات البوابة أي تبديلات مسموحة.
قائمة اختبار
استخدم وضع اختبار Stripe وبطاقات الاختبار، وامرّ على كل حالة:
- الاشتراك الجديد يمنح الخطة الصحيحة للمستخدم الصحيح
- إغلاق التبويب مباشرة بعد الدفع ما زال يمنح الوصول (هذا يثبت أن الـ webhook يعمل)
- بطاقة مرفوضة عند التسجيل لا تمنح شيئاً
- تجديد فاشل يضع الحساب في past_due ويعرض الشريط
- تحديث البطاقة في البوابة يعيد الحالة إلى active
- الترقية والتخفيض يغيّران الميزات بشكل صحيح
- الإلغاء في نهاية الفترة يُبقي الوصول حتى تاريخ الانتهاء، ثم يزيله
- مستخدمو الفترة التجريبية يحصلون على الوصول، ويتلقون التذكير، ويتحولون أو يفقدون الوصول بشكل صحيح
- إرسال حدث الـ webhook نفسه مرتين لا يغيّر شيئاً
تتيح لك ساعات الاختبار في Stripe محاكاة مرور الوقت، فيمكنك اختبار التجديدات دون انتظار شهر. راجع وثائق الاختبار الحالية في Stripe لمعرفة كيفية استخدامها.
أخطاء شائعة
- منح الوصول في صفحة النجاح. قد يدفع العملاء ولا يصلون إليها أبداً. استخدم الـ webhook.
- معالجة الدفعة الأولى فقط. تأتي التجديدات والفشل والإلغاءات لاحقاً، كأحداث.
- التحقق من حالة الخطة في الواجهة الأمامية فقط. يستطيع أي شخص استدعاء واجهتك البرمجية مباشرة.
- مستخدم واحد يملك عدة اشتراكات بالخطأ. تحقق من وجود اشتراك سابق قبل إنشاء جلسة Checkout جديدة، أو وجّه العملاء الحاليين إلى البوابة.
- سحب الوصول عند أول تجديد فاشل. تفشل البطاقات لأسباب عادية. فترة سماح قصيرة مع شريط واضح تُبقي العملاء.
- نسيان الـ webhook الحي. لنقاط النهاية في وضع الاختبار والوضع الحي أسرار توقيع مختلفة.
- تجاهل الضرائب والاسترجاع. حدد سياسة الاسترجاع، وتحقق من التزاماتك الضريبية مع محاسب قبل الإطلاق.
الاشتراكات في Mythex
التطبيقات التي تبنيها على Mythex تستخدم حسابك الخاص في Stripe ومفاتيحك؛ لا يوجد اتصال بنقرة واحدة بـ Stripe لتطبيقك. أضف مفاتيح الاختبار ومعرّفات الأسعار كأسرار للمشروع، واستخدم مطالبات مثل المطالبات أعلاه، واختبر ببطاقات Stripe التجريبية في المعاينة. تحتاج الـ webhooks إلى عنوان التطبيق العام، لذا انشر قبل تسجيل نقطة النهاية في Stripe، وانشر من جديد بعد الانتقال إلى المفاتيح الحية حتى يلتقطها التطبيق الحي. انظر قبول المدفوعات باستخدام Stripe ومعالجة الـ webhooks في الخلفية. وللمنتج الأوسع، يغطي كيفية بناء MVP لـ SaaS ما يجب بناؤه حول الفوترة.
الأسئلة
ما أبسط طريقة لإضافة الاشتراكات مع Stripe؟
أنشئ منتجاً بسعر متكرر في لوحة تحكم Stripe، ووجّه العملاء إلى Stripe Checkout في وضع الاشتراك، وعالج أحداث الاشتراك عبر webhook، واربط زر "إدارة الفوترة" ببوابة العميل المستضافة من Stripe. بذلك تتجنب بناء نماذج البطاقات وشاشات تغيير الخطط بنفسك.
ما أحداث webhook من Stripe التي أحتاجها للاشتراكات؟
على الأقل checkout.session.completed لربط الاشتراك الجديد بمستخدمك، وinvoice.paid لتأكيد كل دفعة ناجحة، وinvoice.payment_failed للتحذير من فشل التجديد، وcustomer.subscription.updated وcustomer.subscription.deleted لتتبع تغييرات الخطط والإلغاءات.
ماذا يحدث عندما يفشل دفع اشتراك؟
بحسب وثائق Stripe اعتباراً من سبتمبر 2026، يصبح الاشتراك عادةً past_due، وقد تعيد Stripe محاولة الدفع حسب إعداداتك. بعد المحاولة الأخيرة، تحدد إعدادات لوحة التحكم ما إذا كان الاشتراك سيُلغى، أو يُعلَّم unpaid، أو يبقى past_due.
هل يمكنني تقديم فترة تجريبية مجانية دون طلب بطاقة؟
نعم. تدعم Stripe الفترات التجريبية المجانية، وتصف وثائقها حالة paused للفترات التجريبية التي تنتهي دون طريقة دفع عند ضبطها بهذا الشكل. جمع البطاقة مقدماً يعني عادةً تسجيلات أقل لكن عملاء مدفوعين أكثر؛ اختبر ما يناسب منتجك.