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

مقدمة

🎯 ماذا يفعل هذا الموديل؟​

يتيح لك موديل Payments إدارة معالجة المدفوعات والمعاملات لمتجر التجارة الإلكترونية الخاص بك. العمل مع المدفوعات والمعاملات هو جزء مهم من أي مشروع تجارة إلكترونية. يتكامل مع بوابات الدفع مثل Stripe للتعامل مع جلسات الدفع، تتبع المعاملات، وإدارة حالة الدفع.

فكر في الأمر كنظام إدارة المدفوعات الخاص بك - تقوم بتكوين حسابات الدفع في لوحة إدارة OneEntry (المدفوعات > الحسابات)، وإنشاء حسابات متعددة لأنواع مختلفة من المدفوعات مثل ربط نظام دفع أو إضافة مدفوعات نقدية، ويتولى هذا الموديل إنشاء جلسات الدفع، تتبع الحالة، وإدارة المعاملات.

📖 شرح بسيط​

تحتاج كل تطبيق تجارة إلكترونية إلى معالجة مدفوعات آمنة:

  • 💳 قبول المدفوعات - بطاقات الائتمان، بطاقات الخصم، المحافظ الرقمية
  • 🔒 معالجة آمنة - معالجة المدفوعات وفقًا لمعايير PCI
  • 🔄 حالة الدفع - تتبع المدفوعات المعلقة، المكتملة، الفاشلة، المستردة
  • 💰 استرداد الأموال - معالجة الاستردادات الكاملة أو الجزئية
  • 📊 تاريخ المدفوعات - عرض جميع المعاملات
  • 🔗 تكامل البوابة - Stripe، PayPal، بوابات مخصصة

المشكلة مع معالجة المدفوعات اليدوية:

المشاكل:

  • 🔒 مخاطر الأمان - تخزين بيانات بطاقات حساسة
  • 📋 امتثال PCI - يتطلب شهادة باهظة الثمن
  • 💸 عدم تتبع الاستردادات - إدارة استرداد يدوية
  • 🔄 عدم وجود تاريخ للمدفوعات - صعوبة تتبع المعاملات

حل المدفوعات:

الفوائد:

  • 🔒 امتثال PCI - مدفوعات مؤمنة باستخدام الرموز
  • 📊 تتبع المدفوعات - تاريخ معاملات كامل
  • 🔄 استردادات آلية - معالجة استرداد سهلة
  • 💸 بوابات متعددة - Stripe، PayPal، مخصص

✨ المفاهيم الأساسية​

ما هي المدفوعات؟​

المدفوعات هي سجل معاملة مالية يحتوي على:

  • طريقة الدفع - بطاقة، PayPal، تحويل بنكي
  • المبلغ - مبلغ المعاملة والعملة
  • مرجع الطلب - معرف الطلب المرتبط
  • حالة الدفع - معلقة، مكتملة، فاشلة، مستردة
  • تفاصيل البوابة - معرف معاملة Stripe، مرجع PayPal
  • معلومات العميل - تفاصيل الفوترة
  • الطوابع الزمنية - تواريخ الإنشاء، المعالجة، الاكتمال

أنواع الحسابات المتاحة​

النوعمتى تستخدمهالتكوين المطلوب
Stripeربط نظام دفع Stripe بمشروعكحساب Stripe، عناوين URL
مخصصأنظمة دفع بديلة أو مدفوعات نقديةتكوين مخصص

دورة حياة الدفع​

1. Create payment account in admin panel
   (Configure Stripe or custom account)
   ↓
2. Customer places order
   (Order created in Orders module)
   ↓
3. Create payment session
   (Payments.createSession(orderId, type))
   ↓
4. Customer redirected to payment URL
   (Stripe checkout or custom payment page)
   ↓
5. Customer completes payment
   (Payment processed by gateway)
   ↓
6. Payment status updated
   (waiting → pending → paid/canceled/expired)
   ↓
7. Notification received
   ↓
8. Order status synchronized
   (Payment status linked to order status)

حالات الدفع​

يتضمن النظام أربع حالات دفع مسبقة تشير إلى حالة المعاملة التي يتم معالجتها:

الحالةالمعنىمتى تحدث
معلقةالحالة الأولية للمعاملةتم إنشاء جلسة الدفع للتو
مدفوعةمعاملة مكتملة بنجاحتم تأكيد الدفع من قبل البوابة
ملغاةتم إلغاء المعاملةألغى العميل الدفع
منتهيةانتهت فترة صلاحية المعاملةتجاوزت مهلة الجلسة

مهم: في إعدادات الدفع، لا يمكنك إنشاء أو تعديل الحالات. ومع ذلك، يمكنك ربط هذه الحالات المدفوعة المسبقة بحالات تخزين الطلبات لتمكين المزامنة التلقائية بين أنظمة الدفع والطلبات.

طرق الدفع​

الطريقةالوصفدعم البوابة
بطاقة ائتمانVisa، Mastercard، AmexStripe، PayPal
بطاقة خصمبطاقات الخصمStripe، PayPal
PayPalحساب PayPalPayPal
تحويل بنكيتحويل مصرفي، ACHمخصص
Apple Payمحفظة Apple PayStripe
Google Payمحفظة Google PayStripe
الدفع عند التسليمالدفع عند التسليمN/A

لماذا تستخدم موديل المدفوعات؟​

الفائدةالوصف
امتثال PCIمعالجة مدفوعات مؤمنة باستخدام الرموز
تكامل البوابةStripe، PayPal مدمجة
تتبع المدفوعاتتاريخ معاملات كامل
إدارة الاسترداداستردادات كاملة/جزئية سهلة
حماية من الاحتيالكشف احتيال مدمج
3D Secureدعم مصادقة SCA
عملات متعددةدعم لعملات متعددة

📋 ما تحتاج لمعرفته​

تُنشأ حسابات الدفع في لوحة الإدارة​

لا يمكنك إنشاء حسابات الدفع عبر SDK - يتم إنشاؤها في لوحة إدارة OneEntry:

OneEntry Admin Panel → Payments → Accounts → Create Account → Fill Form → Click "Add"

عملية الإنشاء:

  • املأ النموذج بثلاثة حقول مطلوبة:
    • الاسم - معرف سلسلة غير فريد
    • النوع - يتم اختياره من القائمة المنسدلة: "Stripe" أو "مخصص"
    • الرمز - معرف سلسلة فريد
  • انقر على "إضافة" لإنشاء الحساب

إدارة الحساب:

  • تحرير - اختر الحساب، انقر على أيقونة التحرير، عدل الاسم/النوع/الرمز/معلمات Stripe
  • إخفاء - انقر على أيقونة العين لإخفاء الحسابات من إعدادات تخزين الطلبات
  • حذف - اختر الحساب، انقر على أيقونة الحذف، أكد الإزالة

الـ SDK مخصص لـ استرجاع حسابات الدفع و إنشاء جلسات الدفع، وليس لإدارة الحسابات.

أنواع حسابات الدفع​

يتوفر نوعان من حسابات الدفع:

النوعالوصف
Stripeاختر هذا النوع لربط نظام دفع Stripe
مخصصلأنظمة الدفع البديلة أو المدفوعات النقدية

تكوين خاص بـ Stripe:

  • عنوان URL للنجاح - عنوان URL لإعادة التوجيه بعد الدفع الناجح
  • عنوان URL للإلغاء - عنوان URL لإعادة التوجيه إذا تم إلغاء الدفع
  • مدة الجلسة - مهلة الجلسة بالدقائق

مزامنة حالة الدفع​

يمكن ربط حالات الدفع بحالات تخزين الطلبات:

OneEntry Admin Panel → Payments → Statuses → Select Order Storage → Map Statuses → Save

سير عمل ربط الحالة:

  1. انتقل إلى قسم الحالات ضمن المدفوعات
  2. اختر نظام تخزين الطلبات المطلوب
  3. اربط كل حالة دفع مسبقة بقيمة حالة تخزين الطلبات المقابلة
  4. تحقق من دقة جميع الربط
  5. انقر على حفظ لتطبيق التغييرات

هذا يمكّن من تحديثات الحالة التلقائية في سجلات الطلبات عند تغيير حالات الدفع.

لا تخزن بيانات البطاقة الخام أبدًا​

حرج: لا تخزن أرقام بطاقات الائتمان، CVV، أو تواريخ انتهاء الصلاحية بالكامل.

لماذا؟

  • يتطلب الامتثال لمعايير PCI DSS معالجة آمنة
  • تخزين بيانات البطاقة يعرضك للمسؤولية
  • OneEntry لا تخزن أبدًا تفاصيل البطاقة الخام

💡 ملاحظات مهمة​

تُنشأ حسابات الدفع في لوحة الإدارة​

تذكر: الـ SDK مخصص لـ استرجاع حسابات الدفع و إنشاء الجلسات، وليس لإنشاء الحسابات.

لإنشاء/تحرير حسابات الدفع: استخدم لوحة إدارة OneEntry.

إدارة حسابات الدفع​

إنشاء الحسابات في لوحة الإدارة:

  1. انتقل إلى المدفوعات > الحسابات
  2. املأ النموذج بالاسم، النوع، والرمز
  3. بالنسبة لحسابات Stripe، قم بتكوين عنوان URL للنجاح، عنوان URL للإلغاء، ومدة الجلسة
  4. انقر على "إضافة" لإنشاء

إدارة الحسابات:

  • تحرير - تعديل الاسم، النوع، الرمز، أو معلمات خاصة بـ Stripe
  • إخفاء - انقر على أيقونة العين للإخفاء من إعداد تخزين الطلبات (لا يحذف)
  • حذف - إزالة الحسابات غير المستخدمة بالكامل

مهم: يمكن حذف الحسابات غير المستخدمة فقط.

تكوين حالة الدفع​

مهم: لا يمكنك إنشاء أو تعديل حالات الدفع في لوحة الإدارة. يحتوي النظام على أربع حالات مسبقة: معلقة، مدفوعة، ملغاة، منتهية.

سير عمل مزامنة الحالة:

  1. انتقل إلى المدفوعات > الحالات
  2. اختر نظام تخزين الطلبات
  3. اربط حالات الدفع المسبقة بحالات تخزين الطلبات
  4. انقر على حفظ لتطبيق التغييرات

هذا يمكّن من تحديثات حالة الطلب تلقائيًا عند تغيير حالات الدفع.

أنواع الجلسات​

يتوفر نوعان من الجلسات:

النوعالوصف
جلسةينشئ صفحة دفع Stripe مع رابط الدفع
نيةينشئ نية دفع لمعالجة الدفع المباشر

الأمان أولاً​

🔒 قواعد الأمان الحرجة:

  • لا تخزن بيانات البطاقة الخام أبدًا - استخدم الرموز
  • استخدم HTTPS فقط - يجب أن تكون جميع صفحات الدفع SSL
  • تحقق على الخادم - لا تثق في بيانات جانب العميل
  • سجل المعاملات - احتفظ بسجل تدقيق
  • تعامل مع المعلومات الشخصية بعناية - احمِ بيانات العملاء

الامتثال لمعايير PCI​

✅ OneEntry تتولى الامتثال لمعايير PCI نيابةً عنك:

  • معالجة مدفوعات مؤمنة باستخدام الرموز
  • تكامل آمن مع البوابة
  • لا تخزين لبيانات البطاقة الخام
  • نقل مشفر

مسؤوليتك:

  • استخدم HTTPS على صفحات الدفع
  • لا تسجل بيانات حساسة
  • اتبع أفضل ممارسات الأمان

استعلام حالة الدفع​

للمدفوعات غير المتزامنة، استعلم عن تحديثات الحالة:

قيود الاسترداد​

قواعد استرداد مهمة:

  • يمكن فقط استرداد المدفوعات المكتملة
  • يجب ألا تتجاوز الاستردادات الجزئية المبلغ الأصلي
  • بعض البوابات لديها حدود زمنية (مثل 180 يومًا)
  • الاستردادات غير متزامنة (قد تستغرق أيامًا)

📊 جدول مرجعي سريع​

الطريقةالوصفحالة الاستخدام
getAccounts()الحصول على جميع حسابات الدفعقائمة بأساليب الدفع المتاحة
getAccountById()الحصول على حساب الدفع حسب المعرفاسترجاع تفاصيل حساب محدد
createSession() 🔐إنشاء جلسة دفعتوليد رابط دفع للطلب
getSessions() 🔐الحصول على جميع جلسات الدفع (مقيدة)عرض تاريخ جلسات الدفع
getSessionById() 🔐الحصول على جلسة الدفع حسب المعرفالتحقق من حالة جلسة محددة
getSessionByOrderId() 🔐الحصول على جلسة الدفع حسب معرف الطلبالعثور على الدفع لطلب محدد

🔐 = يتطلب تفويض

❓ الأسئلة الشائعة (FAQ)​

كيف يمكنني إعداد مدفوعات Stripe؟​

قم بإنشاء حساب دفع في لوحة الإدارة مع النوع "Stripe"، ثم قم بتكوين عنوان URL للنجاح، عنوان URL للإلغاء، ومدة الجلسة. استخدم createSession() لتوليد روابط الدفع التي تعيد توجيه العملاء إلى صفحة دفع Stripe.

ما الفرق بين نوعي الدفع الجلسة والنية؟​

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

هل يمكنني دعم طرق دفع متعددة؟​

نعم! قم بإنشاء حسابات دفع متعددة (Stripe، مخصص، الدفع عند التسليم) في لوحة الإدارة. يمكن لكل طلب استخدام حساب دفع مختلف بناءً على اختيار العميل.

كيف يمكنني ربط حالات الدفع بحالات الطلب؟​

في لوحة الإدارة، انتقل إلى المدفوعات > الحالات، اختر تخزين الطلبات الخاص بك، واربط حالات الدفع الأربعة المسبقة (معلقة، مدفوعة، ملغاة، منتهية) بحالات الطلب المقابلة. هذا يمكّن من المزامنة التلقائية.

ماذا يحدث إذا انتهت جلسة الدفع؟​

تحتوي جلسات الدفع على مدة قابلة للتكوين (تحدد في إعدادات الحساب). إذا لم يكمل العميل الدفع خلال هذا الوقت، تتغير حالة الجلسة إلى "منتهية" وسيتعين عليهم إنشاء جلسة دفع جديدة.

🎓 أفضل الممارسات​

  • استخدم الرموز - قم دائمًا بتشفير البطاقات باستخدام Stripe.js
  • تحقق من المبالغ - تحقق من الإجماليات على الخادم، وليس فقط على العميل
  • تعامل مع الأخطاء بشكل جيد - رسائل خطأ واضحة للمستخدمين
  • سجل المعاملات - احتفظ بسجل تدقيق لجميع المدفوعات
  • استخدم webhooks - استمع لتحديثات حالة الدفع
  • اختبر باستخدام مفاتيح الاختبار - استخدم وضع اختبار Stripe قبل الإنتاج
  • تعامل مع 3D Secure - نفذ تدفق مصادقة SCA
  • احتفظ بمعرفات المعاملات - احتفظ بمراجع البوابة للنزاعات

مزيد من المعلومات حول المدفوعات في لوحة إدارة OneEntry: https://doc.oneentry.cloudhttps://doc.oneentry.cloud/docs/category/payments

تعريف موديل المدفوعات​

يدير موديل Payments معالجة المدفوعات والمعاملات. يوفر أدوات للعمل مع حسابات الدفع، إنشاء جلسات الدفع، وتتبع حالات الدفع.


const { Payments } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

🔗 الوثائق ذات الصلة​