كيفية إضافة المدفوعات إلى تطبيقك: الدفع والاشتراكات والـ Webhooks

أبسط طريقة لإضافة المدفوعات إلى تطبيقك هي Stripe: استخدم رابط دفع (Payment Link) إذا كنت تحتاج فقط إلى زر "اشترِ" وتستطيع معالجة الطلبات يدوياً، أو Stripe Checkout إذا كان تطبيقك يحتاج إلى معرفة من دفع والتفاعل تلقائياً، وCheckout في وضع الاشتراك مع بوابة العميل في Stripe للفوترة المتكررة. وفي كل الحالات عدا الأبسط، ستحتاج أيضاً إلى webhook، وهو نقطة نهاية على خادمك يستدعيها Stripe عند نجاح الدفعة، ويجب أن تختبر كل شيء بمفاتيح الاختبار وبطاقات الاختبار الخاصة بـ Stripe قبل الانتقال إلى المفاتيح الحقيقية.

يشرح هذا الدليل كل خيار، وجزء الـ webhook الذي تتجاوزه معظم الشروحات، وما يجب التحقق منه قبل قبول أموال حقيقية. تفاصيل Stripe مأخوذة من وثائق Stripe نفسها اعتباراً من سبتمبر 2026.

لماذا تستخدم مزوّد دفع أصلاً

لا تجمع أرقام البطاقات في نماذجك الخاصة أبداً. فالتعامل مع بيانات البطاقات الخام يُدخلك في نطاق معيار PCI DSS (معيار الأمان في صناعة البطاقات) ويحمّلك مسؤولية كبيرة. مزوّد دفع مثل Stripe يستضيف نموذج الدفع، ويخزّن البطاقة، ويتولى مصادقة البنك، ويخبر تطبيقك بالنتيجة. تطبيقك لا يرى أبداً سوى "العميل X دفع مقابل Y".

يستخدم هذا الدليل Stripe لأنه منتشر على نطاق واسع، وموثّق جيداً، ومدعوم من معظم منشئي التطبيقات بالذكاء الاصطناعي. توجد مزوّدات أخرى، وبعضها يعمل كـ"تاجر مسجّل" (merchant of record) يتولى التعامل مع ضريبة المبيعات نيابةً عنك؛ وإذا كان الامتثال الضريبي يقلقك، فهذا النموذج يستحق المقارنة.

الطرق الثلاث لقبول المدفوعات مع Stripe

روابط الدفع

رابط الدفع صفحة دفع تستضيفها Stripe، وتنشئها من لوحة تحكم Stripe دون كود. تحصل على عنوان URL يمكنك وضعه خلف زر في تطبيقك، أو مشاركته في بريد إلكتروني، أو عرضه كرمز QR. وتقول وثائق Stripe إن روابط الدفع يمكنها بيع منتج أو اشتراك أو قبول تبرع، ويمكنك السماح للعملاء باختيار ما يدفعونه أو تحديد عدد مرات الشراء.

لكن المشكلة أن تطبيقك لا يعرف تلقائياً أن مستخدماً معيناً مسجّلاً الدخول قد دفع. وهذا مقبول لصفحة تبرعات أو متجر صغير تنفذ طلباته يدوياً من إشعارات Stripe بالبريد. أما "ادفع لفتح ميزات Pro" فليس مناسباً لذلك.

Stripe Checkout

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

التدفق:

1. يضغط العميل على اشترِ في تطبيقك.
2. ينشئ خادمك جلسة Checkout باستخدام مفتاحك السري، ويتضمن معرّفاً يربطها بمستخدمك أو طلبك.
3. يُعاد توجيه العميل إلى Stripe ويدفع.
4. تعيد Stripe توجيهه إلى صفحة النجاح في تطبيقك.
5. ترسل Stripe حدث checkout.session.completed إلى الـ webhook الخاص بك، فيضع خادمك علامة "مدفوع" على الطلب أو يفتح الوصول.

يجب أن تتم الخطوة 2 على الخادم، لأنها تستخدم مفتاحك السري. وهذا هو السبب الرئيسي لحاجة Checkout إلى جزء خلفي (backend).

الاشتراكات

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

ولتمكين العملاء من إدارة اشتراكهم بأنفسهم، يقدم Stripe بوابة عميل (customer portal) تستضيفها. وبحسب وثائق Stripe، يستطيع العملاء هناك تحديث طرق الدفع وتفاصيل الفوترة، وتغيير الاشتراكات أو إلغاءها، وعرض الفواتير وتنزيلها. تهيّئها من لوحة تحكم Stripe وتضيف زر "إدارة الفوترة" يرسل العميل إليها. وهذا يوفّر عليك بناء تلك الشاشات بنفسك.

الـ Webhooks: الجزء الذي لا يمكنك تخطيه

الـ webhook طلب HTTP ترسله Stripe إلى خادمك عند حدوث شيء ما. (انظر ما هو الـ webhook للفكرة العامة.) دليل التنفيذ في Stripe واضح: لا يمكنك الاعتماد على صفحة النجاح وحدها لتنفيذ الطلبات، لأن العميل قد يدفع ثم يفقد اتصاله قبل تحميل تلك الصفحة. وبالنسبة للاشتراكات ووسائل الدفع المؤجلة، الـ webhooks مطلوبة.

الأحداث التي تستحق المعالجة

قواعد معالج webhook صحيح

هذه القواعد مأخوذة مباشرة من وثائق Stripe للـ webhooks، وأحياناً تغفلها المعالجات المولّدة بالذكاء الاصطناعي:

• تحقّق من التوقيع. كل حدث يتضمن رأس Stripe-Signature. يتحقق معالجك منه باستخدام سر التوقيع الخاص بنقطة النهاية (يبدأ بـ whsec_). وبدون ذلك، يمكن لأي شخص أن يرسل إلى خادمك إشعاراً مزيفاً بأن "الدفع نجح".
• استخدم جسم الطلب الخام (raw body). تفشل فحوصات التوقيع إذا حلّل إطار العمل الجسم أو عدّله أولاً.
• أعد استجابة 2xx بسرعة، ثم نفّذ الأعمال الأبطأ لاحقاً. فانتهاء المهلة يُحسب فشلاً.
• تعامل مع التكرار. قد ترسل Stripe الحدث نفسه أكثر من مرة. سجّل معرّفات الأحداث التي عولجت، أو اجعل تنفيذ الطلب آمناً عند تكراره.
• لا تفترض الترتيب. لا تضمن Stripe وصول الأحداث بالترتيب الذي وقعت به.
• توقّع إعادة المحاولة. في الوضع الحي، تعيد Stripe محاولة التسليم الفاشل لمدة تصل إلى ثلاثة أيام، فلا تضيع المدفوعات بسبب انقطاع قصير، لكن معالجك يجب أن يتعامل مع الأحداث المتأخرة.

تحتاج الـ webhooks إلى عنوان HTTPS عام، لذلك لا تعمل عادةً إلا بعد نشر تطبيقك (يستطيع CLI الخاص بـ Stripe توجيه الأحداث إلى جهاز محلي للمطوّرين).

مطالبة واحدة تغطي التدفق كله

أضف عملية شراء لمرة واحدة باستخدام Stripe Checkout لـ "Pro pack" (معرّف السعر في STRIPE_PRICE_ID). أنشئ جلسة Checkout على الخادم باستخدام STRIPE_SECRET_KEY من الأسرار، وضمّن معرّف المستخدم المسجّل الدخول في الجلسة. أضف نقطة نهاية POST /api/stripe/webhook تتحقق من توقيع Stripe باستخدام STRIPE_WEBHOOK_SECRET ومن جسم الطلب الخام، وتعالج checkout.session.completed، وتضع علامة على هذا المستخدم بأنه يملك Pro pack. اجعلها آمنة إذا وصل الحدث نفسه مرتين. أضف صفحتي نجاح وإلغاء. لا تعرض المفتاح السري أبداً في المتصفح.

بالنسبة للاشتراكات، أضف: "استخدم وضع الاشتراك مع STRIPE_PRICE_ID. عالج invoice.paid وinvoice.payment_failed وcustomer.subscription.updated وcustomer.subscription.deleted. أضف زر إدارة الفوترة يفتح بوابة عميل Stripe."

وضع الاختبار

لدى Stripe بيئتان منفصلتان: بيئة الاختبار (sandbox/test) والبيئة الحية، ولكل منهما مفاتيح منفصلة. تبدأ مفاتيح الاختبار بـ pk_test_ أو sk_test_ أو rk_test_، وتبدأ المفاتيح الحية بـ pk_live_ أو sk_live_ أو rk_live_. المعاملات التجريبية لا تنقل أموالاً.

بطاقات اختبار مفيدة من وثائق اختبار Stripe (أي تاريخ انتهاء مستقبلي، ورمز CVC من ثلاثة أرقام):

اختبر على الأقل:

• الدفع الناجح يفتح الشيء الصحيح للمستخدم الصحيح
• البطاقة المرفوضة تعرض رسالة واضحة ولا تفتح شيئاً
• إغلاق تبويب المتصفح مباشرة بعد الدفع ما زال يؤدي إلى منح الوصول (هذا يثبت أن الـ webhook يعمل، لا صفحة النجاح فقط)
• الإلغاء في صفحة Stripe يعيد المستخدم إلى تطبيقك دون أي خصم
• بالنسبة للاشتراكات: ألغِ من بوابة العميل وتأكد من انتهاء الوصول في الوقت الصحيح

الإطلاق الفعلي

1. فعّل حساب Stripe ببيانات نشاطك التجاري والبنك.
2. ضع المفاتيح الحية في أسرار تطبيقك. وتوصي Stripe بمفاتيح مقيّدة (restricted keys) تملك فقط الصلاحيات التي يحتاجها تكاملك، بدلاً من مفتاح سري غير مقيّد.
3. أنشئ نقطة نهاية webhook حية تشير إلى تطبيقك المنشور. لها سر توقيع خاص بها يختلف عن سر الاختبار، فحدّثه.
4. أعد إنشاء المنتجات والأسعار في الوضع الحي؛ فمعرّفات وضع الاختبار غير موجودة هناك.
5. نفّذ عملية شراء حقيقية صغيرة واسترجعها.

احتفظ بكل المفاتيح في أسرار مشروعك، ولا تضعها أبداً في الكود أو في الدردشة. وتغطي قائمة فحص الأمان المفاتيح والتحقق من الـ webhooks بمزيد من التفصيل.

الضرائب والاسترجاع والأوراق

تجلب المدفوعات التزامات لا يحلّها الكود. وهذه ليست نصيحة ضريبية؛ استشر محاسباً.

• ضريبة المبيعات وضريبة القيمة المضافة وضريبة السلع والخدمات (GST). بحسب مكان وجودك ومكان عملائك، قد تحتاج إلى التسجيل وتحصيل الضريبة وتقديم الإقرارات. يستطيع Stripe Tax حساب الضريبة وتحصيلها عند الدفع، ومراقبة الأماكن التي قد تنشأ فيها التزامات بسبب مبيعاتك، والمساعدة في التسجيل والتقديم، لكن المسؤولية تبقى عليك. ومزوّدات التاجر المسجّل بديل يتولى قدراً أكبر من ذلك.
• الاسترجاع والنزاعات. حدد سياسة الاسترجاع قبل الإطلاق وانشرها في موقعك. النزاعات (chargebacks) تحدث؛ واحتفظ بسجلات بما تم شراؤه وتسليمه.
• الإيصالات والفواتير. يستطيع Stripe إرسال الإيصالات بالبريد؛ وقد تحتاج الشركات إلى فواتير رسمية.
• الرسوم. كل مزوّد يتقاضى رسوماً لكل معاملة. تحقق من صفحة الأسعار الحالية للمزوّد بدلاً من الاعتماد على أرقام في المقالات.

أي إعداد يناسب تطبيقك

• تبرعات أو عدد قليل من المنتجات: روابط الدفع. انظر كيفية بناء موقع تبرعات لمنظمة غير ربحية.
• متجر بسلة تسوق: Checkout مع بنود الطلب وwebhook. انظر كيفية بناء متجر إلكتروني.
• SaaS أو عضويات: Checkout في وضع الاشتراك، والـ webhooks، وبوابة العميل. انظر كيفية بناء MVP لمنتج SaaS وكيفية تسعير منتج SaaS.
• سوق يدفع أرباحاً للبائعين: إعداد مختلف وأكثر تنظيماً (Stripe Connect أو ما شابهه). خطّط له بشكل منفصل.

إضافة المدفوعات في Mythex

تستخدم المدفوعات في التطبيقات التي تبنيها على Mythex حسابك الخاص في Stripe ومفاتيحك؛ لا يوجد زر "ربط Stripe" بنقرة واحدة لتطبيقك. والتدفق المعتاد:

1. احصل على مفاتيح Stripe للاختبار.
2. أضف STRIPE_SECRET_KEY (وسر الـ webhook لاحقاً) إلى أسرار المشروع، عبر /secrets أو إعدادات المشروع أو بطاقة الأسرار التي يعرضها الوكيل عندما يحتاج إلى مفتاح.
3. اطلب من الوكيل Checkout باستخدام مطالبة مثل المطالبة أعلاه.
4. اختبر في المعاينة ببطاقات الاختبار. انشر قبل تسجيل الـ webhook، لأنه يحتاج إلى عنوانك العام.
5. بعد الانتقال إلى المفاتيح الحية، انشر من جديد حتى يلتقطها التطبيق الحي.

انظر قبول المدفوعات باستخدام Stripe ومعالجة الـ webhooks في الخلفية في الوثائق.

الأسئلة