يُعد تكامل Stripe من أقوى الحلول المتاحة لبناء البنية التحتية للمدفوعات في مشاريع التجارة الإلكترونية وبرامج SaaS الحديثة. بفضل واجهة API الشاملة لـ Stripe ونظام الـ Webhook وحمايتها المتقدمة من الاحتيال، يمكنك إدارة مدفوعات البطاقات والاشتراكات والمعاملات متعددة العملات من منصة واحدة. ستجد في هذا الدليل كل خطوة لازمة لإعداد Stripe من الصفر.
إعداد حساب Stripe وإدارة مفاتيح API
لبدء تكامل Stripe، عليك أولاً إنشاء حساب على stripe.com. وبعد الموافقة على الحساب، يتاح لك عبر لوحة التحكم نوعان من مفاتيح API: المفتاح العام Publishable Key (يُستخدم في جانب العميل ويمكن مشاركته علناً) والمفتاح السري Secret Key (يجب استخدامه في جانب الخادم فقط وإبقاؤه سرياً تماماً). تتوفر مجموعات مفاتيح منفصلة لبيئتي الاختبار والإنتاج؛ استخدم مفاتيح الاختبار دائماً أثناء التطوير.
- Publishable Key: يُستخدم لتهيئة Stripe.js في شيفرة JavaScript الخاصة بالواجهة الأمامية، ويمكن إرساله إلى العميل بأمان.
- Secret Key: يُستخدم في استدعاءات API من جانب الخادم؛ ويجب تخزينه في ملف .env وعدم إضافته إلى الشيفرة المصدرية أبداً.
- Restricted Keys: يمكن إنشاؤها لمنح وصول محدود إلى عمليات API معينة؛ وهذا هو النهج الموصى به من الناحية الأمنية.
- Webhook Signing Secret: يُستخدم للتحقق من أن أحداث الـ Webhook الواردة صادرة فعلاً من Stripe.
إعداد نموذج الدفع باستخدام Stripe Elements وStripe.js
يقدم Stripe نهجين أساسيين لبناء نموذج الدفع: مكونات نماذج قابلة للتخصيص باستخدام Stripe.js، وStripe Checkout وهي صفحة دفع جاهزة مستضافة بالكامل. وكلاهما متوافق مع معيار PCI-DSS؛ إذ تُرسل بيانات البطاقة مباشرة إلى خوادم Stripe ولا تمر أبداً بخوادمك.
نماذج مخصصة باستخدام Stripe Elements
تتيح لك Stripe Elements بناء نماذج دفع مصممة خصيصاً لعلامتك التجارية. بعد تعريف عنصر div في ملف HTML وإنشاء نسخة من Stripe بواسطة JavaScript، تقوم بتركيب CardElement أو مكونات منفصلة (CardNumberElement وCardExpiryElement وCardCvcElement). وعندما يدخل المستخدم بيانات بطاقته، تحوّل Stripe.js هذه البيانات إلى رمز مميز (Token) وتُنشئ معرّف PaymentMethod. ترسل هذا المعرّف إلى خادمك وتُكمل عملية الدفع من جانب الخادم. توفر Elements دعم السمات (Theming) والتوافق مع الاتجاه من اليمين إلى اليسار (RTL) وتحسين لوحة المفاتيح على الجوال، مما يمنح تجربة مستخدم ممتازة.
تكامل Webhook: معالجة الأحداث في الوقت الفعلي
الـ Webhook في Stripe هي طلبات HTTP POST تُبلغ خادمك في الوقت الفعلي عند اكتمال عملية دفع أو تجديد اشتراك أو فشل عملية دفع. بعد تعريف نقطة نهاية الـ Webhook في لوحة تحكم Stripe، يجب عليك التحقق من الطلبات الواردة باستخدام ترويسة Stripe-Signature. وأهم أحداث الـ Webhook هي: payment_intent.succeeded (نجاح الدفع) وpayment_intent.payment_failed (فشل الدفع) وinvoice.paid (دفع الفاتورة) وcustomer.subscription.deleted (إلغاء الاشتراك). ومن الأهمية بمكان أن تكون شيفرة معالجة الـ Webhook لديك idempotent، أي ألا تُنشئ نسخاً مكررة عند استلام الحدث نفسه أكثر من مرة.
مدفوعات الاشتراكات مع Stripe
توفر وحدة Stripe Billing بنية تحتية شاملة لمنتجات SaaS والتجارة الإلكترونية القائمة على الاشتراكات. ولإعداد نظام اشتراكات، تنشئ تباعاً كائنات Product وPrice (خطة التسعير) وCustomer. ثم يُنشأ Subscription يربط العميل بـ Price. وتُصدر Stripe الفواتير تلقائياً وتحاول تحصيل الدفع وتطبق منطق إعادة المحاولة (Smart Retries) على المدفوعات الفاشلة.
تعدد العملات واستخدام Stripe في تركيا
تدعم Stripe أكثر من 135 عملة. وتُعد الليرة التركية (TRY) من العملات المدعومة؛ غير أن Stripe لا تفتح منذ عام 2022 حسابات مباشرة للشركات التي يقع مقرها في تركيا. ولهذا السبب ينشئ المطورون الأتراك عادةً حساباتهم عبر كيان قانوني في الخارج أو عبر Stripe Atlas. وبدلاً من ذلك، من الأساليب الشائعة استخدام İyzico أو PayTR كمزود دفع رئيسي للسوق التركية مع دمج Stripe للمعاملات الدولية.
الحماية من الاحتيال مع Stripe Radar
Stripe Radar هو نظام لكشف الاحتيال قائم على التعلم الآلي. فهو يحلل كل معاملة في الوقت الفعلي ويمنحها درجة مخاطر. ولأن Radar مدرَّب على بيانات ملايين الشركات في شبكة Stripe، فإنه يقدم نتائج أدق بكثير من الأنظمة الفردية القائمة على القواعد. وبالقواعد المخصصة يمكنك حظر دول بطاقات معينة، أو إضافة تحقق إضافي للمعاملات عالية القيمة، أو إدراج أنماط البريد الإلكتروني المشبوهة في القائمة السوداء. ومع حزمة Radar for Fraud Teams يمكنك تتبع المعاملات التي استلزمت تدخلاً أو مراجعة عبر تقارير تفصيلية.
- Block Rules: تحظر تلقائياً المعاملات التي تستوفي شروطاً معينة.
- Review Rules: تضع المعاملات المشبوهة في قائمة انتظار للمراجعة اليدوية.
- Allow Rules: تسمح بمرور معاملات العملاء الموثوقين دون تحقق.
- 3DS Triggering: يمكن تفعيل 3D Secure تلقائياً على المعاملات ذات درجة المخاطر العالية.
إعداد بيئة الاختبار وأفضل الممارسات
توفر Stripe مجموعة شاملة من أرقام البطاقات التجريبية لبيئة الاختبار. فرقم البطاقة 4242 4242 4242 4242 يحاكي عملية دفع ناجحة، بينما يُستخدم الرقم 4000 0000 0000 0002 لاختبار عملية دفع مرفوضة. وتتوفر بطاقات اختبار خاصة للسيناريوهات التي تتطلب 3DS. ولتكامل مثالي، اتبع أفضل الممارسات التالية: لا تضع Secret Key في شيفرة الواجهة الأمامية أبداً؛ وتحقق دائماً من توقيعات الـ Webhook؛ وتخلّص من خطر التكرار باستخدام مفاتيح idempotency؛ واعرض رسائل الخطأ بطريقة سهلة للمستخدم؛ واستخدم أحدث إصدار من SDK الخاص بـ Stripe.
الأسئلة الشائعة
كم يستغرق تكامل Stripe؟
يمكن لمطور ذي خبرة إنجاز تكامل بسيط للدفع لمرة واحدة خلال يوم إلى يومين. أما التكامل الشامل الذي يتضمن الـ Webhook والاشتراكات وقواعد Radar المتقدمة فيستغرق عادةً من أسبوع إلى أسبوعين. تذكّر أن تُدرج إعداد بيئتي الاختبار والتجريب (Staging) ضمن هذا الإطار الزمني.
ما هي رسوم Stripe؟
السعر القياسي لدى Stripe هو 2.9% إضافة إلى 30 سنتاً لكل معاملة (بالدولار الأمريكي). وقد تختلف الأسعار بالنسبة للمعاملات بالليرة التركية وفي بلدان مختلفة. ويمكن التفاوض على أسعار مخصصة للشركات ذات الحجم الكبير. وتُطبق رسوم Billing إضافية على مدفوعات الاشتراكات.
هل يمكن استخدام Stripe من تركيا؟
لا تفتح Stripe حسابات مباشرة للشركات في تركيا. ومع ذلك، يمكن إنشاء حساب عبر كيان قانوني في الخارج (مثل شركة LLC أمريكية أو شركة Ltd بريطانية) أو عبر برنامج Stripe Atlas. ولقبول المدفوعات من تركيا يُوصى باتباع نهج هجين بالتكامل مع مزودي خدمات الدفع المحليين (PSPs).
كيف تختبر الـ Webhook في Stripe؟
باستخدام أداة Stripe CLI يمكنك تمرير أحداث الـ Webhook إلى بيئة التطوير المحلية لديك. وفي سطر الأوامر، يمرر الأمر stripe listen --forward-to localhost:3000/webhook الـ Webhook إلى نقطة النهاية المحلية، ويرسل الأمر stripe trigger payment_intent.succeeded حدثاً تجريبياً.
الخلاصة
عند تهيئته بشكل صحيح، يوفر تكامل Stripe بنية تحتية للمدفوعات آمنة ومرنة وقابلة للتوسع. فالاهتمام الدقيق بكل التفاصيل، من إدارة مفاتيح API إلى أمان الـ Webhook، ومن نظام الاشتراكات إلى الحماية من الاحتيال، يصنع فارقاً كبيراً على المدى الطويل من حيث الكفاءة التشغيلية ورضا العملاء. تواصل مع Toserof Tech. بشأن مشاريع تكامل متجرك الإلكتروني.
