الخصم التلقائي

الخصم التلقائي هو نموذج السحب المتكرر في OrcaRail: يمنح الدافع المحفظة الساخنة إذنًا بسحب الرموز في كل دورة فوترة. الشبكات المدعومة للخصم التلقائي هي EVM وسولانا (لا تُدعم بيتكوين لسحوبات الاشتراكات). على EVM يضبط الدافع allowance في ERC-20 وتستخدم OrcaRail transferFrom لكل فترة. وعلى سولانا يفوّض الدافع صلاحية رمز SPL؛ وتسحب OrcaRail عبر المحفظة الساخنة باستخدام ذلك التفويض.

:::note اشتراكات غير احتجازية

تنقل OrcaRail الخصم التلقائي إلى نموذج غير احتجازي بالكامل: ينتقل الـ spender في approve من محفظة ساخنة تملكها OrcaRail إلى عقد SubscriptionHub عام (EVM) أو برنامج Anchor باسم subscription (سولانا). يبقى تدفق الدافع في هذه الصفحة (الموافقة مرة واحدة والإلغاء في أي وقت) كما هو؛ ولا يتغير إلا عنوان الـ spender. راجع النظرة العامة غير الاحتجازية والمرحلة 2: اشتراكات بسحب الـ allowance.

:::

للدافعين: كيف توافق وكيف تلغي

هذا القسم موجّه إلى من يدفعون الاشتراك (العملاء)، لا إلى المطورين الذين يدمجون API.

على ماذا توافق

مع الخصم التلقائي توقّع مرة واحدة في محفظتك لتسمح لـ OrcaRail بسحب مبلغ الاشتراك في كل فترة فوترة (مثلًا كل شهر)، حتى الحد الذي وافقت عليه. لا تحتاج إلى فتح رابط دفع في كل مرة، طالما بقي الـ allowance أو التفويض صالحًا ولديك ما يكفي من الرمز في محفظتك.

كيف توافق على الخصم التلقائي

1. افتح الرابط الذي أرسله إليك النشاط التجاري (بريد أو موقع أو تطبيق). يُفترض أن ينقلك إلى تجربة الدفع أو الاشتراك المستضافة لدى OrcaRail.
2. اربط محفظتك على الشبكة الصحيحة واختر الرمز المعروض (مثل USDC).
3. اقرأ الملخص: السعر لكل فترة، وعدد مرات الخصم، وأي إجمالي أو عدد دورات تغطيه الموافقة.
4. عند النقر لتفعيل الخصم التلقائي، تطلب منك محفظتك الموافقة على إذن الرمز. أكّد فقط إذا كنت موافقًا على المبالغ وعلى النشاط التجاري.
5. بعد تأكيد المعاملة على السلسلة، سترى رسالة نجاح. ثم تسجّل OrcaRail الموافقة؛ وتُخصم الفترات اللاحقة تلقائيًا حتى تنفد الموافقة، أو تفشل (مثل انخفاض الرصيد)، أو تلغيها.

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

كيف تلغي الخصم التلقائي (إيقاف السحوبات التلقائية)

1. ألغِ على السلسلة حتى لا يتمكن الـ spender من سحب رموزك:
   • EVM: أرسل معاملة تزيل الـ allowance، وعادةً تكون approve(spender, 0) على عقد الرمز لعنوان الـ spender الخاص بـ OrcaRail (قد توفر أدوات «موافقات الرموز» أو الإلغاء في محفظتك ذلك).
   • سولانا: ألغِ تفويض رمز SPL الذي منحته لذلك الاشتراك.
2. أكمل تدفق التاجر إن وُجد (مثل «إدارة الاشتراك» ← إيقاف الخصم التلقائي). يخبر ذلك OrcaRail بتحويلك إلى روابط دفع في كل فترة بدلًا من السحب، وقد تتلقى بريدًا بالخطوات التالية.
3. إذا ألغيت على السلسلة فقط ولم تُبلغ OrcaRail أبدًا، فقد يفشل الخصم التلقائي التالي ويصبح الاشتراك متأخرًا حتى تدفع رابطًا أو تصلح الموافقة.

يستخدم التجار والتطبيقات المخصصة إلغاء الخصم التلقائي (API) بعد الإلغاء على السلسلة.

كيف يعمل

1. ينشئ التاجر اشتراكًا مع collection_method: "auto_charge".
2. يفتح الدافع رابط الاشتراك أو رابط دفع الدورة الأولى (أو يختار الخصم التلقائي عبر تعيين طريقة التحصيل عند الاقتضاء).
3. يكمل الدافع الموافقة على السلسلة: approve(spender, amount) على EVM لعنوان الـ spender الخاص بـ OrcaRail، أو التفويض المكافئ في SPL على سولانا. استخدم approval_spender_address في كائن auto_charge للاشتراك (إن وُجد) بوصفه الـ spender/المفوَّض الذي يجب أن توافق له المحفظة.
4. يرسل الدافع الموافقة إلى OrcaRail: POST /api/v1/subscriptions/:id/approve-auto-charge مع allowance_tx_hash وpayer_wallet_address وpayer_network_id وpayer_token_id، واختياريًا approved_amount / approved_iterations.
5. تسجّل OrcaRail الـ allowance وتعلّم auto_charge بأنه معتمد. في كل دورة فوترة تستخدم مهمة الفوترة المحفظة الساخنة لسحب مبلغ الفترة. عند النجاح تُعلَّم الدورة مدفوعة وتتقدم فترة الفوترة؛ وعند الفشل قد ينتقل الاشتراك إلى past_due ويُبلَّغ الدافع.

الموافقة على الخصم التلقائي (الدافع)

POST /api/v1/subscriptions/:id/approve-auto-charge

نقطة النهاية هذه عامة (موجهة للدافع). لا مفتاح API للتاجر؛ إذ يثبت الدافع نيته بتوقيعه معاملة الموافقة على السلسلة.

جسم الطلب

المعامل	النوع	مطلوب	الوصف
payer_wallet_address	string	نعم	عنوان محفظة الدافع (EVM أو سولانا، حسب الشبكة)
payer_network_id	string (UUID)	نعم	معرّف الشبكة التي ضُبط عليها الـ allowance أو التفويض
payer_token_id	string (UUID)	نعم	معرّف الرمز (مثل USDC)
allowance_tx_hash	string	نعم	تجزئة معاملة الموافقة (approve على EVM أو إعداد SPL على سولانا حسب الحالة)
approved_amount	string	لا	إجمالي المبلغ المعتمد (مثل "120.00" لاثني عشر خصمًا شهريًا)
approved_iterations	integer	لا	عدد دورات الفوترة التي يغطيها ذلك الإجمالي (مثل 12). عند ضبط approved_amount وapproved_iterations معًا، يمكن لـ OrcaRail استنتاج مبلغ السحب لكل فترة.

التدفق في تطبيق الدفع

1. اعرض ملخص الاشتراك: الوصف، والمبلغ لكل فترة، والفترة، وإجمالي الدورات، والمبلغ الإجمالي المطلوب اعتماده.
2. اقرأ approval_spender_address من auto_charge الخاص بالاشتراك (أو حمولة الاشتراك) لتوافق المحفظة للـ spender/المفوَّض الصحيح.
3. يؤدي «الموافقة» إلى توقيع المحفظة للموافقة المناسبة للشبكة (مثل wagmi/viem على EVM).
4. عند التأكيد، استدعِ POST .../approve-auto-charge مع تجزئة المعاملة وبيانات الدافع/الشبكة/الرمز (واختياريًا approved_amount / approved_iterations).
5. عند النجاح اعرض: «تمت الموافقة على الخصم التلقائي. سيُخصم منك [المبلغ] [الفترة] تلقائيًا.»

إلغاء الخصم التلقائي (الدافع)

بعد الإلغاء على السلسلة (EVM: approve(spender, 0)؛ سولانا: إلغاء تفويض SPL)، يمكن للدافع تأكيد ذلك لـ OrcaRail:

POST /api/v1/subscriptions/:id/revoke-auto-charge

نقطة النهاية هذه عامة (موجهة للدافع)، مثل الموافقة.

جسم الطلب

المعامل	النوع	مطلوب	الوصف
payer_wallet_address	string	نعم	المحفظة التي كانت تملك الـ allowance أو التفويض
revocation_tx_hash	string	نعم	تجزئة معاملة الإلغاء على السلسلة

عند النجاح، تحوّل OrcaRail الاشتراك إلى send_payment_link وترسل إلى الدافع بريدًا بروابط لإدارة الاشتراكات وفتح أحدث صفحة دفع.

تعيين طريقة التحصيل (الدافع)

يمكن للدافعين اختيار طريقة الدفع (رابط دفع لكل دورة أو خصم تلقائي) من التدفق المستضاف:

POST /api/v1/subscriptions/:id/set-collection-method

عامة (موجهة للدافع). لا مفتاح API للتاجر.

جسم الطلب

المعامل	النوع	مطلوب	الوصف
collection_method	string	نعم	send_payment_link أو auto_charge
payer_wallet_id	string (UUID)	مع auto_charge	معرّف محفظة الدافع الموثّقة المستخدمة للسحب
payer_network_id	string (UUID)	لا	الشبكة التي يختارها الدافع للخصم التلقائي؛ تُستخدم شبكة الاشتراك إن حُذف
payer_token_id	string (UUID)	لا	الرمز الذي يختاره الدافع للخصم التلقائي؛ يُستخدم رمز الاشتراك إن حُذف

يعيد كائن الاشتراك كاملًا (بالشكل نفسه في الاسترجاع).

كائن auto_charge في الاشتراك

عندما تكون collection_method هي auto_charge، تتضمن استجابة الاشتراك:

{
  "auto_charge": {
    "payer_wallet_address": "0x...",
    "payer_network_id": "...",
    "payer_token_id": "...",
    "allowance_tx_hash": "0x...",
    "approved_amount": "120.00",
    "approved_iterations": 12,
    "approval_spender_address": "0x...",
    "status": "approved"
  }
}

• approval_spender_address — العنوان (EVM) أو المعرّف المكافئ الذي يجب على الدافع الموافقة له كـ spender/مفوَّض للسحب على تلك الشبكة.
• approved_iterations — عند ضبطه مع approved_amount، يحدد عدد الدورات التي تغطيها تلك الموافقة المجمّعة.

يمكن أن تكون status: pending أو approved أو revoked أو failed. إذا ألغى الدافع على السلسلة فقد ترى revoked؛ وإذا فشل السحب مرارًا، failed أو اشتراكًا بحالة past_due.

معالجة الفشل

• فشل السحب (مثل عدم كفاية الرصيد أو إلغاء الـ allowance/التفويض): قد ينتقل الاشتراك إلى past_due ويتلقى الدافع بريدًا (مثل إشعار فشل الخصم التلقائي). يمكنك الاستماع إلى webhooks subscription.payment_link.payment_failed أو subscription.past_due.
• إلغاء الدافع على السلسلة دون استدعاء API: ستفشل السحوبات اللاحقة؛ وقد يصبح الاشتراك past_due حتى تطلب من الدافع إعادة الموافقة أو تغيير طريقة التحصيل.
• تأكيد الدافع للإلغاء عبر API (إلغاء الخصم التلقائي): تحوّل OrcaRail الاشتراك إلى send_payment_link وتراسل الدافع.

الأمان وتجربة الاستخدام

• لا يمكن الخصم إلا من المحفظة التي أكملت الموافقة؛ ويتحقق الخادم الخلفي من الـ allowance أو التفويض على السلسلة.
• اعرض بوضوح إجمالي مبلغ الموافقة وعدد الخصومات ليعرف الدافع ما الذي يوافق عليه.
• في الاشتراكات الطويلة جدًا أو غير المحدودة، فكّر في وضع سقف للمبلغ المعتمد (مثل 12 شهرًا) وطلب إعادة الموافقة لاحقًا، أو استخدم send_payment_link بدلًا من ذلك.

الخطوات التالية

• إنشاء اشتراك — استخدم collection_method: "auto_charge"
• webhooks الاشتراكات — subscription.payment_link.payment_failed وsubscription.past_due
• إدارة الاشتراكات — حدّث أو ألغِ إذا انتقل الدافع إلى روابط الدفع
• الاشتراكات (SDK) — حِزم SDK للتاجر؛ وتستخدم عمليات الدافع (الموافقة/الإلغاء/تعيين طريقة التحصيل) HTTP من صفحة الدفع المستضافة