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

مقدمة

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

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

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

📖 شرح بسيط​

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

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

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

المشاكل:

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

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

الفوائد:

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

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

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

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

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

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

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

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

1. إنشاء حساب دفع في لوحة الإدارة
   (تكوين حساب Stripe أو مخصص)
   ↓
2. يقوم العميل بعمل طلب
   (تم إنشاء الطلب في موديل الطلبات)
   ↓
3. إنشاء جلسة دفع
   (Payments.createSession(orderId, type))
   ↓
4. يتم إعادة توجيه العميل إلى عنوان الدفع
   (صفحة دفع Stripe أو صفحة دفع مخصصة)
   ↓
5. يكمل العميل الدفع
   (تمت معالجة الدفع بواسطة البوابة)
   ↓
6. تحديث حالة الدفع
   (انتظار → معلقة → مدفوعة/ملغاة/منتهية)
   ↓
7. استلام الإشعار
   ↓
8. مزامنة حالة الطلب
   (حالة الدفع مرتبطة بحالة الطلب)

حالات الدفع​

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

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

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

طرق الدفع​

الطريقةالوصفدعم البوابة
بطاقة ائتمان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 → المدفوعات → الحسابات → إنشاء حساب → ملء النموذج → انقر على "إضافة"

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

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

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

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

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

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

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

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

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

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

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

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

لوحة إدارة OneEntry → المدفوعات → الحالات → اختر تخزين الطلب → ربط الحالات → حفظ

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

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

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

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

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

لماذا؟

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

مسؤوليتك:

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

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

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

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

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

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

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

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

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

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

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

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

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

تقوم الجلسة بإنشاء صفحة دفع Stripe Checkout مع عنوان 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"
  }
);

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