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

نظرة عامة

كل دفع في tikento يمر بتسلسل محدد من الحالات. تحدث الانتقالات بين الحالات تلقائياً بناءً على إشعارات webhook من بوابة الدفع. يرى المنظم الحالة الحالية في قسم المشاركون وفي تفاصيل التسجيل.

حالات الدفع

مخطط الانتقالات

         إنشاء الدفع
               │
               ▼
           ┌────────┐
           │pending │
           └───┬────┘
               │
       ┌───────┼───────┐
       ▼       ▼       ▼
   ┌──────┐ ┌────┐ ┌───────┐
   │failed│ │paid│ │expired│
   └──────┘ └─┬──┘ └───────┘
              │
       ┌──────┴──────┐
       ▼             ▼
┌──────────┐  ┌──────────────────┐
│refunded  │  │partially_refunded│
└──────────┘  └──────────────────┘

الانتقالات لا رجعة فيها: paid لا يمكن أن يعود إلى pending، وrefunded لا يمكن أن يعود إلى paid.

الحجز (Reservation)

قبل إنشاء الدفع ينشئ tikento حجزاً — احتجاز مؤقت للتذكرة حتى لا تذهب لمشارك آخر أثناء دفع الأول.

كيف يعمل الحجز

1. المشارك يضغط «ادفع» — ينشئ tikento حجزاً بمدة 15 دقيقة.
2. تُخصم الكمية المحجوزة من التذاكر المتاحة.
3. يُحال المشارك إلى صفحة دفع البوابة.
4. إذا نجح الدفع — يتحول الحجز إلى تسجيل مؤكد.
5. إذا انتهت المدة — يُلغى الحجز تلقائياً وتعود التذكرة متاحة.

يمنع الحجز حالة قيام شخصين بدفع آخر تذكرة في نفس الوقت.

معالجة Webhook

يعرف tikento نتيجة الدفع عبر webhook — طلب HTTP من بوابة الدفع إلى خوادم tikento.

التسلسل

1. البوابة (YooKassa، Tochka، Telegram) ترسل طلب POST إلى عنوان webhook الخاص بـ tikento.
2. يتحقق tikento من توقيع الطلب (كل بوابة تستخدم آلية توقيع خاصة).
3. يُحدّث الدفع حالته في قاعدة البيانات.
4. إذا كانت الحالة paid — يُؤكد تسجيل المشارك ويُرسل بريد بالتذكرة.
5. إذا كانت الحالة failed أو expired — يُلغى الحجز.

إعادة التسليم

إذا لم يتمكن tikento من معالجة webhook (مثلاً أعاد 5xx)، تعيد البوابة الطلب:

• YooKassa: حتى 10 محاولات بتأخير متصاعد
• Tochka: حتى 5 محاولات بفاصل 5 دقائق

بفضل مفاتيح التكرارية، إعادة معالجة نفس webhook آمنة ولا تنشئ نسخاً مكررة.

حماية التكرارية (Idempotency)

كل عملية دفع في tikento محمية بمفتاح تكرارية — معرف فريد يضمن تنفيذ العملية مرة واحدة بالضبط.

لماذا هذا ضروري

• المشارك ضغط «ادفع» مرتين عن طريق الخطأ — يُنشأ دفع واحد فقط
• وصل webhook متكرر بسبب timeout — تُحدّث الحالة مرة واحدة
• انقطاع الشبكة قطع الطلب والعميل أرسل إعادة — لا تُخصم الأموال مرتين

كيف يعمل

1. عند إنشاء الدفع ينشئ tikento مفتاح Idempotency-Key (UUIDv7).
2. يُرسل المفتاح في ترويسة الطلب إلى البوابة.
3. إذا استلمت البوابة طلباً متكرراً بنفس المفتاح، تعيد نتيجة العملية الأولى.
4. يحفظ tikento المفتاح في Redis بمدة TTL 24 ساعة.

علاقة حالات الدفع والتسجيل

تؤثر حالة الدفع مباشرة على حالة تسجيل المشارك:

عند تفعيل الإشراف قد تكون هناك مرحلة تحقق وسيطة من المنظم بين الدفع والحالة النهائية registered.

عرض سجل المدفوعات

جميع المدفوعات وحالاتها متاحة في قسم المشاركون في فعاليتك. لكل سجل يُعرض:

• الحالة الحالية للدفع
• طريقة الدفع (بطاقة، SBP، Stars)
• المبلغ والعملة
• تاريخ ووقت الإنشاء / الدفع / الاسترداد
• مفتاح التكرارية (للتشخيص)
• سجل الانتقالات بين الحالات

لتصدير بيانات المدفوعات — تصدير المدفوعات والتقارير.