وثائق API

مرجع شامل لـ API الخاص بـ Banking-as-a-Service من Chari Money. ادمج الخدمات المالية في تطبيقاتك عبر نقاط نهاية (endpoints) قوية وآمنة.

البدء

الإصدار 2.1 · آخر تحديث 19 يونيو 2026

مرحبًا بكم في الوثائق الرسمية لواجهة برمجة التطبيقات الخاصة بالخدمات البنكية كخدمة (BAAS) من Chari Money. تتيح واجهة RESTful هذه لشركات التكنولوجيا المالية والمنصات والمطوّرين دمج بنية مالية متكاملة في تطبيقاتهم: فتح الحسابات مع التحقق من الهوية KYC، المعاملات بين المحافظ، الإيداع بالبطاقة (3D Secure)، التحويلات البنكية عبر RIB، المدفوعات متعددة القنوات للتجار (الهاتف، رمز QR، البطاقة)، إدارة المستفيدين، وكلاء التجزئة، وإشعارات Webhook الفورية. تتبع جميع نقاط النهاية نموذج معاينة/تنفيذ مع تأكيد غير متزامن عبر Webhook.

Headers المصادقة

أدرِجوا الترويسات التالية في جميع طلبات API:

Header	Type	مطلوب	Description
`Chari-Api-Key`	string	مطلوب	مفتاح API للمصادقة. توفّره Chari لكل بيئة (sandbox / production).
`C-Request-Id`	string	اختياري	معرّف فريد لكل طلب لأغراض التتبّع. يُعاد في الاستجابة. الصيغة الموصى بها: UUID v4. مثال: 69906411-0aa24a89-ab2005ca-9d18dc15

بطاقة ائتمان للاختبار (sandbox)

PAN

4918914107195005

CVV

123

تاريخ الانتهاء

08/26 (أو أي تاريخ مستقبلي)

رمز 3D Secure

555

جديد

حزمة LLM والذكاء الاصطناعي

حزمة كاملة محسَّنة لنماذج اللغة الكبيرة (LLM) والمساعدات الذكية: وثائق Markdown، ومخططات JSON Schemas، ورسوم Mermaid، ومواصفة OpenAPI 3.0، وأمثلة cURL وقواعد التحقق. مثالية لتقنية RAG وتوليد الشيفرة والتكامل مع Cursor أو Copilot أو Claude.

OpenAPI 3.0JSON SchemaMermaidMarkdowncURL

تنزيل .zip

Postman Collection

حمّلوا مجموعة Postman الكاملة لاختبار جميع نقاط نهاية API.

تنزيل

سجل التغييرات

v1.8

2025-11-05

الوثائق الأولية. تغطية كاملة لواجهة API الإصدار v1.8.

v1.8.1

2025-12-01

إضافة نقطة النهاية merchant-kyc-upload. إثراء الجداول المرجعية (docTypes وcustomerStatuses وaccountLevels). تفصيل رموز الأخطاء مع ربطها بنقاط النهاية. إضافة المعامل autoActivate إلى confirm. تصحيح مسار confirm.

v1.9

2026-04-14

إضافة قسم المحاكاة (Sandbox). أنواع عمليات جديدة: 10=RECHARGE و25=BILL_PAYMENT؛ إعادة تسمية 5→MOBILE_PAYMENT و24→CARD_PAYMENT. توحيد حالات المعاملات: OPEN/COMPLETED/FAILED/CANCELED. تبسيط Webhooks: إضافة payment.received وإزالة operation.created/operation.updated/customer.kyc/bank-transfer.failed. أصبحت صيغة مرجع CashIn/CashOut رقمية (مثال: 1122334455).

v2.0

2026-06-04

الترقية إلى وثائق الإصدار v2.0 (إصدار تمهيدي). إضافة قسم "إدارة البطاقات" (بيتا): البرامج، الطلبات، البطاقات، إجراءات البطاقة، ضبط الاستخدام، المعاملات وقوائم تعداد البطاقات. قسم البطاقات تمهيدي وسيُستكمل بنقاط النهاية الناقصة — وقد يتضمن أخطاء.

v2.1

2026-06-19

إضافة ثلاث وحدات جديدة: تعبئة رصيد الاتصالات Telco Top-up (الكتالوج + التعبئة)، القسائم Vouchers (الكتالوج، العلامات التجارية، معاينة/تأكيد الشراء) ودفع الفواتير Bill Payment (شبكة Fatourati: الدائنون، المستحقات، النموذج الديناميكي، غير المدفوعات، التأكيد، + Webhooks). إضافة نقطة النهاية المخصصة للإيداع Fatourati CashIn ونوع العملية 23 = VOUCHER.

v2.2

2026-06-24

توثيق مستندات KYB المطلوبة لإنشاء محفظة تاجر، حسب نوع العميل المهني (شخص اعتباري، مهني ذاتي، مؤسسة / جمعية) — أُضيفت كملاحظات على نقطة النهاية "Merchant KYC Upload".

نظرة عامة — المحفظة الإلكترونية M-Wallet في المغرب

ما هو M-Wallet؟

المحفظة الإلكترونية M-Wallet (المحفظة المحمولة) هي حساب نقود إلكترونية خاضع للتنظيم يتيح للأفراد والتجار إجراء معاملات مالية باستخدام رقم الهاتف المحمول كمعرّف. وهي جزء من الإطار الوطني لبنك المغرب (BAM) للشمول المالي والمدفوعات الرقمية. كل محفظة مرتبطة بهوية مستخدم متحقَّق منها (KYC) ومحفوظة بموجب ترخيص مؤسسة الأداء الخاصة بنا (CHARI MONEY) الخاضعة لرقابة بنك المغرب.

المبادئ الأساسية

معرّف محفظة فريد

يُستخدم رقم MSISDN (رقم الهاتف المحمول) الخاص بالمستخدم كمعرّف للمحفظة.

شبكة قابلة للتشغيل البيني

يمكن لجميع المحافظ الإلكترونية M-Wallet تبادل الأموال بين مختلف المزوّدين عبر المقسم الوطني (Switch).

مستويات التحقق KYC

تعتمد صلاحيات الحساب وحدوده على تحقق المستخدم (البطاقة الوطنية CIN، سيلفي، إثبات العنوان، إلخ).

عمليات فورية

تُنفَّذ التحويلات وعمليات الإيداع/السحب ومدفوعات التجار ودفع الفواتير فورًا مع التأكيد.

أنواع الحسابات

النوع	المالك	Description	العمليات
المستهلك (فرد)	الأفراد	محفظة شخصية مرتبطة برقم هاتف محمول واحد وبطاقة هوية وطنية.	الإيداع/السحب، التحويلات بين الأفراد P2P، مدفوعات التجار، وخدمات دفع أخرى.
التاجر	مقاولة صغيرة أو متجر أو مقدّم خدمات	محفظة تجارية مرتبطة بحساب تاجر أو متجر.	استقبال المدفوعات، التحويل إلى البنك، ردّ المبلغ للعميل، وخدمات دفع أخرى.
وكيل التجزئة	شبكة/شريك وكلاء معتمدون	يستخدمها وكلاء التوزيع لتسهيل عمليات الإيداع/السحب للمستخدمين.	تعبئة/تفريغ محافظ العملاء.
الوكيل الرئيسي	الشريك / EDP	محفظة مخصصة للشركات بحدود أعلى وحلول تكامل.	مدفوعات جماعية، صرف الرواتب، التحصيلات، وعمليات متعددة أخرى.

مستويات الحساب

المستوى	متطلبات KYC	حد الرصيد
المستوى 1	الاسم + رقم هاتف صالح + رقم البطاقة الوطنية CIN	1,000 MAD
المستوى 2	تحقق كامل من الهوية KYC (البطاقة الوطنية CIN + سيلفي أو مسح الوثيقة)	4,000 MAD
المستوى 3	هوية متحقَّق منها (KYC)، مقابلة، ملف عميل رقمي	20,000 MAD
المستوى 4	تحقق كامل من الهوية KYC، مقابلة، ملف عميل رقمي، إثبات الدخل، إثبات العنوان	100,000 MAD
التاجر	تحقق كامل من الشركة KYB + السجل التجاري (IF/RC)	قابل للتفاوض

مسرد المصطلحات

المصطلح	التعريف
M-Wallet	حساب نقود إلكترونية خاضع للتنظيم مرتبط برقم هاتف محمول، يتيح للمستخدمين إجراء معاملات مالية مثل التحويلات والمدفوعات والعمليات النقدية.
Wallet	حساب مستخدم داخل النظام يخزّن النقود الإلكترونية ويرتبط بمعرّف فريد (MSISDN).
MSISDN	رقم الهاتف المحمول المستخدم كمعرّف أساسي للمحفظة.
KYC (Know Your Customer)	عملية تحقق تُستخدم لتحديد هوية المستخدم والتثبت منها وفقًا للمتطلبات التنظيمية.
مستوى التحقق KYC	مستوى تنظيمي يُسنَد إلى المحفظة بناءً على حالة التحقق، ويحدّد حدود المعاملات والرصيد.
العملية	إجراء أعمال عالي المستوى يبدؤه مستخدم أو شريك (مثال: إيداع، تحويل، دفع).
Transaction	حركة مالية (خصم، إضافة، رسوم، تسوية) تُنشأ في إطار عملية.
نوع العملية	فئة إجراء الأعمال (مثال: CASHIN، TRANSFER، PAYMENT).
نوع المعاملة	نوع الحركة المالية المرتبطة بعملية (مثال: خصم، إضافة، رسوم).
حالة العملية	الحالة الحالية لدورة حياة العملية (مثال: OPEN، COMPLETED، FAILED).
حالة المعاملة	حالة معالجة المعاملة (مثال: COMPLETED، FAILED).
المرجع	معرّف فريد يُنشأ لعملية معلّقة (مثال: إيداع/سحب)، ويُستخدم لإتمام المعاملة عبر شبكة خارجية.
الوكيل / الشبكة	جهة خارجية معتمدة أو قناة توزيع تُستخدم لتنفيذ عمليات الإيداع والسحب.
مفتاح API	رمز آمن يُستخدم لمصادقة طلبات الشركاء إلى واجهة BAAS API.
Webhook	استدعاء HTTP آلي يرسله النظام لإشعار الشركاء بتحديثات العمليات أو المعاملات.

تسجيل العملاء

إدارة كاملة لدورة حياة العميل: التحقق من الحالة، التسجيل، تأكيد رمز OTP، إدارة الرمز السري PIN، الاطلاع على الرصيد والمعلومات، وإلغاء التسجيل.

GET{host}/api/customers/status

التحقق من الحالة لدى Chari

استرجاع حالة التسجيل الحالية للعميل لدى Chari فقط.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	رقم هاتف العميل. الصيغة: +212*********

ملاحظات

•0 : Not exists — الرقم غير موجود لدى ChariMoney.
•1 : Not confirmed — الرقم موجود لدى ChariMoney لكنه غير مسجّل بعد لدى Switch (لم يُدخل رمز OTP).
•2 : Confirmed — الرقم موجود ومسجّل لدى Switch.
•3 : Active — مسجّل لدى Switch ونشِط لدى ChariMoney (تم إنشاء الرمز السري PIN).
•4 : Locked temporary — الرقم محظور مؤقتًا (تم تجاوز الحد الأقصى للمحاولات).
•5 : Locked — الرقم محظور.

GET{host}/api/customers/default

التحقق من الحالة لدى Switch

معرفة ما إذا كانت Chari هي المحفظة الافتراضية للعميل.

Parameter	Type	In	مطلوب	Description
`phoneNumber`	string	query	مطلوب	رقم هاتف العميل. الصيغة: +212*********

ملاحظات

•true : Chari هي المحفظة الافتراضية للعميل.
•false : Chari ليست المحفظة الافتراضية للعميل.

POST{host}/api/customers/register202

التسجيل

بدء عملية تسجيل عميل جديد. سيُرسَل رمز OTP عبر SMS.

Parameter	Type	In	مطلوب	Description
`phoneNumber`	string	body	مطلوب	رقم هاتف العميل. الصيغة: +212*********
`firstName`	string	body	مطلوب	حرفان على الأقل (أحرف لاتينية فقط)
`lastName`	string	body	مطلوب	حرفان على الأقل (أحرف لاتينية فقط)
`cin`	string	body	مطلوب	5 أحرف على الأقل
`walletType`	string	body	مطلوب	"P": فرد (Particulier) / "C": تاجر (Commerçant)
`closeLoopOnly`	boolean	body	اختياري	إذا كانت القيمة true، يُسجَّل العميل في وضع CloseLoop فقط. في هذه الحالة، تُرسل CHARI رمز OTP مباشرة.

POST{host}/api/customers/confirm200

التأكيد

تأكيد التسجيل باستخدام رمز OTP كوسيلة تحقق.

Parameter	Type	In	مطلوب	Description
`phoneNumber`	string	body	مطلوب	رقم هاتف العميل. الصيغة: +212*********
`code`	string	body	مطلوب	رمز OTP المستلَم بالصيغة: xxx-xxx
`walletType`	string	body	مطلوب	نوعان مقبولان: "P": فرد (Particulier)، "C": تاجر (Commerçant).
`autoActivate`	boolean	body	اختياري	القيمة الافتراضية: false. تحدّد ما إذا كان يجب تفعيل المحفظة تلقائيًا بعد التحقق من رمز OTP. إذا كانت false، يجب على المستخدم إتمام التفعيل بإنشاء أو إدخال الرمز السري PIN. إذا كانت true، تُفعَّل المحفظة تلقائيًا دون الحاجة إلى PIN.

POST{host}/api/customers/confirm/resend-otp

إعادة إرسال OTP

إعادة إرسال كلمة المرور لمرة واحدة (OTP) للتسجيل أو التأكيد.

Parameter	Type	In	مطلوب	Description
`phoneNumber`	string	query	مطلوب	رقم هاتف العميل. الصيغة: +212*********

POST{host}/api/customers/login

تسجيل الدخول بالرمز السري PIN

مصادقة عميل موجود باستخدام رمزه السري PIN.

Parameter	Type	In	مطلوب	Description
`phoneNumber`	string	body	مطلوب	رقم هاتف العميل. الصيغة: +212*********
`pin`	string	body	مطلوب	الرمز السري PIN الخاص بالعميل.

ملاحظات

•logged : تكون true إذا نجحت المصادقة، وfalse خلاف ذلك.
•remainingAttempts : عدد المحاولات المتبقية قبل قفل الحساب.

POST{host}/api/customers/pin

إنشاء الرمز السري PIN

إنشاء رمز سري PIN آمن لعميل مسجَّل.

Parameter	Type	In	مطلوب	Description
`phoneNumber`	string	body	مطلوب	رقم هاتف العميل. الصيغة: +212*********
`pin`	string	body	مطلوب	الرمز السري PIN الخاص بالعميل. (4 أرقام مطلوبة)

PATCH{host}/api/customers/pin

تحديث الرمز السري PIN

تغيير الرمز السري PIN الحالي لأسباب أمنية أو بحسب تفضيل المستخدم.

Parameter	Type	In	مطلوب	Description
`phoneNumber`	string	body	مطلوب	رقم هاتف العميل. الصيغة: +212*********
`oldPin`	string	body	مطلوب	الرمز السري PIN الحالي للعميل.
`newPin`	string	body	مطلوب	الرمز السري PIN الجديد للعميل.

POST{host}/api/customers/pin/resetقريباً

إعادة تعيين الرمز السري PIN

إعادة تعيين الرمز السري PIN للعميل. سيتوفر في الإصدار القادم.

لا توجد معاملات (parameters) مطلوبة.

GET{host}/api/customers/balance

الاطلاع على رصيد العميل

استرجاع رصيد عميل مسجَّل.

Parameter	Type	In	مطلوب	Description
`phoneNumber`	string	query	مطلوب	رقم هاتف العميل. الصيغة: +212*********

GET{host}/api/customers/info

الاطلاع على معلومات العميل

استرجاع بيانات الملف التفصيلية لعميل مسجَّل.

Parameter	Type	In	مطلوب	Description
`phoneNumber`	string	query	مطلوب	رقم هاتف العميل. الصيغة: +212*********

ملاحظات

•accountLevel : مستوى الحساب (1 = أساسي، 2-4 = مستويات KYC أعلى).
•customerStatus : حالة العميل (انظر نقطة النهاية "التحقق من الحالة لدى Chari").
•rib : معرّف الحساب البنكي (RIB) المرتبط بالمحفظة.

PUT{host}/api/customers/unregister

إلغاء التسجيل

تعطيل عميل أو إزالته من المنصة.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	body	مطلوب	رقم هاتف العميل. الصيغة: +212*********
`Reason`	int	body	مطلوب	رمز سبب الإغلاق (انظر الملاحظات).

ملاحظات

•1 : إغلاق بمبادرة من EDP — سبب غير محدد
•2 : إغلاق بمبادرة من EDP — اشتباه في احتيال
•3 : إغلاق بمبادرة من العميل — إنهاء العقد
•4 : إغلاق بمبادرة من العميل — هاتف مفقود أو مسروق
•5 : إغلاق بمبادرة من العميل — سبب غير محدد

التحقق من الهوية KYC

مسار KYC عبر الهاتف المحمول (iOS/Android) مدعوم من ShareID. يشغّل تطبيقكم حزمة ShareID SDK لمسح الوثيقة والتقاط السيلفي؛ وتتولى ShareID فحوص الجودة والأصالة ومطابقة الوجه مع الوثيقة.

مسار التكامل

1يستدعي تطبيقكم "/kyc/shareid/auth" للحصول على رمز KYC قصير الصلاحية.
2يفتح التطبيق حزمة ShareID SDK بهذا الرمز.
3يمسح المستخدم بطاقة هويته ويُكمل سيلفي موجَّهًا.
4تُجري ShareID عمليات التحقق.
5يستدعي تطبيقكم "/kyc/session/complete" للإشارة إلى انتهاء المسار على الجهاز.
6يُرسَل استدعاء راجع (callback) إلى واجهة API الخاصة بنا مع الحالة والمستندات.

GET{host}/api/kyc/shareid/auth

المصادقة

الحصول على رمز KYC قصير الصلاحية لتشغيل حزمة ShareID SDK.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	رقم هاتف العميل. الصيغة: +212*********

ملاحظات

•baseUrl : عنوان URL الأساسي لحزمة ShareID SDK المراد استخدامها.
•applicant_id : المعرّف الفريد لطلب التحقق KYC.
•token : رمز JWT مؤقت للمصادقة من جهة SDK.

POST{host}/api/customers/upgrade/request

التأكيد

الإشارة إلى انتهاء مسار KYC على الجهاز وطلب ترقية الحساب.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	رقم هاتف العميل. الصيغة: +212*********
`AccountLevel`	int	query	مطلوب	مستوى الحساب المراد الترقية إليه (2 أو 3 أو 4).

POST{host}/api/merchant/kyc/request

رفع مستندات KYC للتاجر

رفع مستندات KYC الخاصة بالتاجر لطلب ترقية الحساب (multipart/form-data).

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	رقم هاتف التاجر. الصيغة: +212*********
`KycDocuments`	multipart form	body	مطلوب	مصفوفة من كائنات مستندات KYC. يمكن إرسال عدة مستندات في طلب واحد بتكرار الحقول المفهرسة (مثال: kycDocuments[0]، kycDocuments[1]، ...).
`KycDocuments[n].DocType`	int	body	مطلوب	نوع المستند (انظر جدول أنواع المستندات).
`KycDocuments[n].DocFront`	file	body	مطلوب	الصورة الأمامية للمستند. الصيغ المقبولة: PNG وJPG/JPEG وPDF.
`KycDocuments[n].DocBack`	file	body	اختياري	الصورة الخلفية (مطلوبة للمستندات IdentityCard وDrivingLicense وResidencePermit).

ملاحظات

•التحقق من الشركة KYB — تعتمد المستندات المطلوبة لإنشاء محفظة تاجر (مهنية) على الوضع القانوني للعميل. في الحالات الثلاث جميعها تُطلب البطاقة الوطنية أو جواز سفر الموقّع على العقد (DocType 1 أو 3) وإثبات حساب بنكي — RIB / شهادة حساب بنكي، أو شيك ملغى / نموذج شيك. ارفعوا كل مستند مع DocType المطابق له من جدول أنواع المستندات.
•الشخص الاعتباري (شركة / منظمة): البطاقة الوطنية / جواز سفر الموقّع؛ النظام الأساسي للشركة؛ محضر آخر جمعية عامة يؤكد صلاحية التوقيع (مطلوب فقط إذا لم يكن المسيّر / الممثل القانوني مذكورًا كموقّع وحيد في النظام الأساسي)؛ شهادة السجل التجاري (DocType 8) صادرة منذ أقل من 90 يومًا؛ شهادة التسجيل في الضريبة المهنية (Patente)؛ إثبات حساب بنكي (RIB أو شيك ملغى).
•المهني الذاتي (مقاول ذاتي / مستقل / مقاولة فردية): البطاقة الوطنية / جواز سفر الموقّع؛ بطاقة المقاول الذاتي / وثيقة التسجيل المهني؛ شهادة التسجيل في الضريبة المهنية (Patente)؛ إثبات حساب بنكي (RIB أو شيك ملغى)؛ شهادة السجل التجاري (DocType 8) صادرة منذ أقل من 90 يومًا والنظام الأساسي للشركة، إن وُجدا.
•المؤسسة / الجمعية: البطاقة الوطنية / جواز سفر الموقّع؛ محضر آخر جمعية عامة يؤكد صلاحية التوقيع (مطلوب فقط إذا لم يكن الممثل المفوَّض مذكورًا بوضوح في النظام الأساسي)؛ قائمة الممثلين المفوَّضين / أعضاء المجلس؛ النظام الأساسي للجمعية / المؤسسة؛ إثبات حساب بنكي (RIB أو شيك ملغى).

العمليات

جميع العمليات المالية: الإيداع بالبطاقة، التحويلات بين المحافظ، التحويلات البنكية، مدفوعات التجار، عمليات الاسترجاع، المبالغ المردودة، والطلبات المبنية على مرجع.

الإيداع بالبطاقة CashIn

بطاقة ائتمان تجريبية

أرقام بطاقات ائتمان صالحة لإضافة أموال في بيئة sandbox.

PAN

4918914107195005

CVV

123

تاريخ الانتهاء

08/26 (أو أي تاريخ مستقبلي)

رمز 3D Secure

555

POST{host}/api/operations/cashin/card/preview

معاينة (عبر الهاتف)

التحقق من إمكانية إيداع أموال في محفظة عميل انطلاقًا من بطاقة.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	رقم هاتف العميل. الصيغة: +212*********
`Amount`	decimal	body	مطلوب	المبلغ المراد إيداعه. يجب أن يكون رقمًا موجبًا.

POST{host}/api/operations/cashin/card

تنفيذ (عبر الهاتف)

إضافة أموال إلى محفظة عميل انطلاقًا من بطاقة أداء. تُطلق مصادقة 3D Secure.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	رقم هاتف العميل.
`FirstName`	string	body	مطلوب	الاسم الشخصي لحامل البطاقة.
`LastName`	string	body	مطلوب	الاسم العائلي لحامل البطاقة.
`Cvv`	string	body	مطلوب	رمز الأمان المكوَّن من 3 أرقام (CVV).
`Amount`	decimal	body	مطلوب	المبلغ المراد إيداعه.
`Currency`	string	body	اختياري	رمز العملة ISO المكوَّن من 3 أحرف (مثال: MAD).
`Pan`	string	body	مطلوب	رقم البطاقة الكامل (PAN).
`ExpiryDate`	string	body	مطلوب	تاريخ الانتهاء بصيغة YYMM.
`KeepAlive`	bool	body	مطلوب	true: حفظ البطاقة للاستخدام اللاحق / false: استخدام لمرة واحدة.
`CardName`	string	body	اختياري	الاسم الذي يختاره المستخدم للبطاقة المحفوظة.

ملاحظات

•بعد مصادقة 3D Secure، يُعاد توجيه المستخدم إلى acceptURL أو declineURL.
•قيمة RESPONSE_CODE في عنوان URL لإعادة التوجيه: 0 = نجاح، وأي قيمة أخرى = فشل.
•REASON_CODE : سبب النتيجة بصيغة مقروءة (مثال: SUCCESS، DECLINED).
•تحققوا من RESPONSE_CODE وREASON_CODE لتحديد الإجراء التالي في تطبيقكم.

POST{host}/api/operations/cashin/card/{cardId}

تنفيذ ببطاقة محفوظة

إضافة أموال من بطاقة مرمَّزة محفوظة.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	رقم هاتف العميل.
`CardId`	int	route	مطلوب	معرّف البطاقة المحفوظة.
`Cvv`	string	body	مطلوب	رمز الأمان المكوَّن من 3 أرقام.
`Amount`	decimal	body	مطلوب	المبلغ المراد إيداعه.

ملاحظات

•بعد مصادقة 3D Secure، يُعاد توجيه المستخدم إلى acceptURL أو declineURL حسب النتيجة.
•يتضمن عنوان URL لإعادة التوجيه المعاملات التالية: RESPONSE_CODE (0 = نجاح، وأي قيمة أخرى = فشل)، وREASON_CODE (سبب مقروء: SUCCESS، DECLINED…) وOPERATION (نوع العملية، مثال: PAYMENT).
•تحققوا من RESPONSE_CODE وREASON_CODE عند استلام إعادة التوجيه لتحديد الإجراء التالي في تطبيقكم.

POST{host}/api/operations/cashin/card/agent/preview

معاينة (عبر الوكيل)

التحقق من إمكانية إيداع أموال عبر رمز الوكيل.

Parameter	Type	In	مطلوب	Description
`code`	string	query	مطلوب	رمز الوكيل.
`Amount`	decimal	body	مطلوب	المبلغ المراد إيداعه.

POST{host}/api/operations/cashin/card/agent

تنفيذ (عبر الوكيل)

إضافة أموال إلى محفظة عميل عبر وكيل.

Parameter	Type	In	مطلوب	Description
`agent`	string	query	مطلوب	رمز الوكيل.
`FirstName`	string	body	مطلوب	الاسم الشخصي لحامل البطاقة.
`LastName`	string	body	مطلوب	الاسم العائلي لحامل البطاقة.
`Cvv`	string	body	مطلوب	رمز الأمان المكوَّن من 3 أرقام.
`Amount`	decimal	body	مطلوب	المبلغ المراد إيداعه.
`Pan`	string	body	مطلوب	رقم البطاقة الكامل.
`ExpiryDate`	string	body	مطلوب	تاريخ الانتهاء بصيغة YYMM.
`KeepAlive`	bool	body	مطلوب	حفظ البطاقة للاستخدام اللاحق.
`Currency`	string	body	اختياري	رمز العملة ISO المكوَّن من 3 أحرف (مثال: MAD).
`CardName`	string	body	اختياري	الاسم الذي يختاره المستخدم لحفظ البطاقة.

ملاحظات

•بعد مصادقة 3D Secure، يُعاد توجيه المستخدم إلى acceptURL أو declineURL حسب النتيجة.
•يتضمن عنوان URL لإعادة التوجيه المعاملات التالية: RESPONSE_CODE (0 = نجاح، وأي قيمة أخرى = فشل)، وREASON_CODE (سبب مقروء: SUCCESS، DECLINED…) وOPERATION (نوع العملية، مثال: PAYMENT).
•تحققوا من RESPONSE_CODE وREASON_CODE عند استلام إعادة التوجيه لتحديد الإجراء التالي في تطبيقكم.

التحويل

POST{host}/api/operations/transfer/preview

معاينة

التحقق من إمكانية نقل الأموال داخليًا بين محافظ العملاء.

Parameter	Type	In	مطلوب	Description
`CustomerPhoneNumber`	string	body	مطلوب	رقم هاتف المُرسِل. الصيغة: +212*********
`Amount`	decimal	body	مطلوب	المبلغ المراد تحويله.
`Reason`	string	body	مطلوب	سبب التحويل.
`RecipientPhoneNumber`	string	body	مطلوب	رقم هاتف المستفيد. الصيغة: +212*********
`BeneficiaryId`	int	body	اختياري	مرجع إلى مستفيد موجود (اختياري).

POST{host}/api/operations/transfer

تنفيذ

نقل الأموال داخليًا بين محافظ العملاء.

Parameter	Type	In	مطلوب	Description
`CustomerPhoneNumber`	string	body	مطلوب	رقم هاتف المُرسِل.
`Amount`	decimal	body	مطلوب	المبلغ المراد تحويله.
`Reason`	string	body	مطلوب	سبب التحويل.
`RecipientPhoneNumber`	string	body	مطلوب	رقم هاتف المستفيد.
`BeneficiaryId`	int	body	اختياري	مرجع إلى مستفيد موجود (اختياري).

التحويل البنكي

POST{host}/api/operations/bank-transfer/preview

معاينة

التحقق من إمكانية إرسال أموال من محفظة إلى حساب بنكي خارجي.

Parameter	Type	In	مطلوب	Description
`CustomerPhoneNumber`	string	body	اختياري	مطلوب إذا كان AgentCode فارغًا. لا يجتمع مع AgentCode (أحدهما فقط).
`AgentCode`	string	body	اختياري	مطلوب إذا كان CustomerPhoneNumber فارغًا. رمز الوكيل (رئيسي أو تجزئة). لا يجتمع مع CustomerPhoneNumber.
`Amount`	decimal	body	مطلوب	المبلغ المراد تحويله.
`Reason`	string	body	مطلوب	سبب التحويل (أحرف لاتينية فقط، بحد أقصى 35 حرفًا).
`BeneficiaryId`	int	body	اختياري	اختياري إذا تم توفير rib + beneficiaryName.
`BeneficiaryName`	string	body	اختياري	اختياري إذا تم توفير beneficiaryId.
`Rib`	string	body	اختياري	RIB: سلسلة رقمية من 24 رقمًا. اختياري إذا تم توفير beneficiaryId.

ملاحظات

•يجب توفير معرّف واحد على الأقل من بين beneficiaryId أو (rib + beneficiaryName).

POST{host}/api/operations/bank-transfer

تنفيذ

إرسال أموال من محفظة إلى حساب بنكي خارجي.

Parameter	Type	In	مطلوب	Description
`CustomerPhoneNumber`	string	body	اختياري	مطلوب إذا كان AgentCode فارغًا. لا يجتمع مع AgentCode (أحدهما فقط).
`AgentCode`	string	body	اختياري	مطلوب إذا كان CustomerPhoneNumber فارغًا. لا يجتمع مع CustomerPhoneNumber.
`Amount`	decimal	body	مطلوب	المبلغ المراد تحويله.
`Reason`	string	body	اختياري	سبب التحويل (اختياري في خطوة التنفيذ).
`BeneficiaryId`	int	body	اختياري	اختياري إذا تم توفير rib + beneficiaryName.
`BeneficiaryName`	string	body	اختياري	اختياري إذا تم توفير beneficiaryId.
`Rib`	string	body	اختياري	RIB: 24 رقمًا. مطلوب في غياب beneficiaryId.

الدفع للتاجر

POST{host}/api/operations/merchant/payment/push/manual/preview

عبر الهاتف — معاينة

التحقق من الدفع للتاجر عبر PhoneNumber.

Parameter	Type	In	مطلوب	Description
`CustomerPhoneNumber`	string	body	مطلوب	رقم هاتف العميل الدافع.
`Amount`	decimal	body	مطلوب	مبلغ الدفع.
`Reason`	string	body	مطلوب	سبب الدفع.
`RecipientPhoneNumber`	string	body	مطلوب	رقم هاتف التاجر.
`BeneficiaryId`	int	body	اختياري	مرجع إلى مستفيد موجود (اختياري).

POST{host}/api/operations/merchant/payment/push/manual

عبر الهاتف — تنفيذ

الدفع للتاجر عبر PhoneNumber.

Parameter	Type	In	مطلوب	Description
`CustomerPhoneNumber`	string	body	مطلوب	رقم هاتف العميل الدافع.
`Amount`	decimal	body	مطلوب	مبلغ الدفع.
`Reason`	string	body	مطلوب	سبب الدفع.
`RecipientPhoneNumber`	string	body	مطلوب	رقم هاتف التاجر.
`BeneficiaryId`	int	body	اختياري	مرجع إلى مستفيد موجود (اختياري).

POST{host}/api/operations/merchant/payment/push/qrcode/preview

عبر رمز QR — معاينة

التحقق من الدفع للتاجر عبر رمز QR.

Parameter	Type	In	مطلوب	Description
`CustomerPhoneNumber`	string	body	مطلوب	رقم هاتف العميل الدافع.
`QrCodeContent`	string	body	مطلوب	محتوى رمز QR الممسوح.
`Amount`	decimal	body	مطلوب	مبلغ الدفع.

POST{host}/api/operations/merchant/payment/push/qrcode

عبر رمز QR — تنفيذ

الدفع للتاجر عبر رمز QR.

Parameter	Type	In	مطلوب	Description
`CustomerPhoneNumber`	string	body	مطلوب	رقم هاتف العميل الدافع.
`QrCodeContent`	string	body	مطلوب	محتوى رمز QR.
`Amount`	decimal	body	مطلوب	مبلغ الدفع.

POST{host}/api/operations/merchant/payment/push/card/preview

عبر البطاقة — معاينة

التحقق من الدفع للتاجر بالبطاقة (Card to Wallet).

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	رقم هاتف التاجر.
`Amount`	decimal	body	مطلوب	مبلغ الدفع.

POST{host}/api/operations/merchant/payment/card

عبر البطاقة — تنفيذ

الدفع للتاجر بالبطاقة (Card to Wallet). مسار 3DS: تُرجِع الاستجابة `redirectionURL` الذي يجب فتحه.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	رقم هاتف التاجر. الصيغة: +212*********
`FirstName`	string	body	مطلوب	الاسم الشخصي لحامل البطاقة.
`LastName`	string	body	مطلوب	الاسم العائلي لحامل البطاقة.
`Cvv`	string	body	مطلوب	رمز CVV (3 أرقام).
`Amount`	decimal	body	مطلوب	مبلغ الدفع.
`Pan`	string	body	مطلوب	رقم البطاقة (PAN).
`ExpiryDate`	string	body	مطلوب	تاريخ الانتهاء بصيغة `YYMM`. مثال: `2608`.
`KeepAlive`	bool	body	مطلوب	ترميز البطاقة لإعادة استخدامها عبر نقطة نهاية البطاقة المرمَّزة.
`Currency`	string	body	اختياري	العملة. القيمة الافتراضية: MAD.
`3dSecure`	bool	body	اختياري	تفعيل 3D Secure. القيمة الافتراضية: true.
`FeesPercent`	decimal	body	اختياري	نسبة الرسوم المطبَّقة على الدافع.
`AllowInternationalCards`	bool	body	اختياري	قبول البطاقات الدولية.
`InternationalFeesPercent`	decimal	body	اختياري	نسبة الرسوم الخاصة بالبطاقات الدولية.
`AutoCapture`	bool	body	اختياري	تحصيل الدفع تلقائيًا.
`NotificationUrl`	string	body	اختياري	عنوان URL الذي يُشعَر عند انتهاء المعاملة (نجاح/فشل).
`AcceptUrl`	string	body	اختياري	عنوان URL لإعادة التوجيه عند نجاح 3DS.
`CardName`	string	body	اختياري	تسمية البطاقة (للترميز).
`ExternalReference`	string	body	اختياري	المرجع الخارجي للتاجر.

ملاحظات

•بعد مصادقة 3D Secure، يُعاد توجيه المستخدم إلى acceptURL أو declineURL حسب النتيجة.
•يتضمن عنوان URL لإعادة التوجيه المعاملات التالية: RESPONSE_CODE (0 = نجاح، وأي قيمة أخرى = فشل)، وREASON_CODE (سبب مقروء: SUCCESS، DECLINED…) وOPERATION (نوع العملية، مثال: PAYMENT).
•تحققوا من RESPONSE_CODE وREASON_CODE عند استلام إعادة التوجيه لتحديد الإجراء التالي في تطبيقكم.

POST{host}/api/operations/merchant/payment/tokenized/card/{cardId}

عبر بطاقة مرمَّزة — تنفيذ

الدفع للتاجر عبر بطاقة سبق ترميزها (`KeepAlive = true`). رمز CVV هو الوحيد المطلوب.

Parameter	Type	In	مطلوب	Description
`cardId`	int	path	مطلوب	معرّف البطاقة المرمَّزة.
`PhoneNumber`	string	query	مطلوب	رقم هاتف التاجر. الصيغة: +212*********
`Cvv`	string	body	مطلوب	رمز CVV (3 أرقام).
`Amount`	decimal	body	مطلوب	مبلغ الدفع.

ملاحظات

•بنية الاستجابة نفسها كما في "الدفع للتاجر بالبطاقة — تنفيذ".
•بعد مصادقة 3D Secure، يُعاد توجيه المستخدم إلى acceptURL أو declineURL حسب النتيجة.
•يتضمن عنوان URL لإعادة التوجيه المعاملات التالية: RESPONSE_CODE (0 = نجاح، وأي قيمة أخرى = فشل)، وREASON_CODE (سبب مقروء) وOPERATION.

GET{host}/api/operations/merchant/qrcode/static

توليد رمز QR ثابت

توليد رمز QR ثابت لتاجر (دون مبلغ مضمَّن). يُدخل العميل المبلغ عند الدفع.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	رقم هاتف التاجر.
`MaskedNumber`	bool	query	اختياري	إخفاء رقم التاجر في محتوى رمز QR. مثال: +2126######74

POST{host}/api/operations/merchant/qrcode

توليد رمز QR ديناميكي

توليد رمز QR ديناميكي بمبلغ ثابت ومرجع فريد.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	رقم هاتف التاجر.
`MaskedNumber`	bool	query	اختياري	إخفاء رقم التاجر.
`Amount`	decimal	body	مطلوب	المبلغ الثابت لرمز QR.

ملاحظات

•رمز QR الثابت (GET): دون مبلغ مضمَّن، يُدخل العميل المبلغ عند الدفع.
•رمز QR الديناميكي (POST): مبلغ ثابت مضمَّن، ومرجع فريد `qrCodeReference`.

الاسترجاع ChargeBack

POST{host}/api/operations/chargeback/preview

معاينة

التحقق من إمكانية تنفيذ عملية استرجاع.

Parameter	Type	In	مطلوب	Description
`SourcePhoneNumber`	string	body	مطلوب	رقم هاتف العميل المُصدِر. الصيغة: +212*********
`Amount`	decimal	body	مطلوب	مبلغ الاسترجاع.
`Description`	string	body	مطلوب	سبب الاسترجاع.
`DestinationPhoneNumber`	string	body	مطلوب	رقم هاتف المستلِم. الصيغة: +212*********
`OriginalOperationId`	int	body	مطلوب	معرّف العملية الأصلية موضوع الاسترجاع.

POST{host}/api/operations/chargeback

تنفيذ

تنفيذ عملية استرجاع.

Parameter	Type	In	مطلوب	Description
`SourcePhoneNumber`	string	body	مطلوب	رقم هاتف العميل المُصدِر.
`Amount`	decimal	body	مطلوب	مبلغ الاسترجاع.
`Description`	string	body	مطلوب	سبب الاسترجاع.
`DestinationPhoneNumber`	string	body	مطلوب	رقم هاتف المستلِم.
`OriginalOperationId`	int	body	مطلوب	معرّف العملية الأصلية.

عمليات الطلب

POST{host}/api/operations/cashin/request

طلب إيداع CashIn

طلب عملية إيداع CashIn. يولّد مرجعًا فريدًا تنتهي صلاحيته مع الوقت.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	body	مطلوب	رقم هاتف العميل.
`Amount`	decimal	body	مطلوب	مبلغ الإيداع CashIn.

ملاحظات

•operationType: 1 = CashIn، 2 = CashOut
•operationStatus: 1 = open، 2 = completed، 3 = failed، 4 = canceled

POST{host}/api/operations/fatourati/cashin/request

طلب إيداع CashIn (Fatourati)

بدء عملية إيداع CashIn عبر المزوّد Fatourati. نقطة نهاية مخصصة — Fatourati مزوّد خاص له مسار توليد مراجع خاص به (بادئة FATREF-). استخدموا هذا المسار المخصص بدلًا من نقطة نهاية cashin القياسية؛ فقد يختلف سلوك توليد المرجع وقواعد انتهاء الصلاحية.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	body	مطلوب	رقم هاتف العميل. بالنسبة للوكيل الرئيسي، استبدلوا phoneNumber برمز الوكيل (PhoneNumber => Code).
`Amount`	decimal	body	مطلوب	المبلغ المراد إيداعه. يجب أن يكون قيمة رقمية موجبة.
`Description`	string	body	اختياري	حقل نصي حر يصف الغرض من العملية.
`FeesPercent`	decimal	body	اختياري	نسبة الرسوم المطبَّقة (كما هو مبيَّن في مثال الوثائق).

ملاحظات

•نقطة نهاية مخصصة: لدى Fatourati مسار توليد مراجع خاص به (بادئة FATREF-)، مختلف عن مسار CashIn القياسي.
•type (operationType): 1 = CashIn، 2 = CashOut
•status (operationStatus): 1 = open، 2 = completed، 3 = failed

POST{host}/api/operations/cashout/request

طلب سحب CashOut

طلب عملية سحب CashOut. يولّد مرجعًا فريدًا تنتهي صلاحيته مع الوقت.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	body	مطلوب	رقم هاتف العميل.
`Amount`	decimal	body	مطلوب	مبلغ السحب CashOut.

الاطلاع على العمليات

GET{host}/api/operations

حسب العميل

الحصول على قائمة عمليات عميل محدد.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	رقم هاتف العميل.
`PageSize`	int	query	اختياري	عدد النتائج في الصفحة. القيمة الافتراضية: 10.
`PageNumber`	int	query	اختياري	رقم الصفحة. القيمة الافتراضية: 1.
`OperationType`	list int	query	اختياري	1=CASHIN, 2=CASHOUT, 3=TRANSFER, 5=MOBILE_PAYMENT, 7=PAYMENT_REFUND, 9=BANK_TRANSFER, 10=RECHARGE, 12=CHARGEBACK, 24=CARD_PAYMENT, 25=BILL_PAYMENT
`TransactionStatus`	int	query	اختياري	1=OPEN, 2=COMPLETED, 3=FAILED, 4=CANCELED
`Sens`	int	query	اختياري	1=CREDIT, 2=DEBIT
`From`	datetime	query	اختياري	تاريخ/وقت بداية التصفية.
`To`	datetime	query	اختياري	تاريخ/وقت نهاية التصفية.

ملاحظات

•collection: قائمة العمليات مقسّمة على صفحات.
•count: العدد الإجمالي للعمليات المطابقة لمعايير التصفية.
•accountNumber: يمكن أن يكون رقم هاتف أو RIB أو accountId.

GET{host}/api/operations/{id}

حسب المعرّف

الحصول على عملية محددة عبر معرّفها.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	رقم هاتف العميل.
`Id`	int	route	مطلوب	معرّف العملية.

ملاحظات

•operationId: معرّف العملية الشاملة.
•transactionId: معرّف المعاملة الرئيسية (يمكن لعملية واحدة أن تولّد عدة معاملات: خصم المُرسِل، إضافة للمستلِم، رسوم، إلخ).
•transactionReference: مرجع المعاملة الرئيسية.
•amount: المبلغ الأولي.
•totalAmount: المبلغ بعد تطبيق الرسوم والعمولات.

GET{host}/api/operations/all

الكل (حسب الشريك)

الحصول على قائمة جميع العمليات حسب الشريك.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	رقم هاتف العميل. الصيغة: +212*********
`PageSize`	int	query	اختياري	عدد النتائج في الصفحة. القيمة الافتراضية: 10.
`PageNumber`	int	query	اختياري	رقم الصفحة (يبدأ من 1). القيمة الافتراضية: 1.
`OperationType`	list int	query	اختياري	التصفية حسب نوع العملية.
`TransactionStatus`	int	query	اختياري	التصفية حسب حالة المعاملة.
`Sens`	int	query	اختياري	1 = CREDIT، 2 = DEBIT.
`From`	datetime	query	اختياري	العمليات ابتداءً من تاريخ/وقت.
`To`	datetime	query	اختياري	العمليات حتى تاريخ/وقت.

GET{host}/api/operations/c-request-idقريباً

الاطلاع على عملية عبر C-Request-Id

الحصول على عملية عبر C-Request-Id الخاص بها. سيتوفر في الإصدار القادم.

لا توجد معاملات (parameters) مطلوبة.

ردّ المبلغ

POST{host}/api/operations/refund/preview

معاينة

التحقق من إمكانية ردّ المبلغ بعد دفعة لتاجر.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	body	مطلوب	رقم هاتف العميل المراد ردّ المبلغ له.
`OperationId`	int	body	مطلوب	معرّف العملية المراد ردّ مبلغها.
`RefundAmount`	decimal	body	مطلوب	مبلغ الردّ.
`OrderId`	string	body	مطلوب	قيمة OrderId الأصلية من paymentGateway.
`TransactionTrackId`	string	body	مطلوب	قيمة TransactionTrackId الأصلية من paymentGateway.

POST{host}/api/operations/refund

تنفيذ

ردّ المبالغ للعملاء بعد دفعة لتاجر.

Parameter	Type	In	مطلوب	Description
`phoneNumber`	string	body	مطلوب	رقم هاتف العميل.
`OperationId`	int	body	مطلوب	معرّف العملية المراد ردّ مبلغها.
`RefundAmount`	decimal	body	مطلوب	مبلغ الردّ.
`OrderId`	string	body	مطلوب	قيمة OrderId الأصلية.
`TransactionTrackId`	string	body	مطلوب	قيمة TransactionTrackId الأصلية.

المستفيد

إدارة مستفيدي العميل: عرض القائمة، إضافة، تعديل، وحذف. يمكن تحديد المستفيدين برقم الهاتف و/أو RIB.

GET{host}/api/customer/beneficiaries

الاطلاع على المستفيدين

الحصول على قائمة المستفيدين لعميل.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	رقم هاتف العميل.
`PageSize`	int	query	اختياري	عدد النتائج في الصفحة. القيمة الافتراضية: 10.
`PageNumber`	int	query	اختياري	رقم الصفحة. القيمة الافتراضية: 1.
`Search`	string	query	اختياري	التصفية بكلمة مفتاحية.
`From`	datetime	query	اختياري	تاريخ الإنشاء — البداية.
`To`	datetime	query	اختياري	تاريخ الإنشاء — النهاية.

POST{host}/api/customer/beneficiaries

إضافة مستفيد

إضافة مستفيد جديد. يجب توفير PhoneNumber أو RIB على الأقل.

Parameter	Type	In	مطلوب	Description
`PhoneNumber (query)`	string	query	مطلوب	رقم هاتف العميل (المالك).
`Name`	string	body	مطلوب	اسم المستفيد. حرفان على الأقل.
`PhoneNumber`	string	body	اختياري	رقم هاتف المستفيد. الصيغة: +212*********
`Rib`	string	body	اختياري	رقم RIB الخاص بالمستفيد. 24 رقمًا.
`Email`	string	body	اختياري	البريد الإلكتروني للمستفيد.

ملاحظات

•PhoneNumber أو RIB: يجب توفير أحدهما على الأقل.

PUT{host}/api/customer/beneficiaries/{id}

تعديل مستفيد

تعديل مستفيد موجود.

Parameter	Type	In	مطلوب	Description
`PhoneNumber (query)`	string	query	مطلوب	رقم هاتف العميل (المالك).
`Id`	int	route	مطلوب	معرّف المستفيد المراد تعديله.
`Name`	string	body	مطلوب	اسم المستفيد. حرفان على الأقل.
`PhoneNumber (body)`	string	body	اختياري	رقم هاتف المستفيد.
`Rib`	string	body	اختياري	رقم RIB الخاص بالمستفيد. 24 رقمًا.
`Email`	string	body	اختياري	البريد الإلكتروني للمستفيد.

DELETE{host}/api/customer/beneficiaries/{Id}

حذف مستفيد

حذف مستفيد موجود.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	رقم هاتف العميل.
`Id`	int	route	مطلوب	معرّف المستفيد المراد حذفه.

البطاقات المرمَّزة

عرض وإدارة البطاقات البنكية المحفوظة (المرمَّزة) الخاصة بعميل.

GET{host}/api/customers/tokenized/cards

الاطلاع على بطاقات عميل

استرجاع جميع البطاقات المرمَّزة لعميل.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	رقم هاتف العميل.
`PageSize`	int	query	اختياري	عدد النتائج في الصفحة. القيمة الافتراضية: 10.
`PageNumber`	int	query	اختياري	رقم الصفحة. القيمة الافتراضية: 1.

ملاحظات

•customerBankCardId: معرّف فريد للبطاقة المحفوظة.
•maskedPan: رقم البطاقة المقنَّع (آخر 4 أرقام).
•issuer: اسم البنك المُصدر.
•scheme: شبكة البطاقة (Visa، Mastercard، إلخ).
•cardName: تسمية اختيارية يختارها العميل عند الترميز.

GET{host}/api/customers/tokenized/cards/{id}

الاطلاع على بطاقة عبر معرّفها

استرجاع بطاقة مرمَّزة محددة عبر معرّفها.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	رقم هاتف العميل.
`Id`	int	route	مطلوب	معرّف البطاقة.

DELETE{host}/api/customers/tokenized/cards/{id}قريباً

حذف بطاقة مرمَّزة

حذف بطاقة مرمَّزة. سيتوفر في الإصدار القادم.

لا توجد معاملات (parameters) مطلوبة.

وكلاء التجزئة

إدارة وكلاء التجزئة: عرض القائمة، إضافة، وتنفيذ عمليات الإيداع/السحب CashIn/CashOut بمرجع.

GET{host}/api/agents/retail

الاطلاع على وكلاء التجزئة

عرض قائمة جميع وكلاء التجزئة.

Parameter	Type	In	مطلوب	Description
`Code`	string	query	مطلوب	رمز الوكيل.
`PageSize`	int	query	اختياري	عدد النتائج في الصفحة. القيمة الافتراضية: 10.
`PageNumber`	int	query	اختياري	رقم الصفحة. القيمة الافتراضية: 1.
`From`	datetime	query	اختياري	إنشاء الوكيل — تاريخ البداية.
`To`	datetime	query	اختياري	إنشاء الوكيل — تاريخ النهاية.

GET{host}/api/agents/retail/{code}

الاطلاع على وكيل عبر رمزه

الحصول على وكيل تجزئة محدد عبر رمزه.

Parameter	Type	In	مطلوب	Description
`Code`	string	route	مطلوب	رمز الوكيل.

POST{host}/api/agents/retail

إضافة وكيل تجزئة

إضافة وكيل تجزئة جديد.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	body	مطلوب	رقم هاتف الوكيل. الصيغة: +212*********
`Name`	string	body	مطلوب	الاسم التجاري للوكيل.
`FirstName`	string	body	مطلوب	الاسم الشخصي. حرفان على الأقل.
`LastName`	string	body	مطلوب	الاسم العائلي. حرفان على الأقل.
`Cin`	string	body	مطلوب	رقم وثيقة الهوية.
`Address`	string	body	اختياري	عنوان الوكيل.
`Email`	string	body	اختياري	البريد الإلكتروني للوكيل.

PUT{host}/api/agents/retail/{code}قريباً

تعديل وكيل تجزئة

تعديل وكيل تجزئة. سيتوفر في الإصدار القادم.

لا توجد معاملات (parameters) مطلوبة.

GET{host}/api/operations/cashin/request

الاطلاع على إيداع CashIn عبر مرجع

استرجاع تفاصيل العملية المطلوبة باستخدام معرّف مرجع فريد.

Parameter	Type	In	مطلوب	Description
`Reference`	string	query	مطلوب	المرجع الفريد للعملية.

ملاحظات

•type: 1 = CashIn، 2 = CashOut
•status: 1 = open، 2 = completed، 3 = failed

POST{host}/api/operations/cashin/agent

تنفيذ إيداع CashIn عبر مرجع

تنفيذ عملية إيداع CashIn من طرف الوكيل.

Parameter	Type	In	مطلوب	Description
`Code`	string	body	مطلوب	رمز الوكيل الذي ينفّذ العملية.
`Reference`	string	body	مطلوب	معرّف مرجع العملية المراد استرجاعها.

GET{host}/api/operations/cashout/request

الاطلاع على سحب CashOut عبر مرجع

استرجاع تفاصيل عملية السحب CashOut عبر المرجع.

Parameter	Type	In	مطلوب	Description
`Reference`	string	query	مطلوب	المرجع الفريد للعملية.

POST{host}/api/operations/cashout/agent

تنفيذ سحب CashOut عبر مرجع

تنفيذ عملية سحب CashOut من طرف الوكيل.

Parameter	Type	In	مطلوب	Description
`Code`	string	body	مطلوب	رمز الوكيل الذي ينفّذ العملية.
`Reference`	string	body	مطلوب	معرّف مرجع العملية المراد استرجاعها.

الوكلاء الرئيسيون

الاطلاع على معلومات وكيل رئيسي.

GET{host}/api/agents/principal

الاطلاع على وكيل رئيسي عبر رمزه

الحصول على معلومات حساب وكيل رئيسي.

Parameter	Type	In	مطلوب	Description
`Code`	string	query	مطلوب	رمز الوكيل الرئيسي.

ملاحظات

•الاستجابة: كائن الوكيل Agent + كائن الحساب Account (الرصيد، RIB، المستوى، إلخ).

إدارة البطاقات

إصدار البطاقات وإدارتها: برامج البطاقات، الطلبات، البطاقات، ضبط الاستخدام والمعاملات.

⚠️ قسم بيتا. لا تزال وثائق البطاقات البنكية تمهيدية: ستُضاف نقاط النهاية الناقصة وقد تتضمن أخطاء. إذا واجهتم أي مشكلة، تواصلوا مع Hedi ZaZ (نائب رئيس BaaS) عبر WhatsApp: wa.me/212600000010

GET{host}/api/cards/programs

الاطلاع على البرامج

الحصول على قائمة البرامج المتاحة للشريك.

Parameter	Type	In	مطلوب	Description
`PageSize`	int	query	اختياري	عدد النتائج المعادة في كل صفحة. القيمة الافتراضية = 10.
`PageNumber`	int	query	اختياري	رقم صفحة النتائج المراد استرجاعها. يبدأ من 1. القيمة الافتراضية = 1.

ملاحظات

•collection : قائمة البرامج.
•count : عدد البرامج.

GET{host}/api/cards/programs/{id}قريباً

الاطلاع على برنامج عبر معرّفه

سيتوفر في الإصدار القادم.

Parameter	Type	In	مطلوب	Description
`Id`	int	route	مطلوب	معرّف برنامج البطاقات.

POST{host}/api/cards/applications

إضافة طلب بطاقة

إضافة طلب بطاقة جديد.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	رقم هاتف العميل. الصيغة: +212*********
`cardProgramId`	int	query	مطلوب	معرّف برنامج البطاقات.

ملاحظات

•لا يوجد محتوى للطلب حاليًا.

GET{host}/api/cards/applications

الاطلاع على الطلبات

الحصول على قائمة الطلبات حسب معايير التصفية.

Parameter	Type	In	مطلوب	Description
`PageSize`	int	query	اختياري	عدد النتائج المعادة في كل صفحة. القيمة الافتراضية = 10.
`PageNumber`	int	query	اختياري	رقم صفحة النتائج المراد استرجاعها. يبدأ من 1. القيمة الافتراضية = 1.
`Status`	int	query	اختياري	التصفية حسب الحالة: 1=Pending، 2=Validated، 3=Rejected.

ملاحظات

•collection : قائمة الطلبات.
•count : عدد الطلبات.
•CardApplicationStatus — 1: PENDING، 2: VALIDATED، 3: REJECTED.

GET{host}/api/cards/applications/customer

الاطلاع على طلبات عميل

الحصول على قائمة الطلبات حسب العميل.

Parameter	Type	In	مطلوب	Description
`PageSize`	int	query	اختياري	عدد النتائج المعادة في كل صفحة. القيمة الافتراضية = 10.
`PageNumber`	int	query	اختياري	رقم صفحة النتائج المراد استرجاعها. يبدأ من 1. القيمة الافتراضية = 1.

ملاحظات

•collection : قائمة الطلبات.
•count : عدد الطلبات.

PUT{host}/api/cards/applications/{id}/validate

قبول طلب

قبول طلب قائم قيد المعالجة.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	رقم هاتف العميل. الصيغة: +212*********
`Id`	int	route	مطلوب	معرّف الطلب المراد قبوله.

ملاحظات

•لا يوجد محتوى للطلب حاليًا.

PUT{host}/api/cards/applications/{id}/reject

رفض طلب

رفض طلب قائم قيد المعالجة.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	رقم هاتف العميل. الصيغة: +212*********
`Id`	int	route	مطلوب	معرّف الطلب المراد رفضه.

ملاحظات

•لا يوجد محتوى للطلب حاليًا.

GET{host}/api/cards

الاطلاع على البطاقات

الحصول على قائمة البطاقات حسب الشريك.

Parameter	Type	In	مطلوب	Description
`PageSize`	int	query	اختياري	عدد النتائج المعادة في كل صفحة. القيمة الافتراضية = 10.
`PageNumber`	int	query	اختياري	رقم صفحة النتائج المراد استرجاعها. يبدأ من 1. القيمة الافتراضية = 1.
`PhoneNumber`	string	query	اختياري	رقم هاتف العميل. الصيغة: +212*********
`CardProgramId`	int	query	اختياري	معرّف برنامج البطاقات.
`DeliveryStatusId`	int	query	اختياري	معرّف حالة التسليم (انظر قوائم تعداد البطاقات).
`CardStatusId`	int	query	اختياري	معرّف حالة البطاقة (انظر قوائم تعداد البطاقات).

ملاحظات

•collection : قائمة البطاقات.
•count : عدد البطاقات.
•CardType — 1: PHYSICAL، 2: VIRTUAL، 3: DIGITAL.
•DeliveryStatus — 1: PENDING، 2: SENT_TO_PERSONALIZATION، 3: READY_FOR_DELIVERY، 4: DELIVERED.
•CardStatus — 1: ISSUED، 2: ACTIVATED، 3: BLOCKED، 4: SUSPENDED، 5: EXPIRED، 6: CANCELLED.

GET{host}/api/cards/{id}

الاطلاع على بطاقة عبر معرّفها

الحصول على بطاقة محددة عبر معرّفها.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	رقم هاتف العميل. الصيغة: +212*********
`Id`	int	route	مطلوب	معرّف البطاقة.

PUT{host}/api/cards/{id}/{action}

إجراءات البطاقة

تنفيذ إجراءات على البطاقات الموجودة (تفعيل، حظر، تعليق، إلخ).

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	رقم هاتف العميل. الصيغة: +212*********
`Id`	int	route	مطلوب	معرّف البطاقة المراد تعديلها.

ملاحظات

•الإجراءات المتاحة ({action}):
•/activate — تفعيل البطاقة وجعلها جاهزة للاستخدام.
•/block — حظر البطاقة مؤقتًا عن أي معاملات.
•/suspend — تعليق استخدام البطاقة حتى إشعار آخر.
•/reactivate — إعادة تفعيل بطاقة سبق تعليقها.
•/cancel — إلغاء البطاقة وتعطيلها نهائيًا.
•/unblock-pin — إلغاء قفل الرمز السري PIN للبطاقة بعد محاولات فاشلة.
•/reset-pin — إعادة تعيين رمز سري PIN جديد للبطاقة وتوليده.
•الاستجابة: true / false.

PUT{host}/api/cards/{id}/services

ضبط استخدام البطاقة

تحديث خدمات البطاقة لضبط الاستخدام.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	رقم هاتف العميل. الصيغة: +212*********
`Id`	int	route	مطلوب	معرّف البطاقة المراد تعديلها.
`allowAtm`	bool	body	مطلوب	تفعيل أو تعطيل السحب من الصراف الآلي ATM للبطاقة.
`allowOnline`	bool	body	مطلوب	تفعيل أو تعطيل المعاملات عبر الإنترنت/التجارة الإلكترونية.
`allowPos`	bool	body	مطلوب	تفعيل أو تعطيل المدفوعات عبر نقاط البيع POS.
`contactlessEnabled`	bool	body	مطلوب	تفعيل أو تعطيل المدفوعات اللاتلامسية.

ملاحظات

•الاستجابة: true / false.

GET{host}/api/cards/{id}/transactions

الاطلاع على معاملات البطاقة

الحصول على معاملات البطاقة.

Parameter	Type	In	مطلوب	Description
`PageSize`	int	query	اختياري	عدد النتائج المعادة في كل صفحة. القيمة الافتراضية = 10.
`PageNumber`	int	query	اختياري	رقم صفحة النتائج المراد استرجاعها. يبدأ من 1. القيمة الافتراضية = 1.
`PhoneNumber`	string	query	اختياري	رقم هاتف العميل. الصيغة: +212*********
`From`	datetime	query	اختياري	التصفية من تاريخ.
`To`	datetime	query	اختياري	التصفية إلى تاريخ.
`Id`	int	route	مطلوب	معرّف البطاقة.

ملاحظات

•collection : قائمة المعاملات.
•count : عدد المعاملات.

المحاكاة (Sandbox)

نقاط نهاية محاكاة خاصة ببيئة sandbox فقط لإتمام عمليات الإيداع/السحب CashIn/CashOut بمرجع دون التعامل مع شبكة وكلاء حقيقية. استخدموها مع البطاقة التجريبية أدناه لتنفيذ مسار كامل من البداية إلى النهاية.

بطاقة ائتمان تجريبية

استخدموا بيانات هذه البطاقة التجريبية لاختبار الإيداع بالبطاقة في بيئة sandbox.

PAN

4918914107195005

CVV

123

تاريخ الانتهاء

08/26 (أو أي تاريخ مستقبلي)

رمز 3D Secure

555

POST{host}/api/simulate/network/operations/cashin200

محاكاة إيداع CashIn عبر الشبكة

تحاكي تنفيذ إيداع CashIn بمرجع (خطوة وكيل الشبكة). تُطلق حدث Webhook باسم `cashin.network.executed`.

Parameter	Type	In	مطلوب	Description
`reference`	string	body	مطلوب	المرجع الرقمي المُعاد عند إنشاء طلب الإيداع CashIn.

POST{host}/api/simulate/network/operations/cashout200

محاكاة سحب CashOut عبر الشبكة

تحاكي تنفيذ سحب CashOut بمرجع (خطوة وكيل الشبكة). تُطلق حدث Webhook باسم `cashout.network.executed`.

Parameter	Type	In	مطلوب	Description
`reference`	string	body	مطلوب	المرجع الرقمي المُعاد عند إنشاء طلب السحب CashOut.

أحداث Webhook

تتيح أحداث Webhook لمنصة ChariBaaS إشعار نظامكم بالأحداث (اكتمال عملية، تحديثات KYC، إلخ) في زمن شبه فوري. يعرض خادمكم نقطة نهاية HTTPS؛ ونرسل إليها أحداث JSON موقَّعة عبر POST.

طلب HTTP

POSThttps://{your-domain}/webhooks/chari

يمكنكم توفير أي نقطة نهاية أخرى.

Headers

Content-Type: application/jsonUser-Agent: Chari-BAAS-Webhook/1.0C-Webhook-Id: xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxxX-Api-Key: xxxxxxxx

•C-Webhook-Id: معرّف فريد لطلب Webhook، تولّده Chari.
•X-Api-Key: مفتاح سري يُستخدم للمصادقة لدى نظامكم (يجب أن تزوّدونا بهذا المفتاح).

الاستجابة المتوقعة: 200 OK خلال 5 ثوانٍ (بمحتوى فارغ). في حال وجود خطأ في الأعمال أو إخلال بالعقد مرسَل من طرفنا، يُرجى إرجاع خطأ 400 مع وصف للمشكلة. أي استجابة غير 2xx تؤدي إلى إعادة المحاولة.

خصائص body الحدث

Propriétés communes

Property	Type	مطلوب	Description
`WebhookId`	string	مطلوب	معرّف Webhook.
`EventId`	string	مطلوب	نوع الحدث. مثال: bank-transfer.initiated
`CRequestId`	string	مطلوب	معرّف التتبّع المستلَم من الشريك.
`OperationId`	int	مطلوب	معرّف العملية المنفَّذة (قد يكون 0 إذا لم تُنشأ أي عملية).
`TransactionId`	int	اختياري	معرّف المعاملة الرئيسية.
`OperationType`	int	مطلوب	رمز نوع العملية (انظر الأنواع).
`OperationStatus`	int	مطلوب	1 = Open, 2 = Completed, 3 = Failed, 4 = Canceled
`CreatedAt`	date	مطلوب	تاريخ بدء المعالجة.
`ExecutedAt`	date	مطلوب	تاريخ تنفيذ العملية.
`Amount`	decimal	مطلوب	مبلغ العملية.
`FeeAmount`	decimal	مطلوب	مبلغ الرسوم.
`PrimaryAccountNumber`	string	مطلوب	رقم هاتف المُرسِل.
`SecondaryAccountNumber`	string	اختياري	رقم هاتف المستلِم.
`Method`	string	اختياري	الطريقة: Card / Agent / Network

Spécifique Cash-in Card

Property	Type	مطلوب	Description
`CustomData`	string	اختياري	بيانات مخصصة يوفّرها الشريك (بحد أقصى 128 حرفًا).
`GatewayTrackId`	string	اختياري	Gateway Transaction Track Id.
`GatewayOrderId`	string	اختياري	Gateway Transaction Order Id.
`GatewayReferenceId`	string	اختياري	Gateway Transaction Reference Id.

Spécifique virement bancaire

Property	Type	مطلوب	Description
`BankTransferBeneficiaryName`	string	اختياري	اسم المستفيد للتحويلات البنكية.

Cash-in / Cash-out (référence réseau)

Property	Type	مطلوب	Description
`NetworkName`	string	اختياري	اسم الشبكة للعمليات عبر الشبكة.
`Reference`	string	اختياري	مرجع العملية المنفَّذة بمرجع.

سياسة إعادة المحاولة

Backoff:دقيقة، 5 دقائق، 30 دقيقة، 60 دقيقة، ثم كل 6 ساعات حتى 72 ساعة إجمالًا.

Stop:عند أول استجابة 200.

Dead letter:بعد 72 ساعة يُوسَم بأنه متعذّر التسليم.

الأحداث

Event ID	Description
`customer.level.updated`	تحديث مستوى حساب العميل
`cashin.card.authorized`	قبول إيداع CashIn بالبطاقة
`payment.card.authorized`	قبول الدفع بالبطاقة
`payment.received`	استلام التاجر للدفعة
`bank-transfer.initiated`	إرسال التحويل البنكي
`bank-transfer.completed`	اكتمال التحويل البنكي (تمت تسويته أو رُفض أو أُعيد — راجعوا OperationStatus)
`bank-transfer.received`	استلام التحويل البنكي
`transfer.received`	استلام التحويل
`cashin.network.executed`	تنفيذ إيداع CashIn بمرجع
`cashout.network.executed`	تنفيذ سحب CashOut بمرجع

مثال body الحدث

التحويل البنكي

json

{
  "data": {
    "WebhookId": 12345,
    "CRequestId": "a4d1e0b5-9f6a-4c1d-bc7b-2d0a7f4b9b12",
    "OperationId": 924381,
    "OperationType": 5,
    "OperationStatus": 2,
    "CreatedAt": "2025-11-05T10:12:00Z",
    "ExecutedAt": "2025-11-05T10:12:22Z",
    "Amount": 25000.00,
    "FeeAmount": 350.00,
    "CustomData": "{\"note\":\"Salary for October\"}",
    "PrimaryAccountNumber": "+212711111111",
    "SecondaryAccountNumber": "+212722222222",
    "Method": "BankTransfer",
    "Reference": "BANK-REF-9FJ2X7",
    "BankTransferBeneficiaryName": "Aminata Diop"
  }
}

الإيداع بالبطاقة CashIn

json

{
  "data": {
    "WebhookId": 12346,
    "CRequestId": "7b8c9f1a-15da-4e1c-8c3b-3a2bd0ed5e6f",
    "OperationId": 563210,
    "OperationType": 1,
    "OperationStatus": 2,
    "CreatedAt": "2025-11-05T09:41:00Z",
    "ExecutedAt": "2025-11-05T09:41:18Z",
    "Amount": 10000.00,
    "FeeAmount": 150.00,
    "CustomData": "ref12345",
    "PrimaryAccountNumber": "+212711111111",
    "Method": "Card",
    "GatewayTrackId": "83c1d1c7",
    "GatewayOrderId": "20251105_00045",
    "GatewayReferenceId": "6f92b0aa"
  }
}

صيغة الاستجابة

تُغلَّف جميع استجابات API داخل كائن `data`. تُعاد ترويسة C-Request-Id التي أرسلتموها في الاستجابة.

Header C-Request-Id

تدعم واجهتنا البرمجية ترويسة C-Request-Id لتمكين الشبكات من تتبّع الطلبات بكفاءة. يمكنكم إدراج C-Request-Id فريد في ترويسات الطلب، وسيُعاد في الاستجابة.

تعبئة رصيد الاتصالات

توفّر واجهة Telco API واجهة موحّدة وآمنة لخدمات تعبئة رصيد الهاتف المحمول المدفوع مسبقًا. وتتيح خدمتين: استرجاع كتالوج منتجات التعبئة المتاحة، وإطلاق تعبئة لرقم هاتف معيّن وعرض مختار، مع تحقق فوري. المشغّلون المدعومون في المغرب: اتصالات المغرب (IAM) وOrange وInwi.

POST{host}/api/services/telco/catalog/b2b

استرجاع الكتالوج

الحصول على قائمة منتجات وعروض التعبئة المتاحة لرقم هاتف ومشغّل معيّنين.

Parameter	Type	In	مطلوب	Description
`RecipientPhoneNumber`	string	body	مطلوب	رقم هاتف العميل، بالصيغة المطلوبة: +212*********.
`Amount`	int	body	مطلوب	القيمة النقدية للمعاملة. يجب أن تكون قيمة رقمية موجبة.
`Operator`	int	body	مطلوب	المشغّل: 1 = اتصالات المغرب، 2 = Orange، 3 = Inwi.

ملاحظات

•تتضمن المصفوفة data قائمة المنتجات المتاحة للمشغّل المطلوب.
•استخدموا productCode في نقطة نهاية recharge لاختيار العرض.

POST{host}/api/services/telco/recharge/b2b

طلب تعبئة

بدء تعبئة رصيد هاتف محمول لرقم هاتف معيّن وعرض مختار، مع تحقق فوري وتتبّع للمعاملة.

Parameter	Type	In	مطلوب	Description
`RecipientPhoneNumber`	string	body	مطلوب	رقم هاتف العميل، بالصيغة المطلوبة: +212*********.
`Amount`	int	body	مطلوب	القيمة النقدية للمعاملة. يجب أن تكون قيمة رقمية موجبة.
`Operator`	int	body	مطلوب	المشغّل: 1 = اتصالات المغرب، 2 = Orange، 3 = Inwi.
`ProductCode`	int	body	مطلوب	رمز المنتج المتاح، المُعاد من نقطة نهاية الكتالوج.
`Code`	string	body	مطلوب	رمز الوكيل الرئيسي — الحساب الذي سيُخصم منه. توفّره Chari بعد تفعيل حساب الشريك الخاص بكم.
`RechargeType`	int	body	مطلوب	نوع التعبئة: 0 = كلاسيكية، 1 = منتج.

ملاحظات

•المشغّلون الثلاثة مدعومون جميعًا: 1 = اتصالات المغرب، 2 = Orange، 3 = Inwi.
•Code هو رمز الوكيل الرئيسي (الحساب المخصوم)، توفّره Chari بعد تفعيل حساب الشريك.
•operationType: القيمة 10 (انظر جدول "الأنواع والمراجع").

القسائم

توفّر واجهة Voucher API واجهة موحّدة وآمنة لإصدار القسائم الرقمية وإدارتها واستخدامها داخل منظومة BaaS: توزيع القيمة والخدمات المدفوعة مسبقًا (بطاقات الهدايا، تعبئة الألعاب، إلخ). يتبع مسار الشراء نموذج معاينة/تأكيد.

GET{host}/api/vouchers/articles

استرجاع الكتالوج (المقالات)

استرجاع الكتالوج الحالي: قائمة مقالات القسائم لعلامة تجارية معيّنة.

Parameter	Type	In	مطلوب	Description
`phoneNumber`	string	query	مطلوب	رقم هاتف العميل، بالصيغة +212*********.
`brandId`	int	query	مطلوب	معرّف العلامة التجارية. يجب أن يكون قيمة رقمية موجبة.
`page`	int	query	اختياري	رقم صفحة النتائج المراد استرجاعها. يبدأ من 1. القيمة الافتراضية: 1.
`take`	int	query	اختياري	عدد النتائج المعادة في كل صفحة. القيمة الافتراضية: 10.

GET{host}/api/vouchers/brands

استرجاع العلامات التجارية

استرجاع القائمة الحالية لعلامات القسائم التجارية المتاحة.

Parameter	Type	In	مطلوب	Description
`phoneNumber`	string	query	مطلوب	رقم هاتف العميل، بالصيغة +212*********.
`brandId`	int	query	مطلوب	معرّف العلامة التجارية. يجب أن يكون قيمة رقمية موجبة.
`page`	int	query	اختياري	رقم صفحة النتائج المراد استرجاعها. يبدأ من 1. القيمة الافتراضية: 1.
`take`	int	query	اختياري	عدد النتائج المعادة في كل صفحة. القيمة الافتراضية: 10.

GET{host}/api/vouchers/brands/{id}

الاطلاع على علامة تجارية عبر معرّفها

الحصول على علامة تجارية محددة عبر معرّفها.

Parameter	Type	In	مطلوب	Description
`id`	int	path	مطلوب	معرّف العلامة التجارية.
`phoneNumber`	string	query	مطلوب	رقم هاتف العميل، بالصيغة +212*********.

GET{host}/api/vouchers/{id}/articles

الاطلاع على القسائم عبر معرّف العلامة التجارية

الحصول على قائمة القسائم المرتبطة بعلامة تجارية، عبر معرّف العلامة.

Parameter	Type	In	مطلوب	Description
`id`	int	path	مطلوب	معرّف العلامة التجارية.
`phoneNumber`	string	query	مطلوب	رقم هاتف العميل، بالصيغة +212*********.

ملاحظات

•تعكس الاستجابة كائن علامة تجارية Brand، كما هو معرَّف في الوثائق المصدر.

POST{host}/api/operations/voucher/preview

شراء قسيمة — معاينة

التحقق من إمكانية تنفيذ عملية شراء القسيمة (المبلغ، الرسوم) قبل التأكيد.

Parameter	Type	In	مطلوب	Description
`CustomerPhoneNumber`	string	body	مطلوب	رقم هاتف العميل، بالصيغة +212*********.
`DestinationPhoneNumber`	string	body	مطلوب	رقم هاتف المستلِم، بالصيغة +212*********.
`BeneficiaryName`	string	body	مطلوب	حقل نصي حر يصف اسم المستفيد.
`ProviderSkuId`	string	body	مطلوب	معرّف المقال.
`ProviderId`	string	body	مطلوب	معرّف المزوّد الذي يوفّر القسيمة.

ملاحظات

•type: القيمة 23 (انظر جدول "الأنواع والمراجع").
•feesAmount هو الرسوم؛ وtotalAmount هو المبلغ الإجمالي شامل الضريبة.

POST{host}/api/operations/voucher/confirm

شراء قسيمة — تأكيد

تنفيذ عملية شراء القسيمة. تُرجِع رمز القسيمة وتفاصيلها.

Parameter	Type	In	مطلوب	Description
`customerPhoneNumber`	string	body	مطلوب	رقم هاتف العميل، بالصيغة +212*********.
`destinationPhoneNumber`	string	body	مطلوب	رقم هاتف المستلِم، بالصيغة +212*********.
`beneficiaryName`	string	body	مطلوب	حقل نصي حر يصف اسم المستفيد.
`providerSkuId`	string	body	مطلوب	معرّف المقال.
`providerId`	string	body	مطلوب	معرّف المزوّد الذي يوفّر القسيمة.

ملاحظات

•type / operation.operationType: القيمة 23 (انظر جدول "الأنواع والمراجع").
•يتضمن operation.code رمز القسيمة المراد مشاركته مع المستفيد.
•cashBack: مبلغ استرداد نقدي اختياري.

دفع الفواتير

تتيح وحدة دفع الفواتير للمستخدمين النهائيين تسديد الفواتير لدى الدائنين المرتبطين بشبكة Fatourati في المغرب (RADEEMA وLYDEC وIAM وTGR وAMENDIS وREDAL وغيرهم من مصدري فواتير Fatourati). يتبع المسار 5 خطوات: عرض قائمة الدائنين، عرض مستحقات الدائن، جلب نموذج التعريف الديناميكي، استرجاع غير المدفوعات، ثم تأكيد الدفع. نموذج بدائن واحد (لا توجد سلة متعددة المصدرين)؛ الدفع الجزئي مدعوم. عنوان بيئة sandbox: https://sandbox.charimoney.com.

GET{host}/api/fatourati/creanciers

قائمة الدائنين

تُرجِع قائمة الدائنين النشطين المتاحين للشريك عبر ChariBaaS (مصفّاة حسب عقد الشريك وإعدادات Fatourati). ولأن الاستجابة مستقرة نسبيًا، فإن تخزينها المؤقت لعدة ساعات لدى الشريك مقبول.

لا توجد معاملات (parameters) مطلوبة.

ملاحظات

•codeRetour: 000 = ACCEPTE (نجاح)، 908 = خطأ تقني لدى Fatourati.
•الاستجابة مستقرة نسبيًا: تخزينها المؤقت لبضع ساعات لدى الشريك مقبول.

GET{host}/api/fatourati/creances?creancierId={creancierId}

قائمة مستحقات دائن

تُرجِع قائمة المستحقات النشطة المعروضة من طرف دائن معيّن (يقابل المستحق نوع خدمة: فاتورة، تعبئة، ضريبة…). قد يعرض دائن واحد عدة مستحقات.

Parameter	Type	In	مطلوب	Description
`creancierId`	string	query	مطلوب	معرّف الدائن المُحصَّل عليه عبر GET /creanciers (4 أرقام).

ملاحظات

•codeRetour: 000 = ACCEPTE، 104 = دائن غير موجود أو غير نشط، 908 = خطأ تقني.

GET{host}/api/fatourati/form?creancierId={creancierId}&creanceId={creanceId}

الاطلاع على نموذج التعريف

تُرجِع مخطط نموذج التعريف الديناميكي بالعميل للزوج (دائن، مستحق): الحقول المراد عرضها (التسمية، النوع، الصيغة، الحجم، القيود). يجب على الشريك بناء شاشة الإدخال الخاصة به من هذه الاستجابة (لا نموذج مكتوب يدويًا) للبقاء متوافقًا مع الدائنين الجدد المضافين إلى شبكة Fatourati.

Parameter	Type	In	مطلوب	Description
`creancierId`	string	query	مطلوب	معرّف الدائن (4 أرقام).
`creanceId`	string	query	مطلوب	معرّف المستحق، مكوَّن دائمًا من خانتين (مثال: 01).

ملاحظات

•typeChamp: text، select، password، libelle. الحقل من نوع libelle نص ثابت (غير قابل للتحرير) ويجب ألّا يُرسَل أبدًا في CreancierVals.
•formatChamp: 1 = سلسلة نصية، 2 = عدد صحيح، 3 = عدد حقيقي. contrainte: 0 = اختياري، 1 = مطلوب.
•refTxFatourati: 1 = استدعاء /impayes (القيمة الافتراضية)، 2 = sendRecharge (ربما أصبحت متقادمة).
•رموز الإرجاع: 000 = ACCEPTE (نجاح)، 103 = المستحق/الخدمة غير نشط لدى الدائن المختار، 104 = دائن غير موجود، 908 = خطأ تقني لدى Fatourati.

POST{host}/api/fatourati/impayes?creancierId={creancierId}&creanceId={creanceId}

استرجاع غير المدفوعات

يُرسِل بيانات تعريف العميل (المُدخلة عبر /form) ويسترجع غير المدفوعات الخاصة بالعميل لدى الدائن. يفتح هذا الاستدعاء المعاملة (حالة EN_ATTENTE) ويُرجِع refTxFatourati لاستخدامه مع /confirm. يبقى الربط صالحًا لمدة 7 أيام تقويمية (مهلة Fatourati).

Parameter	Type	In	مطلوب	Description
`creancierId`	string	query	مطلوب	معرّف الدائن (4 أرقام).
`creanceId`	string	query	مطلوب	معرّف المستحق (خانتان).
`CreancierVals`	array	body	مطلوب	مصفوفة القيم المُدخلة من المستخدم: كائنات { nomChamp, valeurChamp } (باستثناء الحقول من نوع typeChamp=libelle).

ملاحظات

•تنتقل المعاملة إلى حالة EN_ATTENTE؛ احتفظوا بـ refTxFatourati من أجل /confirm. صالحة لمدة 7 أيام تقويمية.
•codeDevise: القيمة 504 = MAD.
•typeFrais: forfait، commission، forfait_facture. valeurFrais = النسبة المئوية × 100 (مثال: 1% → 100).
•typeArticle: 0 = مستحق، 1 = رسوم، 2 = إلزامي، 3 = رسوم تنبر.
•globalParams: المعاملات التقنية ذات التسمية libelle الفارغة (contrPaiement، isConfTO، isAnnul، rejoue، colAffiche) يجب ألّا تُعرض أبدًا على العميل.
•رموز الإرجاع الرئيسية: 000 = نجاح (EN_ATTENTE)، 103 = مستحق غير نشط، 104 = دائن غير موجود، 107 = لا توجد فاتورة للدفع، 109 = حقل مطلوب ناقص، 902/908/909/910/911 = أخطاء تقنية/اتصال.
•الوضع دون اتصال: يمكن أيضًا بدء دفعة عبر مرجع Fatourati ثابت من 13 رقمًا (4 للدائن + 2 للمستحق + 6 للفاتورة + 1 رقم تحقق)، يُمرَّر في CreancierVals.

POST{host}/api/fatourati/confirm?phoneNumber={phoneNumber}

تأكيد الدفع

يؤكد دفع مجموعة المقالات التي اختارها المستخدم النهائي. رمز الإرجاع 000 يعني تسوية فعلية لدى الدائن. يُحدَّد المستخدم النهائي برقم هاتفه لدى Chari Money (معامل الاستعلام phoneNumber).

Parameter	Type	In	مطلوب	Description
`phoneNumber`	string	query	مطلوب	رقم هاتف المستخدم النهائي لدى Chari Money، بالصيغة الدولية (مثال: +212670770743). يجب أن يطابق مستخدمًا موجودًا لدى Chari Money، وإلا تُرفض المعاملة قبل أي استدعاء لـ Fatourati.
`creancierId`	string	body	مطلوب	معرّف الدائن (نفس قيم /impayes).
`creanceId`	string	body	مطلوب	معرّف المستحق.
`refTxFatourati`	string	body	مطلوب	المرجع المُعاد من /impayes. يربط الاستدعاء بالمعاملة المفتوحة.
`CreancierVals`	array	body	مطلوب	إعادة مُثراة لحقول التعريف (libelle + nomChamp + valeurChamp).
`ListeArticleSelectionnes`	array	body	مطلوب	مجموعة جزئية من impayesParams اختارها المستخدم (idArticle، prixTTC، typeArticle، …).

ملاحظات

•codeRetour 000 = CONFIRME (تسوية فعلية). 301 = عولجت من قبل (تُعامَل كنجاح، اعرضوا الإيصال).
•السلوك غير المتزامن (القناة الرقمية): الرموز 908/909/910 ليست حالات فشل نهائية — تبقى المعاملة في حالة AUTORISE ويُبلَّغ عن حلّها النهائي (CONFIRME/ANNULE) عبر Webhook.
•يجب أن يظهر refReglement على الإيصال. numCRC / texteCRC (من params): تُعرض على الإيصال إن وُجدت.
•أحداث Webhook الخاصة بالوحدة: payment.confirmed وpayment.cancelled وpayment.refunded وpayment.failed — تُصدر للإبلاغ عن الحل النهائي (الحالات CONFIRME / ANNULE / REMBOURSE / FAILED).

الأنواع والمراجع

أنواع العمليات

ID	Code
1	CASHIN
2	CASHOUT
3	TRANSFER
5	MOBILE_PAYMENT
7	PAYMENT_REFUND
9	BANK_TRANSFER
10	RECHARGE
12	CHARGEBACK
23	VOUCHER
24	CARD_PAYMENT
25	BILL_PAYMENT

أنواع المعاملات

ID	Code
1	CASHIN
2	CASHOUT
3	TRANSFER
5	MOBILE_PAYMENT
6	TRANSACTION_FEES
7	PAYMENT_REFUND
9	CHARGEBACK
10	CHARGEBACK_CANCELLATION
16	BANK_TRANSFER
17	RECHARGE
18	CASHBACK
24	CARD_PAYMENT
25	BILL_PAYMENT

حالات العمليات

ID	Code	Description
1	OPEN	مفتوحة (دورة الحياة جارية)
2	COMPLETED	اكتملت بنجاح
3	FAILED	فشلت
4	CANCELED	أُلغيت

حالات المعاملات

ID	Code	Description
1	OPEN	مفتوحة (جارية)
2	COMPLETED	مكتملة
3	FAILED	فشلت
4	CANCELED	أُلغيت

اتجاه المعاملة (Sens)

ID	Code	Description
1	CREDIT	دائن (أموال واردة)
2	DEBIT	مدين (أموال صادرة)

حالات العميل

ID	Code	Description
0	NOT_EXISTS	الرقم غير موجود لدى ChariMoney
1	NOT_CONFIRMED	موجود لكنه غير مؤكَّد (لم يُدخل رمز OTP)
2	CONFIRMED	مؤكَّد ومسجَّل لدى Switch
3	ACTIVE	مسجَّل ونشِط وتم إنشاء الرمز السري PIN
4	LOCKED_TEMPORARY	مقفل مؤقتًا (محاولات مفرطة)
5	LOCKED	مقفل

مستويات الحساب

ID	Code	Description
1	LEVEL_1	المستوى 1 — الاسم + رقم هاتف صالح + رقم البطاقة الوطنية CIN. الحد: 1,000 MAD.
2	LEVEL_2	المستوى 2 — تحقق كامل من الهوية KYC (البطاقة الوطنية CIN + سيلفي أو مسح الوثيقة). الحد: 4,000 MAD.
3	LEVEL_3	المستوى 3 — هوية متحقَّق منها + مقابلة + ملف عميل رقمي. الحد: 20,000 MAD.
4	LEVEL_4	المستوى 4 — تحقق كامل من الهوية KYC + مقابلة + إثبات الدخل + إثبات العنوان. الحد: 100,000 MAD.
5	MERCHANT	التاجر — تحقق كامل من الشركة KYB + السجل التجاري IF/RC. الحد: قابل للتفاوض.

أنواع الوثائق

ID	Code	Description
1	IdentityCard	البطاقة الوطنية للتعريف
2	DrivingLicense	رخصة السياقة
3	Passport	جواز السفر
4	ResidencePermit	بطاقة الإقامة
5	ProofOfIncome	إثبات الدخل
6	ProofOfResidence	إثبات السكن
7	Selfie	سيلفي / صورة الوجه
8	CommercialRegister	السجل التجاري

رموز الأخطاء

رموز حالة HTTP

401 Unauthorizedبيانات المصادقة (API KEY) غير مصرَّح بها.

422 Unprocessableالخادم غير قادر على معالجة الطلب.

423 Lockedالوصول مقفل بالنسبة للعميل المعني.

400 Bad Requestخطأ خاص بالحالة مع رمز خطأ Chari.

صيغة استجابة الخطأ

json

{
  "errorCode": 20005,
  "errorDescription": "The specified user could not be found."
}

رموز أخطاء Chari

10xxxGénéral

Code	Message	نقاط النهاية (endpoints) ذات الصلة
10001	معاملات ناقصة.

20xxxClient

Code	Message	نقاط النهاية (endpoints) ذات الصلة
20000	صيغة رقم الهاتف غير صالحة.
20005	تعذّر العثور على المستخدم المحدد.
20006	المعاملات الأولية المقدَّمة غير صحيحة أو غير صالحة.
20007	رمز فئة التاجر (MCC) المقدَّم غير صحيح أو غير معروف.
20008	التسجيل مقفل مؤقتًا بسبب قيود أمنية أو تنظيمية.
20009	الطلب في انتظار التأكيد. يُرجى انتظار استكمال المعالجة.
20017	لا يوجد طلب معلّق مرتبط برقم الهاتف المقدَّم.

26xxxPIN / Authentification

Code	Message	نقاط النهاية (endpoints) ذات الصلة
26001	الرمز السري PIN المُدخل غير صحيح.
26004	تم بالفعل تعيين رمز سري PIN لهذه المحفظة.
26005	الرمز السري PIN المقدَّم لا يستوفي الصيغة المطلوبة (يجب أن يكون رقمًا من 4 خانات).

27xxxBénéficiaire

Code	Message	نقاط النهاية (endpoints) ذات الصلة
27000	المستفيد موجود بالفعل بنفس رقم الهاتف phoneNumber.
27001	المستفيد غير موجود.

32xxxKYC / Mise à niveau

Code	Message	نقاط النهاية (endpoints) ذات الصلة
32000	هناك طلب ترقية قيد المراجعة بالفعل لهذا الحساب.

البنية التحتية والأمن

البيئات

Sandbox

https://sandbox.charimoney.com

التطوير والاختبار. المعاملات محاكاة.

Production

Communiqué sur demande

معاملات حقيقية. تتطلب موافقة مسبقة.

إدارة مفاتيح API

سيُخصَّص لكم مفتاح API لكل بيئة (sandbox وproduction). يجب إدراج المفاتيح في الترويسة Chari-Api-Key لكل طلب.

إدراج عناوين IP والنطاقات في القائمة البيضاء

يجب مشاركة عناوين IP و/أو النطاقات التي ستُستخدم لاستهلاك واجهتنا البرمجية. لن يُسمح بالوصول إلى API إلا لعناوين IP/النطاقات المدرجة في القائمة البيضاء. إذا تغيّرت بنيتكم التحتية، حدّثوا قائمة عناوين IP/النطاقات لدى فريق الدعم.

كيفية إرسال عناوين IP / النطاقات

1قدّموا قائمة بعناوين IP العمومية أو النطاقات التي ستُستخدم للوصول إلى API.
2أرسلوا هذه المعلومات إلى فريق الدعم قبل الشروع في تكامل API.
3يجب الإبلاغ عن أي تغيير قبل 72 ساعة على الأقل حتى نتمكن من تحديث قواعدنا الأمنية.

الأمان والامتثال

•تتم مصادقة API باستخدام مفاتيح API.
•سترُفض الطلبات الواردة من عناوين IP/نطاقات غير مدرجة في القائمة البيضاء.
•إذا تعرّض مفتاح API للاختراق، يجب تدويره فورًا.
•قد يُطبَّق تحديد لمعدل الطلبات لمنع إساءة الاستخدام.
•تتطلب بيئة الإنتاج موافقة مسبقة واختبارات في بيئة sandbox.

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

1
طلب مفاتيح API
تواصلوا مع الدعم لاستلام مفاتيحكم المخصصة لبيئتَي sandbox وproduction.
2
تقديم عناوين IP/النطاقات
قدّموا قائمة عناوين IP العمومية أو النطاقات لإدراجها في القائمة البيضاء.
3
الاختبار في sandbox
نفّذوا جميع اختبارات التكامل في بيئة sandbox.
4
الانتقال إلى الإنتاج
بعد الموافقة، انتقلوا إلى الإنتاج بمفتاح API الخاص بالبيئة الحقيقية.

ستتوصلون بنموذج لملئه بالعناصر اللازمة.

وثائق API

البدء

Headers المصادقة

بطاقة ائتمان للاختبار (sandbox)

حزمة LLM والذكاء الاصطناعي

Postman Collection

سجل التغييرات

نظرة عامة — المحفظة الإلكترونية M-Wallet في المغرب

ما هو M-Wallet؟

المبادئ الأساسية

أنواع الحسابات

مستويات الحساب

مسرد المصطلحات

تسجيل العملاء

مسار تسجيل العميل

التحقق من الحالة لدى Chari

التحقق من الحالة لدى Switch

التسجيل

التأكيد

إعادة إرسال OTP

تسجيل الدخول بالرمز السري PIN

إنشاء الرمز السري PIN

تحديث الرمز السري PIN

إعادة تعيين الرمز السري PIN

الاطلاع على رصيد العميل

الاطلاع على معلومات العميل

إلغاء التسجيل

التحقق من الهوية KYC

مسار التحقق من الهوية KYC (ShareID)

مسار التكامل

المصادقة

التأكيد

رفع مستندات KYC للتاجر

العمليات

الإيداع بالبطاقة CashIn

مسار الإيداع بالبطاقة CashIn (3D Secure)

بطاقة ائتمان تجريبية

معاينة (عبر الهاتف)

تنفيذ (عبر الهاتف)

تنفيذ ببطاقة محفوظة

معاينة (عبر الوكيل)

تنفيذ (عبر الوكيل)

التحويل

مسار التحويل من محفظة إلى محفظة

معاينة

تنفيذ

التحويل البنكي

مسار التحويل البنكي

معاينة

تنفيذ

الدفع للتاجر

مسار الدفع للتاجر

عبر الهاتف — معاينة

عبر الهاتف — تنفيذ

عبر رمز QR — معاينة

عبر رمز QR — تنفيذ

عبر البطاقة — معاينة

عبر البطاقة — تنفيذ

عبر بطاقة مرمَّزة — تنفيذ

توليد رمز QR ثابت

توليد رمز QR ديناميكي

الاسترجاع ChargeBack

مسار الاسترجاع (Chargeback)

معاينة

تنفيذ

عمليات الطلب

مسار الإيداع/السحب بمرجع (CashIn/CashOut)

طلب إيداع CashIn

طلب إيداع CashIn (Fatourati)

طلب سحب CashOut

الاطلاع على العمليات

حسب العميل

حسب المعرّف

الكل (حسب الشريك)

الاطلاع على عملية عبر C-Request-Id

ردّ المبلغ

معاينة

تنفيذ

المستفيد

مسار إدارة المستفيدين