بنية المدفوعات

لا تظهر طريقة الدفع إلا بعد أن يُعدّ HyoNova مزوّد الدفع الخاص بها.

HyoNova Commerce هو الطريقة التي يبيع بها HyoNova خططه للشركات: الدفع، والاشتراكات، والفواتير، والمدفوعات، والاستردادات، وأحداث المزوّدين. تشرح هذه الصفحة تصميمه للمطورين وفرق تقنية المعلومات الذين يحتاجون إلى فهم سلوك المدفوعات. وليس واجهة برمجية عامة: تستخدمه الشركات عبر المنتج، ومشغّلو HyoNova عبر مركز التحكم.

نظامان لا يتشاركان شيئاً#

يحتفظ النظامان ببيانات وبيانات اعتماد ودفاتر منفصلة. ولا تُحمِّل شيفرة مالية الشركة أي مزوّد دفع للمنصة أبداً، وسجلات كل شركة معزولة عن غيرها بأمان مستوى الصفوف في قاعدة البيانات.

نواة واحدة فوق محوّلات المزوّدين#

Product (company owners)          Control Center (HyoNova operators)
            \                          /
             v                        v
   ┌──────────── Commerce core ────────────┐
   │ catalogue · billing profiles ·        │
   │ checkout · orders · subscriptions ·   │
   │ seats · invoices · payments ·         │
   │ refunds · credits · discounts ·       │
   │ dunning · provider events ·           │
   │ reconciliation · settlements ·        │
   │ revenue metrics                       │
   └──────────────────┬────────────────────┘
                      │ asks for capabilities, never provider names
   ┌──────────────────▼────────────────────┐
   │ Provider adapters                     │
   │ FastSpring · Triple-A ·               │
   │ Bank transfer (native) · Stripe       │
   └───────────────────────────────────────┘

النواة التجارية هي مصدر الحقيقة الوحيد. والمزوّد محوّل يصفه manifest: قدراته (مثل checkout وsubscriptions وproration وrefunds وpartial_refunds وcustomer_portal وmerchant_of_record وbank_transfer وmanual_confirmation وreconciliation وhealth_check)، وطرق الدفع التي يقبلها (card وcrypto وbank_transfer)، وكيف تُحصَّل التجديدات (provider أو invoice_per_cycle)، وحقول الإعدادات والأسرار، والـWebhook، ومضيفات الـAPI الوحيدة المسموح له باستدعائها. تسأل النواة «هل يستطيع هذا المزوّد الاسترداد الجزئي؟» — ولا تسأل أبداً «هل هذا FastSpring؟». وطلب قدرة لا يعلنها المزوّد يعيد الخطأ المصنّف CAPABILITY_UNSUPPORTED.

التوجيه والبديل الآمن#

تُوجَّه كل طريقة دفع إلى نسخة مزوّد واحدة. ويكون المسار صالحاً فقط حين تكون نسخته مفعّلة ومكتملة الإعداد وغير متدهورة. والنسخ المفعّلة بدور secondary مرشّحة بديلة، لكن HyoNova لا ينتقل إلى البديل إلا حين يتعذر الوصول إلى المزوّد الموجَّه أثناء إنشاء عملية الدفع، وفقط إلى مزوّد يحصّل التجديدات بالطريقة نفسها. وبعد وجود عملية دفع لدى مزوّد لا يتغير المزوّد أبداً — فلا يمكن الخصم من المشتري مرتين.

الدفع#

1. يختار المالك سعراً وطريقة. ويتحقق الخادم من الشركة والسعر والخطة والعملة والمقاعد وملف الفوترة والمسار، ويرفض عملية دفع مفتوحة ثانية.
2. يكتب HyoNova سجل عملية الدفع أولاً (ويصدر فاتورة HyoNova في التحويل البنكي والعملات الرقمية)، ثم يطلب من المزوّد صفحة دفع مستضافة، حاملاً معرّف عملية الدفع في HyoNova ضمن بيانات المزوّد الوصفية.
3. يدفع المشتري في صفحة المزوّد (البطاقة، العملات الرقمية) أو بالتحويل البنكي.
4. صفحة النجاح بعد الدفع لتجربة المستخدم فقط. لا يتفعّل شيء لأن المتصفح عاد. ولا يتغير الاشتراك إلا بـWebhook موقّع ومتحقق منه من المزوّد، أو بتأكيد مشغّل لتحويل بنكي، أو بالمطابقة — وكلها عبر مسار الأحداث نفسه. راجع Webhooks المدفوعات.

الاشتراكات#

الحالات: trial وactive وpast_due وcanceled وpaused، مع علامة cancel_at_period_end.

• الإلغاء في نهاية الفترة يُبقي الوصول حتى تنتهي الفترة؛ وإيقاف المزوّد النهائي (أو HyoNova في الاشتراكات المحصّلة بالفواتير) يُنهيه.
• تأخر السداد يبدأ فترة سماح؛ وتعمل الوحدات المدفوعة فقط ما دام تاريخ نهاية السماح محدداً وفي المستقبل، ثم تتوقف. ولا تُحذف البيانات أبداً وتبقى الفوترة متاحة.
• انتهاء الفترة التجريبية لا يُطبَّق إلا في مرحلة المنتج العامة؛ وخلال الوصول المبكر تستمر الفترات التجريبية في العمل.
• تغيير الخطة: ترقية الاشتراك الذي يحصّله المزوّد تسري فوراً مع احتساب المزوّد النسبي؛ أما التخفيض وتغيير الفترة وكل تغيير لاشتراك محصّل بالفواتير فيسري في نهاية الفترة. وتبديل الخطة أثناء التجربة مجاني. ولا يخترع HyoNova أي مبلغ احتساب نسبي.
• المقاعد: تعريف واحد للمقعد المحتسب — الأعضاء النشطون أو المدعوون أو المعلّقون الذين يحملون مقعداً مخصصاً. ولا يُحسب الضيوف ولا المُزالون ولا الموقوفون أبداً.

الفواتير#

• فواتير المزوّد (FastSpring بصفته البائع المسجَّل) نسخ مطابقة: المبالغ والحالة ورابط مستند المزوّد القانوني.
• فواتير HyoNova (التحويل البنكي والعملات الرقمية) تحصل على رقم ذري متسلسل دون فجوات PREFIX-YYYY-000123، ومرجع دفع فريد HN-XXXX-XXXX، ونسخ مجمّدة من بيانات العميل والمُصدِر. ولا تتغير هويتها ومبالغها بعد الإصدار. والضريبة صفر ما لم توجد قاعدة ضريبية؛ فلا يملك HyoNova محرك ضرائب خاصاً به.

الأمان#

• بيانات الاعتماد في مخزن الأسرار فقط (AWS Secrets Manager في الإنتاج)، مدخل واحد لكل نسخة مزوّد. وتحتفظ قاعدة البيانات بمرجع فقط. ولا تعيد أي واجهة برمجية بيانات الاعتماد ولا تُسجَّل ولا تُدقَّق.
• العزل: كل جدول تجاري تملكه شركة محمي بأمان مستوى الصفوف.
• الصلاحيات: billing.read وbilling.manage للشركات؛ ويحتاج المشغّلون أيضاً providers.manage أو plans.manage وإعادة تحقق حديثة وسبباً لكل تغيير.
• حماية CSRF لا تُتجاوز إلا لمسار الـWebhook الموقّع.
• الاستدعاءات الخارجية تذهب فقط إلى المضيفات التي يسمح بها كل مزوّد، عبر HTTPS، مع مهل زمنية وإعادة محاولات محدودة للاستدعاءات الآمنة التكرار.
• نطاق PCI يقتصر على صفحات الدفع المستضافة. ولا يخزّن HyoNova إلا نوع البطاقة وآخر أربعة أرقام وتاريخ الانتهاء.

المراقبة#

تُصدر النواة عدّادات وسطور سجل منظّمة دون أسرار أو بيانات شخصية: checkout_created، checkout_provider_error، checkout_completed، checkout_expired، payment_succeeded، payment_failed، webhook_received، webhook_invalid، webhook_duplicate، webhook_processed، subscription_changed، invoice_paid، refund_succeeded، reconciliation_mismatch، reconciliation_error، provider_api_error، provider_latency، provider_configured، provider_test.

اقرأ بعد ذلك#