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

نظرة عامة على الاشتراكات

تتيح لك اشتراكات OrcaRail تحصيل مدفوعات كريبتو متكررة من الدافعين. تستخدم REST API مورد اشتراك تقليديًا بحقول snake_case. وتضيف OrcaRail ميزة auto_charge، حيث تسحب المحفظة الساخنة لـ OrcaRail مبلغ كل فترة من محفظة الدافع على EVM (allowance في ERC-20 وtransferFrom) أو سولانا (تفويض رمز SPL). لا يعمل الخصم التلقائي على بيتكوين.

ما هي الاشتراكات؟​

يمثل الاشتراك اتفاق دفع متكرر بينك (التاجر) وبين الدافع. في كل دورة فوترة، إما أن:

  • ترسل رابط دفع — تنشئ OrcaRail رابط PaymentLink للفترة و(اختياريًا) ترسله بالبريد إلى الدافع.
  • تخصم تلقائيًا — يوافق الدافع مرة واحدة (allowance على EVM أو تفويض على سولانا)؛ وتسحب OrcaRail مبلغ الفترة في كل دورة.

تدعم الاشتراكات فترات ثابتة (يوم، أسبوع، شهر، سنة)، وفترات تجريبية اختيارية، ودورة حالات مألوفة.

الحقول الشائعة​

المفهومOrcaRail
العميل / الدافعpayer (معرّف المستخدم أو البريد الإلكتروني)
البند / السعرamount + currency + token_id + network_id (بند واحد، أصيل للكريبتو)
الخصم التلقائيcollection_method: auto_charge (سحب عبر allowance على EVM أو تفويض على سولانا)
فاتورة / دفع برابط في كل دورةcollection_method: send_payment_link (رابط PaymentLink لكل دورة، وبريد اختياري)
أحدث عنصر قابل للدفعlatest_payment_link
دورة الحالاتtrialing وactive وpast_due وcanceled وpaused وcompleted (مكيّفة للكريبتو)
الجدولة والبيانات الوصفيةcancel_at_period_end وtrial_end وbilling_cycle_anchor وmetadata

طرق التحصيل​

في كل دورة فوترة، تنشئ OrcaRail رابط PaymentLink بمبلغ الاشتراك. يمكنك مراسلة الدافع (مثلًا قبل يوم من الاستحقاق). يفتح الدافع الرابط ويدفع بمحفظته كما في أي دفعة فردية. دون allowance أو سحب تلقائي.

  • استخدمه عندما: تريد أن يوافق الدافع صراحةً على كل دفعة، أو لا تحتاج إلى خصم تلقائي.
  • التدفق: تنشئ مهمة الفوترة المجدولة رابط PaymentLink ← بريد اختياري ← يدفع الدافع عبر تطبيق الدفع المستضاف.

auto_charge​

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

  • استخدمه عندما: تريد خصومات متكررة حقيقية دون أن يفتح الدافع رابطًا في كل فترة.
  • التدفق: يوافق الدافع في الدورة الأولى أو في صفحة الاشتراك (راجع approval_spender_address في auto_charge) ← في كل دورة تسحب مهمة الفوترة من الدافع ← عند النجاح تُعلَّم الدورة مدفوعة؛ وعند الفشل قد ينتقل الاشتراك إلى past_due ويُبلَّغ الدافع.

راجع الخصم التلقائي لتدفق الموافقة، وخطوات الدافع للموافقة أو الإلغاء، وتفاصيل API.

كائن الاشتراك (شكل الاستجابة)​

تستخدم الاستجابات snake_case وتتبع شكل الاشتراك التالي:

{
  "id": "sub_550e8400e29b41d4a716446655440000",
  "object": "subscription",
  "status": "active",
  "collection_method": "send_payment_link",
  "amount": "10.00",
  "currency": "usd",
  "description": "Monthly Pro Plan",
  "token": { "id": "...", "symbol": "USDC", "name": "USD Coin" },
  "network": { "id": "...", "name": "Base", "chain_id": 8453 },
  "interval": "month",
  "interval_count": 1,
  "total_cycles": 12,
  "completed_cycles": 3,
  "billing_cycle_anchor": 1679609767,
  "current_period_start": "2025-03-01T00:00:00Z",
  "current_period_end": "2025-04-01T00:00:00Z",
  "start_date": "2025-01-01T00:00:00Z",
  "cancel_at": null,
  "cancel_at_period_end": false,
  "trial_start": null,
  "trial_end": null,
  "auto_charge": null,
  "payer": { "id": "...", "email": "[email protected]" },
  "latest_payment_link": {
    "id": "...",
    "unique_slug": "...",
    "link": "...",
    "status": "completed"
  },
  "withdrawal_addresses": { "evm": "0x742d..." },
  "metadata": {},
  "created": "2025-01-01T00:00:00Z",
  "updated": "2025-03-15T00:00:00Z"
}

عندما تكون collection_method هي auto_charge، يتضمن كائن auto_charge محفظة الدافع ومعرّفات الرمز/الشبكة، وallowance_tx_hash الاختياري، وapproved_amount، وapproved_iterations، وapproval_spender_address (الـ spender أو المفوَّض الذي يجب على الدافع الموافقة له على السلسلة)، وstatus. راجع الخصم التلقائي لنقاط نهاية الموافقة والإلغاء وتعيين طريقة التحصيل.

مثال على الشكل بعد الموافقة:

"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"
}

دورة الحالات​

الحالةالوصف
trialingفي الفترة التجريبية؛ لا دفع مطلوب حتى انتهائها
activeحالي؛ تُنشأ روابط دفع في كل دورة أو يعمل الخصم التلقائي
past_dueفشلت دفعة دورة ما أو تأخرت
canceledانتهى الاشتراك (فورًا أو في نهاية الفترة)
pausedمتوقف مؤقتًا (مثل ما بعد الفترة التجريبية دون طريقة دفع)
completedاكتملت كل الدورات (تم بلوغ total_cycles)

تدفق دورة الفوترة​

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