إنتقل إلى المحتوى الرئيسي

بوابات الدفع (Stripe وPayPal)

يدعم FeedbackPulse SaaS Stripe وPayPal لإدارة فواتير الاشتراكات. يمكنك تفعيل أحدهما أو كليهما.

💰 كيف تعمل الفوترة​

  1. تُنشئ خطط الاشتراك في الإدارة ← الخطط (مثلاً: Starter بـ 9.99$/شهر، Pro بـ 29.99$/شهر)
  2. لكل خطة معرف سعر Stripe و/أو معرف خطة PayPal
  3. عند اشتراك مستأجر، يُعاد توجيهه إلى Stripe Checkout أو PayPal
  4. بعد الدفع، يُفعّل FeedbackPulse اشتراكه
  5. تحافظ Webhooks على التزامن (التجديدات والإلغاءات والإخفاقات)

💳 إعداد Stripe​

الخطوة 1: إنشاء حساب Stripe​

  1. سجّل في stripe.com
  2. أكمل التحقق من الهوية
  3. احصل على مفاتيح API من Developers ← API Keys

الخطوة 2: الحصول على مفاتيح API​

المفتاحمكان الحصول عليهمتغير .env
المفتاح العامDashboard ← Developers ← API KeysSTRIPE_PUBLISHABLE_KEY
المفتاح السريDashboard ← Developers ← API KeysSTRIPE_SECRET_KEY
STRIPE_PUBLISHABLE_KEY=pk_live_xxxxxxxxxxxxxxxx
STRIPE_SECRET_KEY=sk_live_xxxxxxxxxxxxxxxx

🧪 الاختبار: استخدم مفاتيح pk_test_ وsk_test_ لوضع sandbox.

الخطوة 3: إنشاء المنتجات والأسعار في Stripe​

لكل خطة اشتراك، أنشئ سعرًا متكررًا في Stripe:

  1. انتقل إلى Products ← Add Product
  2. الاسم: "FeedbackPulse Starter" (أو اسم خطتك)
  3. أضف سعرًا متكررًا: 9.99$ / شهر
  4. أضف اختياريًا سعرًا سنويًا: 99.99$ / سنة
  5. انسخ معرف السعر (يبدأ بـ price_)

الخطوة 4: ربط الأسعار بالخطط​

في FeedbackPulse، انتقل إلى الإدارة ← الخطط ← تعديل:

حقل الخطةقيمة Stripe
معرف السعر الشهري لـ Stripeprice_xxxxxxxxx (معرف السعر الشهري)
معرف السعر السنوي لـ Stripeprice_xxxxxxxxx (معرف السعر السنوي)

الخطوة 5: إعداد Webhooks في Stripe​

هذا أمر بالغ الأهمية — تحافظ Webhooks على تزامن الاشتراكات.

  1. انتقل إلى Stripe Dashboard ← Developers ← Webhooks
  2. انقر على Add endpoint
  3. رابط نقطة النهاية: https://yourdomain.com/webhooks/stripe
  4. الأحداث المطلوب الاستماع إليها:
    • checkout.session.completed
    • customer.subscription.created
    • customer.subscription.updated
    • customer.subscription.deleted
    • invoice.payment_failed
  5. انسخ سر التوقيع (يبدأ بـ whsec_)
STRIPE_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxx

الخطوة 6: التفعيل من لوحة الإدارة​

انتقل إلى الإدارة ← الإعدادات ← المدفوعات:

  • فعّل Stripe
  • الصق مفاتيحك العامة والسرية
  • احفظ

💰 إعداد PayPal​

الخطوة 1: إنشاء حساب PayPal للأعمال​

  1. سجّل في paypal.com/business
  2. انتقل إلى developer.paypal.com

الخطوة 2: إنشاء تطبيق REST API​

  1. انتقل إلى Dashboard ← Apps & Credentials
  2. انقر على Create App
  3. الاسم: "FeedbackPulse"
  4. انسخ Client ID وSecret
PAYPAL_CLIENT_ID=your_client_id
PAYPAL_CLIENT_SECRET=your_client_secret
PAYPAL_MODE=live

🧪 الاختبار: استخدم PAYPAL_MODE=sandbox وبيانات اعتماد sandbox.

الخطوة 3: إنشاء خطط الاشتراك في PayPal​

  1. انتقل إلى PayPal Developer Dashboard ← Subscriptions ← Plans
  2. أنشئ منتجًا أولاً، ثم أنشئ خططًا له
  3. انسخ كل Plan ID (يبدأ بـ P-)

الخطوة 4: ربط الخطط في FeedbackPulse​

في الإدارة ← الخطط ← تعديل:

حقل الخطةقيمة PayPal
معرف الخطة الشهرية لـ PayPalP-xxxxxxxxx (الخطة الشهرية)
معرف الخطة السنوية لـ PayPalP-xxxxxxxxx (الخطة السنوية)

الخطوة 5: إعداد Webhooks في PayPal​

  1. في PayPal Developer Dashboard ← Webhooks
  2. أضف رابط webhook: https://yourdomain.com/webhooks/paypal
  3. اختر الأحداث:
    • BILLING.SUBSCRIPTION.CREATED
    • BILLING.SUBSCRIPTION.ACTIVATED
    • BILLING.SUBSCRIPTION.UPDATED
    • BILLING.SUBSCRIPTION.CANCELLED
    • BILLING.SUBSCRIPTION.SUSPENDED
    • PAYMENT.SALE.COMPLETED
  4. انسخ Webhook ID
PAYPAL_WEBHOOK_ID=your_webhook_id

الخطوة 6: التفعيل من لوحة الإدارة​

انتقل إلى الإدارة ← الإعدادات ← المدفوعات:

  • فعّل PayPal
  • الصق Client ID والسر الخاص بك
  • احفظ

🧪 اختبار المدفوعات​

وضع اختبار Stripe​

استخدم أرقام بطاقات اختبارية:

  • نجاح: 4242 4242 4242 4242
  • رفض: 4000 0000 0000 0002
  • 3D Secure: 4000 0025 0000 3155

تاريخ الانتهاء: أي تاريخ مستقبلي. CVC: أي 3 أرقام.

PayPal Sandbox​

  1. انتقل إلى developer.paypal.com ← Sandbox ← Accounts
  2. استخدم حساب المشتري في sandbox لاختبار المدفوعات

دعم العملات المتعددة​

يمكن تعيين عملات مختلفة للخطط (مثل USD وEUR وGBP). قم بإعداد قائمة العملات المدعومة في الإدارة ← الإعدادات ← المدفوعات ضمن حقل العملات المدعومة.

  • Stripe: تُمرَّر عملة الخطة تلقائيًا في جلسات Checkout، ليُحاسب العملاء بالعملة الصحيحة.
  • PayPal: تتضمن طلبات الاشتراك بيانات وصفية للعملة تتطابق مع عملة الخطة المُعدَّة.
  • تُخزَّن العملة في كل فاتورة للحفاظ على دقة السجلات.

للمزيد من التفاصيل حول إعداد العملات المدعومة، راجع إعدادات المنصة.

🔒 ملاحظات الأمان​

  • تُخزَّن مفاتيح API مشفّرة في جدول platform_settings
  • يُتحقق من توقيعات Webhook (HMAC لـ Stripe، التحقق من توقيع PayPal)
  • تُسجَّل أحداث الدفع في جدول payment_events (الإدارة ← المدفوعات)
  • تمنع آلية إلغاء التكرار المعالجة المزدوجة للـ webhooks

⏭️ الخطوات التالية​