الاشتراكات في OrcaRail: الخصم التلقائي وتعدد الشبكات

25 مارس 2026 — تدعم OrcaRail الاشتراكات المتكررة بنموذج API أولًا نفسه المستخدم في المدفوعات الفردية: تنشئ اشتراكًا، ونتتبع نحن فترات الفوترة، ويكمل الدافعون كل دورة إما بفتح رابط دفع أو عبر الخصم التلقائي، حيث يأذنون لنا بسحب العملات المستقرة في كل فترة بعد موافقة واحدة على السلسلة.

لماذا الاشتراكات في OrcaRail

الاشتراكات مخصصة لمنصات SaaS والعضويات وعقود الأتعاب الدورية وأي منتج يُفوتر على فترة ثابتة (يوم، أسبوع، شهر، سنة)، مع فترات تجريبية وحدود للدورات وقواعد إلغاء اختيارية. تستخدم مصادقة المدفوعات نفسها المستخدمة في بقية المنصة، ويمكنك التفاعل مع أحداث دورة الحياة عبر webhooks الاشتراكات.

طريقتان للتحصيل: روابط الدفع أو الخصم التلقائي

• send_payment_link (افتراضي): في كل دورة فوترة يحصل الدافع على رابط دفع (بالبريد الإلكتروني و/أو عبر التدفق المستضاف). يدفع عند فتح الرابط، وهي طريقة مألوفة في الدفع بالكريبتو ويسهل دمجها مع مسارات Relay واختيار المحفظة.
• auto_charge: يأذن الدافع مسبقًا لـ المحفظة الساخنة (hot wallet) الخاصة بـ OrcaRail بسحب مبلغ الفترة عند كل تجديد. بعد الإعداد، لا تتطلب التجديدات أن ينقر الدافع على رابط جديد كل مرة، طالما بقي الرصيد والتفويض صالحين.

أنشئ طريقة التحصيل واضبطها عبر POST /api/v1/subscriptions؛ واسرد الاشتراكات وحدّثها وأوقفها مؤقتًا وألغِها عبر إدارة الاشتراكات. الحقول الكاملة للطلب والأمثلة موجودة في تلك الأدلة.

الخصم التلقائي: كيف نتعامل معه

1. ينشئ التاجر اشتراكًا مع collection_method: "auto_charge" والحقول المعتادة amount وinterval وtoken_id وnetwork_id وبيانات الاتصال بالدافع.
2. يفتح الدافع صفحة الاشتراك أو تجربة دفع الدورة الأولى. يرى النطاق الإجمالي للموافقة (مثل مجموع الرسوم القادمة التي تطلب منه تغطيتها) ويوقّع تفويضًا على السلسلة:
   • على شبكات EVM يكون ذلك approve(spender, amount) قياسيًا من ERC-20 مع محفظتنا الساخنة بصفتها spender.
   • على سولانا تكون الخطوة المقابلة تفويض رمز SPL (delegation) بمبلغ فترة واحدة على الأقل لمحفظتنا الساخنة على سولانا.
3. يستدعي الدافع نقطة النهاية العامة POST /api/v1/subscriptions/:id/approve-auto-charge مع تجزئة (hash) معاملة الـ allowance (أو التفويض) و**payer_wallet_address** و**payer_network_id** و**payer_token_id**. لا يلزم مفتاح API الخاص بالتاجر، فالدافع يثبت نيته بتوقيعه معاملة السلسلة.
4. تتحقق OrcaRail على السلسلة من أن الـ allowance أو التفويض يغطي دورة فوترة واحدة على الأقل للمحفظة الساخنة المتوقعة قبل وسم الخصم التلقائي بأنه معتمد. قبل كل سحب يمكننا إعادة التحقق من التفويض حتى لا تُخلط مشكلات RPC العابرة بإلغاء الـ allowance.
5. في كل دورة فوترة، تحاول عملية الفوترة تنفيذ السحب (في EVM تدفق من نوع transferFrom من الدافع إلى التسوية؛ وفي سولانا يُستخدم الرصيد المفوَّض). عند النجاح تتقدم الفترة؛ وعند الفشل المتكرر (مثل عدم كفاية الرصيد أو إلغاء الموافقة) قد ينتقل الاشتراك إلى past_due ويُبلَّغ الدافع. يمكنك الاستماع إلى webhooks مثل subscription.payment_link.payment_failed أو subscription.past_due كما هو موضح في الخصم التلقائي وwebhooks.

الإلغاء والبديل: إذا ألغى الدافع التفويض على السلسلة، تفشل عمليات السحب اللاحقة. ويمكنه أيضًا استدعاء POST .../revoke-auto-charge بعد الإلغاء لنسجّل الحالة ونحوّل التحصيل إلى send_payment_link، مع إرشادات بالبريد الإلكتروني لإدارة الاشتراك والدفع عبر الروابط مجددًا. التفاصيل في الخصم التلقائي وإدارة الاشتراكات.

الأمان والوضوح: تُستخدم في السحب المحفظة التي أكملت الموافقة فقط؛ ونعرض مجاميع وأعداد دورات واضحة ليعرف الدافعون ما الذي أذنوا به. في الخطط الطويلة جدًا أو المفتوحة، فكّر في وضع سقف للمبالغ المعتمدة وتجديد الموافقة دوريًا، أو البقاء على روابط الدفع؛ راجع الخصم التلقائي.

تعدد الشبكات: كيف يتكامل مع الاشتراكات

• مرجع التاجر: يُنشأ كل اشتراك مع network_id و**token_id** يحددان كيفية تسعير الاشتراك وتسويته في API، أي الشبكة والأصل «الأساسيين» لتلك الخطة.
• سياق الدافع في الخصم التلقائي: يخزّن الخصم التلقائي payer_network_id و**payer_token_id**، وهما الشبكة والرمز اللذان ضبط عليهما الدافع الـ allowance أو التفويض فعليًا. قد يختلفان عن الحقول الأساسية للاشتراك عندما يموّل الدافع من شبكة أو أصل مدعوم آخر، بما يتسق مع طريقة تحديد عروض الأسعار وصفحة الدفع لمسارات جهة الدافع.
• تغطية متوافقة مع Relay: تبقى الشبكات والعملات المدعومة متوافقة مع Relay؛ وعندما يوسّع Relay الشبكات والرموز، تتبعه قائمتنا. لخّصنا هذا النموذج في الشبكات والعملات المدعومة: بتقنية Relay.
• وجهة العائدات: يضبط التجار عناوين السحب لكل نوع شبكة (ويمكنهم التجاوز لكل دفعة حيث يكون ذلك مدعومًا). للصورة الكاملة عن السحوبات متعددة الشبكات وتعدد العناوين لكل شبكة، راجع OrcaRail متعددة الشبكات: السحوبات والتوافق مع Relay.

الملخص

الموضوع	سلوك OrcaRail
التحصيل	send_payment_link لكل دورة، أو auto_charge مع موافقة على السلسلة
الخصم التلقائي	approve من ERC-20 على EVM أو delegate من SPL على سولانا ← API موافقة عامة ← تحقق على السلسلة ← سحب لكل دورة، مع past_due وwebhooks عند الفشل
الإلغاء	إلغاء على السلسلة + revoke-auto-charge اختياري؛ إمكانية الرجوع إلى روابط الدفع
تعدد الشبكات	network_id / token_id للاشتراك؛ موافقة الدافع تخزّن payer_network_id / payer_token_id؛ شبكات متوافقة مع Relay؛ سحوبات لكل نوع شبكة

تجمع الاشتراكات في OrcaRail بين موارد REST للاشتراكات وتفويض غير احتجازي من الدافع للخصم التلقائي ومدفوعات متعددة الشبكات، دون التخلي عن تجربة الدفع المستضافة وواجهات API التي تستخدمها أصلًا للمدفوعات الفردية.

---

تطبيق OrcaRail · التوثيق · Relay