1. ما هي Stripe ولماذا تحتاجها

Stripe هي منصة دفع رائدة تتيح للمتاجر الإلكترونية وخدمات SaaS وأي تطبيقات ويب أخرى قبول المدفوعات من العملاء حول العالم. توفر المكتبة الرسمية stripe الخاصة بـ Node.js للمطورين مجموعة كاملة من الأدوات لدمج واجهة API الخاصة بـ Stripe في الجزء الخادمي من التطبيق. تقوم هذه المكتبة بتجريد تعقيد طلبات HTTP المباشرة لواجهة Stripe، وتقدم واجهة سهلة الاستخدام ومكتوبة بشكل واضح ومتوقعة بلغة JavaScript.

لماذا تحتاج هذه المكتبة؟ في تطوير الويب الحديث، تعد معالجة المدفوعات الآمنة من أهم المهام. تتولى Stripe مسؤولية الامتثال لمعايير PCI DSS، ومعالجة البيانات الحساسة (أرقام البطاقات، CVV)، وإدارة السيناريوهات المعقدة (الاشتراكات، الاسترداد، النزاعات). تتيح لك مكتبة Node.js إنشاء نماذج دفع بسهولة، وإدارة العملاء، وإنشاء اشتراكات، ومعالجة webhooks، وإنشاء التقارير - كل ذلك باستخدام كود غير متزامن يعتمد على الوعود (Promises).

بفضل هذه المكتبة، يمكنك التركيز على منطق الأعمال الخاص بتطبيقك بدلاً من التفاصيل منخفضة المستوى لبروتوكولات الدفع. إنها مثالية لتطبيقات Node.js التي تعمل على Express أو Koa أو Fastify أو أي إطار عمل آخر. المكتبة مدعومة بنشاط من شركة Stripe، ويتم تحديثها بانتظام، ولها مجتمع ضخم.

2. التثبيت

لتثبيت مكتبة Stripe في مشروع Node.js الخاص بك، استخدم مدير الحزم npm أو yarn. قم بتنفيذ أحد الأوامر التالية في الدليل الجذر للمشروع:

# باستخدام npm
npm install stripe

# باستخدام yarn
yarn add stripe

بعد التثبيت، يمكنك استيراد المكتبة في الكود الخاص بك:

// الصيغة الحديثة (ES Modules)
import Stripe from 'stripe';

// أو CommonJS (الافتراضي في Node.js)
const Stripe = require('stripe');

هام: للعمل مع المكتبة، ستحتاج إلى مفتاح سري (sk_test_... لوضع الاختبار أو sk_live_... للإنتاج). يمكنك الحصول على المفتاح من لوحة تحكم Stripe.

3. بداية سريعة — مثال عملي بسيط

لنقم بإنشاء سكريبت بسيط يقوم بإنشاء نية دفع (PaymentIntent) — وهي الطريقة القياسية لقبول دفعة لمرة واحدة.

// استيراد المكتبة
const Stripe = require('stripe');
// التهيئة باستخدام المفتاح السري (استبدله بمفتاح الاختبار الخاص بك)
const stripe = Stripe('sk_test_XXXXXXXXXXXXXXXXXXXXXXXX');

async function createPayment() {
    try {
        // إنشاء PaymentIntent بمبلغ 2000 سنت (20 دولارًا أمريكيًا)
        const paymentIntent = await stripe.paymentIntents.create({
            amount: 2000,
            currency: 'usd',
            // وصف الدفعة (اختياري)
            description: 'دفعة اختبارية من Node.js',
            // التقاط الدفعة تلقائيًا (true) أو التفويض فقط (false)
            capture_method: 'automatic',
        });

        console.log('تم إنشاء PaymentIntent بنجاح:');
        console.log(`المعرف: ${paymentIntent.id}`);
        console.log(`الحالة: ${paymentIntent.status}`);
        console.log(`المبلغ: ${paymentIntent.amount} ${paymentIntent.currency.toUpperCase()}`);
    } catch (error) {
        console.error('خطأ أثناء إنشاء PaymentIntent:', error.message);
    }
}

createPayment();

هذا الكود