7 نقاط نهاية

الاشتراكات

رابط دفع يُرسَل بالبريد الإلكتروني عند كل استحقاق، بتذكيراته وتوقّفاته وسجله.

عناوين النقاط وأوصافها تأتي من عقد OpenAPI، بالإنجليزية — فلا يمكن أن تحيد عن الواجهة.

تُنشئون مفتاح الاختبار من البوابة بمجرد تفعيل حسابكم.

بكلمات بسيطة

إرسال رابط دفع إلى الزبون نفسه على فترات منتظمة.

متى تستعملونها

لأي إيراد متكرر: اشتراك شهري، أو باقة، أو خدمة مقسّطة.

كيف تدمجونها

1أنشئوا الاشتراك لزبون قائم — ببريد إلكتروني صالح: فإليه يُرسَل كل استحقاق —، بدوريته ومبلغه.
2عند كل استحقاق، تُنشئ ChariPay رابط دفع لاستعمال واحد وترسله إلى الزبون؛ وينقل أول أداء الاشتراك من INCOMPLETE إلى ACTIVE.
3ما دام استحقاق غير مؤدًّى، يُرسَل تذكير كل يوم ولا تُفتح أي فترة جديدة؛ ويبقى الرابط قابلًا للأداء 14 يومًا بعد الاستحقاق، ثم يُلغى الاشتراك — تابعوا subscription.payment_succeeded وsubscription.payment_failed وsubscription.canceled.
4علّقوا أو استأنفوا أو ألغوا حسب حياة العقد؛ واطّلعوا على الاستحقاقات لفوترتكم.
5في السندبوكس، يفتح تاريخُ بدايةٍ في اليوم نفسه الاستحقاق الأول فورًا؛ وتجلب الدورية DAILY الاستحقاق الموالي من الغد.

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}استرجاع اشتراك

POST

استئناف اشتراك

يستأنف دورة فوترة اشتراك موقوف مؤقتًا. ولا تُفوتر الفترات التي انقضت أثناء التوقف بأثر رجعي.

الحقل	النوع	الموضع	مطلوب	الوصف
`reference`	string	path	مطلوب

POST

إيقاف اشتراك مؤقتاً

يوقف الاشتراك مؤقتًا: لا تُفتح أي فترة جديدة ولا يُرسَل أي رابط دفع إلى حين /resume.

الحقل	النوع	الموضع	مطلوب	الوصف
`reference`	string	path	مطلوب

POST

إلغاء اشتراك

يُنهي الاشتراك نهائيًا. لا يُنشأ أي رابط دفع آخر.

الحقل	النوع	الموضع	مطلوب	الوصف
`reference`	string	path	مطلوب

GET

عرض الاشتراكات

يُعيد اشتراكات المستدعي لبيئة المفتاح، على شكل Page مقسّمة إلى صفحات.

الحقل	النوع	الموضع	مطلوب	الوصف
`origin`	enum	query	اختياري	التصفية حسب مصدر الإنشاء (API أو DASHBOARD).القيم `APIDASHBOARD`
`pageable`	Pageable	query	مطلوب

POST200

إنشاء اشتراك

يبدأ اشتراكًا لزبون قائم؛ وتبقى الحالة المُعادة INCOMPLETE إلى أن تُؤدّى الفترة الأولى. عند كل استحقاق، يُنشأ رابط دفع لاستعمال واحد للفترة ويُرسَل بالبريد الإلكتروني إلى الزبون، فيؤديه على صفحة الدفع المستضافة مع 3DS. وما دامت فترة غير مؤدّاة، يُرسَل تذكير كل يوم بالبريد الإلكتروني ولا تُفتح أي فترة لاحقة؛ والرابط الذي يبقى غير مؤدًّى 14 يومًا بعد استحقاقه يُلغي الاشتراك. وإذا كان تاريخ البداية اليوم أو قبله، يُفتح الاستحقاق الأول فورًا ويُعاد في 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	مطلوب	القنوات المستخدمة لإرسال رابط دفع كل فترة إلى الزبون. EMAIL هي القناة المدعومة.
`externalId`	string	body	اختياري	معرّف الاشتراك الخاص بكم، فريد لكل تاجر ولكل بيئة. إنشاء اشتراك بـ externalId موجود مسبقاً يُرجع الاشتراك الموجود. يُعاد إرساله في ExternalId ضمن كل ويب هوك خاص بدفع الاشتراك لأغراض المطابقة.
`metadata`	object	body	اختياري	سمات مطابقة اختيارية خاصة بالتاجر (بحد أقصى 4 كيلوبايت بعد التسلسل)، تُعاد كما هي ضمن metadata في كل ويب هوك لدفع الاشتراك. استخدموا معرّفات مبهمة مثل customerId أو contractId؛ ولا تُدرجوا بيانات البطاقة أو CVV أو بيانات الاعتماد أو بيانات شخصية غير ضرورية.

GET

عرض أقساط اشتراك

يُعيد جميع الاستحقاقات التي ولّدها الاشتراك (رابط دفع لاستعمال واحد لكل فترة فوترة)، بدءًا من أحدث فترة.

الحقل	النوع	الموضع	مطلوب	الوصف
`reference`	string	path	مطلوب

GET

استرجاع اشتراك

يجلب اشتراكًا مع حالته في دورة الحياة واستحقاقه المفتوح: رابط دفع الفترة الحالية، إن وُجد.

الحقل	النوع	الموضع	مطلوب	الوصف
`reference`	string	path	مطلوب	مرجع الاشتراك.

تحدّثوا إلى مختص دمج

أجروا أول نداء في وضع الاختبار

أنشئوا حسابكم، وأنشئوا مفتاح الاختبار من البوابة، وأرسلوا أول طلب اليوم — أو تحدّثوا إلى مختص دمج.

اتصلوا بنا

مجاني ودون التزام
وضع الاختبار منذ التسجيل
لا موافقة تنتظرونها