9 نقاط نهاية
الاشتراكات
خصم متكرر على وسيلة دفع محفوظة، باستحقاقاته وتوقّفاته ومحاولات اقتطاعه.
عناوين النقاط وأوصافها تأتي من عقد OpenAPI، بالإنجليزية — فلا يمكن أن تحيد عن الواجهة.
بكلمات بسيطة
استخلاص من الزبون نفسه على فترات منتظمة، تلقائيًا.
متى تستعملونها
لأي إيراد متكرر: اشتراك شهري، أو باقة، أو خدمة مقسّطة.
كيف تدمجونها
- 1أنشئوا الاشتراك لزبون قائم — ببريد إلكتروني صالح: إشعار ما قبل الخصم الإلزامي يُرسل دائمًا بالبريد —، بدوريته ومبلغه.
- 2تتم الدفعة الأولى بحضور الزبون، بموافقته الصريحة على حفظ وسيلة دفعه.
- 3عيّنوا وسيلة الدفع المراد خصمها، أو اتركوا الوسيلة الافتراضية للزبون.
- 4علّقوا أو استأنفوا أو ألغوا بحسب حياة العقد؛ واطّلعوا على الاستحقاقات لفوترتكم.
- 5وعند تعثر خصم، يتحول الاشتراك إلى
PAST_DUE: حتى 4 محاولات تلقائية، ورابط دفع احتياطي يُرسل للزبون، ثم الإلغاء — تابعواsubscription.payment_failedوsubscription.canceled. - 6في السندبوكس، تفرض نقطة مخصّصة الاستحقاق التالي لتختبروا سنة اشتراك في دقيقة.
- PUT
/v1/subscriptions/{reference}/payment-methodاختيار وسيلة الدفع لاشتراك - POST
/v1/subscriptions/{reference}/test-auto-payفرض الدفع التلقائي التالي (السندبوكس فقط) - POST
/v1/subscriptions/{reference}/resumeاستئناف اشتراك - POST
/v1/subscriptions/{reference}/pauseإيقاف اشتراك مؤقتاً - POST
/v1/subscriptions/{reference}/cancelإلغاء اشتراك - GET
/v1/subscriptionsعرض الاشتراكات - POST
/v1/subscriptionsإنشاء اشتراك - GET
/v1/subscriptions/{reference}/chargesعرض أقساط اشتراك - GET
/v1/subscriptions/{reference}استرجاع اشتراك
اختيار وسيلة الدفع لاشتراك
يحوّل اشتراكاً بالخصم التلقائي إلى إحدى وسائل الدفع المحفوظة لدى زبونه. يُقبل فقط UUID المحلي لوسيلة الدفع؛ ولا يتم أبداً كشف رموز المزوّد ولا CVV.
المخطط · SelectSubscriptionPaymentMethodRequest
| الحقل | النوع | الموضع | مطلوب | الوصف |
|---|---|---|---|---|
reference | string | path | مطلوب | |
paymentMethodId | string (uuid) | body | مطلوب | UUID المحلي لوسيلة الدفع، الخاص بالزبون. |
فرض الدفع التلقائي التالي (السندبوكس فقط)
أداة اختبار متاحة فقط مع مفتاح API من نوع SANDBOX. تنشئ الخصم الخاص بالفترة المستحقة حاليًا أو تعيد استخدامه، وتضع بريد ما قبل الخصم في قائمة الانتظار، ثم تنفّذ فورًا الدفع بالرمز المحفوظ باستخدام CVV المفكوك تشفيره داخليًا مع تعطيل 3DS. لا يظهر CVV أبدًا في الطلب ولا في الاستجابة. يجب أن يكون الاشتراك في الحالة INCOMPLETE أو ACTIVE أو PAST_DUE القابلة لإعادة المحاولة، وأن يكون autoPay مفعّلًا، وأن تكون أول جلسة دفع keepAlive + 3DS قد ربطت بالفعل وسيلة دفع محفوظة. عند النجاح، يتقدّم nextRunDate. عند الفشل، لا يتقدّم: يبقى الفشل الأولي INCOMPLETE، ويتحوّل فشل التجديد إلى PAST_DUE. تتضمّن الاستجابة فئة ورمز فشل آمنين، وعدد المحاولات، وتوقيت إعادة المحاولة أو الإلغاء، وقيمة fallbackPayUrl. تتطلّب حالات الرفض النهائي، مثل البطاقة المنتهية الصلاحية، وسيلة دفع بديلة أو دفعًا يدويًا. Idempotency-Key إلزامي؛ وتؤدي إعادة إرساله إلى إرجاع العملية نفسها دون خصم جديد.
| الحقل | النوع | الموضع | مطلوب | الوصف |
|---|---|---|---|---|
reference | string | path | مطلوب | مرجع الاشتراك. |
Idempotency-Key | string | header | مطلوب | مفتاح فريد إلزامي. لا تُعيدوا استخدامه إلا لإعادة إرسال طلب الاختبار هذا بعينه. |
استئناف اشتراك
يستأنف دورة فوترة اشتراك موقوف مؤقتًا.
| الحقل | النوع | الموضع | مطلوب | الوصف |
|---|---|---|---|---|
reference | string | path | مطلوب |
إيقاف اشتراك مؤقتاً
يوقف الخصومات المستقبلية مؤقتًا دون إلغاء. يمكنكم الاستئناف لاحقًا عبر /resume.
| الحقل | النوع | الموضع | مطلوب | الوصف |
|---|---|---|---|---|
reference | string | path | مطلوب |
إلغاء اشتراك
يُنهي الاشتراك نهائيًا. لا تُنشأ أي خصومات أخرى.
| الحقل | النوع | الموضع | مطلوب | الوصف |
|---|---|---|---|---|
reference | string | path | مطلوب |
عرض الاشتراكات
يُعيد اشتراكات المستدعي لبيئة المفتاح، على شكل Page مقسّمة إلى صفحات.
| الحقل | النوع | الموضع | مطلوب | الوصف |
|---|---|---|---|---|
origin | enum | query | اختياري | التصفية حسب مصدر الإنشاء (API أو DASHBOARD).القيم APIDASHBOARD |
pageable | Pageable | query | مطلوب |
إنشاء اشتراك
يبدأ اشتراكًا متكررًا لزبون موجود. الدفع التلقائي مفعّل افتراضيًا (true)؛ وتبقى الحالة المُعادة INCOMPLETE حتى تنجح فترة الفوترة الأولى. تستخدم صفحة الدفع المستضافة الأولى 3DS، وتحفظ رمزًا (token) من المزوّد، وتُخفي رقم البطاقة (PAN)، وتخزّن عناصر مصادقة قابلة لإعادة الاستخدام في الخزنة المقيّدة الخاضعة للتدقيق. لا يُعاد الرمز ولا CVV. يُعلَن عن الخصومات اللاحقة عبر البريد الإلكتروني وتُحصَّل عند billingTime بتوقيت Africa/Casablanca. إذا كان تاريخ البدء هو اليوم أو قبله، يُفتح القسط الأول فورًا ويُعاد في currentCharge. قدّموا externalId اختياريًا خاصًا بكم (فريدًا لكل تاجر) لجعل الإنشاء غير قابل للتكرار (idempotent): يؤدي externalId مكرر إلى إعادة الاشتراك الموجود مع 200 OK.
المخطط · CreateSubscriptionRequest
| الحقل | النوع | الموضع | مطلوب | الوصف |
|---|---|---|---|---|
clientId | string (uuid) | body | مطلوب | UUID الخاص بالزبون المراد فوترته (أنشئوه أولًا عبر /v1/clients). |
amount | number | body | مطلوب | المبلغ المراد خصمه في كل فترة، بالوحدات الرئيسية للدرهم. |
description | string | body | مطلوب | الوصف الظاهر على كل خصم يتم إنشاؤه. |
frequency | enum | body | مطلوب | وتيرة الفوترة.القيم DAILYWEEKLYMONTHLYYEARLY |
startDate | string (date) | body | مطلوب | تاريخ فترة الفوترة الأولى (YYYY-MM-DD). |
endDate | string (date) | body | اختياري | تاريخ انتهاء اختياري؛ بلا نهاية محددة عند إغفاله. |
channels | array of enum | body | مطلوب | القنوات المستخدمة لإشعار الزبون بكل خصم. |
externalId | string | body | اختياري | معرّف الاشتراك الخاص بكم، فريد لكل تاجر ولكل بيئة. إنشاء اشتراك بـ externalId موجود مسبقاً يُرجع الاشتراك الموجود. يُعاد إرساله في ExternalId ضمن كل ويب هوك خاص بدفع الاشتراك لأغراض المطابقة. |
metadata | object | body | اختياري | سمات مطابقة اختيارية خاصة بالتاجر (بحد أقصى 4 كيلوبايت بعد التسلسل)، تُعاد كما هي ضمن metadata في كل ويب هوك لدفع الاشتراك. استخدموا معرّفات مبهمة مثل customerId أو contractId؛ ولا تُدرجوا بيانات البطاقة أو CVV أو بيانات الاعتماد أو بيانات شخصية غير ضرورية. |
autoPay | boolean | body | اختياري | يحفظ وسيلة الدفع بعد أول عملية دفع 3DS ويُحصّل الفترات اللاحقة تلقائيًا. القيمة الافتراضية true. |
billingTime | LocalTime | body | اختياري | وقت الخصم المتكرر بتوقيت Africa/Casablanca. |
billingTime.hour | integer (int32) | body | اختياري | |
billingTime.minute | integer (int32) | body | اختياري | |
billingTime.second | integer (int32) | body | اختياري | |
billingTime.nano | integer (int32) | body | اختياري | |
reminderDaysBefore | integer (int32) | body | اختياري | عدد الأيام التي تسبق الخصم التلقائي لإرسال بريد إلكتروني إلى الزبون (0-30). |
paymentMethodId | string (uuid) | body | اختياري | UUID اختياري لوسيلة دفع تخص الزبون. عند إغفاله، يُعاد استخدام وسيلة الدفع الافتراضية للزبون إن وُجدت؛ وإلا تلتقط جلسة الدفع الأولى وسيلة جديدة. |
عرض أقساط اشتراك
يُعيد جميع الأقساط (روابط الدفع) التي ولّدها الاشتراك، بدءًا من أحدث فترة.
| الحقل | النوع | الموضع | مطلوب | الوصف |
|---|---|---|---|---|
reference | string | path | مطلوب |
استرجاع اشتراك
يجلب اشتراكًا مع بيانات العرض الآمنة لوسيلة الدفع المحفوظة، والقسط المفتوح، وحالة استرجاع الفوترة. في حالة إعداد INCOMPLETE فاشل أو تجديد PAST_DUE، يتضمن billingRecovery سببًا موحّدًا، والإجراء المطلوب من الزبون، وعدد المحاولات، وموعد إعادة المحاولة التالية، والمهلة النهائية للإلغاء؛ ولا يُعاد أبدًا JSON خطأ المزوّد ولا بيانات البطاقة الحساسة.
| الحقل | النوع | الموضع | مطلوب | الوصف |
|---|---|---|---|---|
reference | string | path | مطلوب | مرجع الاشتراك. |
سؤال حول الدمج؟
يجيب فريقنا التقني فرق الإدماج، من أول استدعاء في السندبوكس حتى الانتقال إلى الإنتاج.