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

المقدمة

قم بإنشاء جلسات دفع وتتبع المعاملات من خلال البوابات المكونة في مشروعك.

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

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

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

يقوم SDK بجلب حسابات الدفع وإنشاء جلسات الدفع؛ يتم تكوين الحسابات والحالات في لوحة التحكم.

🚀 البدء السريع​

قم بتهيئة الموديل من defineOneEntry:


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

قم بإنشاء جلسة دفع لطلب وقم بإعادة توجيه العميل إلى البوابة (يتطلب مصادقة):

// Create a Stripe Checkout session for order #179.
const session = await Payments.createSession(179, "session");

console.log(session.id, session.status, session.paymentUrl);

// Send the customer to the gateway checkout page.
window.location.href = session.paymentUrl;

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

ما هي جلسة الدفع؟​

جلسة الدفع (ISessionEntity) هي سجل يحتوي على:

  • type — 'session' أو 'intent'
  • status — سلسلة حالة الدفع الحرة (مثل "waiting"، "completed")
  • paymentAccountId — الحساب المكون المستخدم
  • orderId — الطلب المرتبط
  • paymentUrl — رابط الخروج من البوابة (أو null)
  • createdDate / updatedDate — الطوابع الزمنية

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

النوعالوصف
sessionينشئ صفحة دفع Stripe مع رابط دفع إعادة توجيه
intentينشئ نية دفع لمعالجة الدفع المباشر/المخصص

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

يبلغ حقل type في الحساب عن مزود الدفع الذي يدعمه:

typeمتى تستخدمالتكوين المطلوب
stripeربط نظام الدفع Stripeحساب Stripe، روابط
yookassaربط YooKassaمعرف المتجر، مفتاح سري، روابط
midtransربط Midtransبيانات اعتماد المزود، روابط
xenditربط Xenditبيانات اعتماد المزود، روابط
customأنظمة دفع بديلة أو مدفوعات نقديةتكوين مخصص

تعيش معلمات الاتصال الخاصة بالمزود في كائن settings الخاص بالحساب - انظر getAccountById().

حالات الدفع​

حالة الجلسة status هي سلسلة حرة تم تعيينها من نتيجة البوابة، وليست تعداد ثابت. القيم الشائعة:

الحالةالمعنى
waitingتم إنشاء الجلسة، في انتظار الدفع
completedتم تأكيد الدفع من قبل البوابة

لا يمكنك إنشاء أو تعديل حالات الدفع في لوحة التحكم. ومع ذلك، يمكنك ربط حالات الدفع بحالات تخزين الطلبات بحيث يتم تحديث حالة الطلب تلقائيًا عند تغيير حالة الدفع.

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

1. Configure a payment account in the admin panel (Stripe or custom)
   ↓
2. Customer places an order (Orders module)
   ↓
3. Create a payment session  →  Payments.createSession(orderId, type)
   ↓
4. Redirect the customer to session.paymentUrl
   ↓
5. Customer completes payment at the gateway
   ↓
6. Session status reflects the gateway result (e.g. "waiting" → "completed")
   ↓
7. Mapped order status is updated automatically

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

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

لا يمكنك إنشاء حسابات دفع عبر SDK — قم بإنشائها وتحريرها في لوحة تحكم OneEntry (المدفوعات > الحسابات)، مع توفير الاسم، النوع (Stripe أو مخصص)، والتوكن. بالنسبة لحسابات Stripe، يجب عليك أيضًا تكوين رابط النجاح، رابط الإلغاء، ومدة الجلسة. SDK مخصص لـ جلب الحسابات وإنشاء الجلسات.

مزامنة الحالة​

تتم مزامنة حالات الدفع مع حالات تخزين الطلبات في لوحة التحكم (المدفوعات > الحالات → اختر تخزين الطلب → ربط الحالات → حفظ). هذا يمكّن من تحديث حالات الطلب تلقائيًا عند تغيير حالة الدفع.

لا تخزن بيانات بطاقة الائتمان الخام​

لا تقم أبدًا بتخزين أرقام بطاقات الائتمان، CVV، أو تواريخ انتهاء الصلاحية الكاملة. يتم التعامل مع الدفع من قبل البوابة (Stripe)، مما يبقيك خارج نطاق تخزين بيانات البطاقة؛ لا تخزن OneEntry أبدًا تفاصيل البطاقة الخام.

عمليات الاسترداد تعيش في موديل الطلبات​

لا يحتوي موديل المدفوعات على طرق استرداد. يتم التعامل مع الاستردادات من قبل موديل الطلبات عبر createRefundRequest()، cancelRefundRequest()، وgetRefunds().

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

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

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

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

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

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

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

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

هل يمكنني دعم حسابات دفع متعددة؟​

نعم. قم بإنشاء حسابات دفع متعددة (Stripe أو مخصص) في لوحة التحكم. يمكن لكل طلب استخدام حساب مختلف عبر paymentAccountIdentifier الخاص به.

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

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

كيف يمكنني إصدار استرداد؟​

الاستردادات ليست جزءًا من موديل المدفوعات. استخدم موديل الطلبات: createRefundRequest() لطلب استرداد، cancelRefundRequest() لإلغاء الطلب، وgetRefunds() لعرضها.

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

  • قم بالمصادقة أولاً — كل طريقة من طرق المدفوعات تتطلب مستخدمًا مخولًا (انظر AuthProvider).
  • قم بإعادة التوجيه إلى paymentUrl بعد إنشاء جلسة، وتعامل مع روابط العودة من البوابة في تطبيقك.
  • اقرأ الحالة من الجلسة، وليس من العميل — تحقق من status للجلسة (أو getSessionByOrderId()) لتأكيد الدفع.
  • قم بربط حالات الدفع بحالات الطلبات بحيث تبقى حالة الطلب متزامنة تلقائيًا.
  • اختبر باستخدام مفاتيح اختبار Stripe قبل الانتقال إلى الإنتاج.

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