وثائق API

مرجع شامل لواجهة برمجة التطبيقات الخاصة بالبنية التحتية للتكنولوجيا المالية من Chari Money. ادمج الخدمات المالية في تطبيقاتك عبر نقاط نهاية (endpoints) قوية وآمنة.

البدء

الإصدار 2.3 · آخر تحديث 29 يوليوز 2026

مرحبًا بكم في الوثائق الرسمية لواجهة برمجة التطبيقات الخاصة بالبنية التحتية للتكنولوجيا المالية ChariBaaS من 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

انقر للنسخ

CVV

انقر للنسخ

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

انقر للنسخ — API: 2608 (أو أي تاريخ مستقبلي)

رمز 3D Secure

انقر للنسخ

جديد

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

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

OpenAPI 3.0JSON SchemaMermaidMarkdowncURL

تنزيل .zip

مرجع تفاعلي (Swagger UI)

تصفّحوا 114 عملية ومخططاتها في Swagger UI، مستضاف على هذا الموقع ومولَّد من واجهة الإنتاج.

فتح المرجع

مواصفة OpenAPI (Swagger)

مواصفة OpenAPI 3.0 لواجهة API الخاصة بالشركاء، مولَّدة من واجهة الإنتاج: 114 عملية خاصة بالشركاء، مخططات كاملة، جاهزة لـ Swagger UI أو Postman أو توليد العملاء.

تحميل OpenAPI

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

v2.3

2026-07-29

مواءمة مع واجهة API الإنتاجية مع الحفاظ على نطاق الشركاء. الجديد: دورة حياة الدفع التجاري بالبطاقة (capture، إلغاء التفويض، الاسترداد)، حالة الدفع QR بالمرجع، البطاقات المرمّزة لدى الوكلاء، وتوسيعات الفواتير (المفضلة، السجل، الإيصالات، المعاينة، حالة المرجع) وتعبئة الرصيد (تعبئة العميل، السجل، الكتالوج، التصدير) والقسائم (الكتالوج المحلي، المنتجات). إعادة مواءمة المسارات: /api/fatourati/* → /api/bills/*، نقل التعبئة B2B، معاملات البطاقات عبر /api/card-transactions، معاينة الدفع بالبطاقة، الوكيل الرئيسي بالرمز (path)، ترقية الحساب أصبحت PUT. تقسيم إجراءات البطاقة إلى 5 نقاط نهاية مخصصة. حذف نقاط النهاية الملغاة. إعادة مواءمة معاملات 19 بطاقة توثيق مع الإنتاج. مواصفة OpenAPI ومجموعة Postman قابلتان للتنزيل ومولَّدتان من واجهة الإنتاج؛ حزمة LLM v2.3.

نظرة عامة — المحفظة الإلكترونية 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	رمز آمن يُستخدم لمصادقة طلبات الشركاء إلى واجهة ChariBaaS API.
Webhook	استدعاء HTTP آلي يرسله النظام لإشعار الشركاء بتحديثات العمليات أو المعاملات.

أدلة التكامل

مسارات خطوة بخطوة حسب حالة الاستخدام، مركّبة من نقاط النهاية الموثقة أدناه: من الانطلاق في sandbox إلى دورة الدفع التجاري الكاملة.

البدء في بيئة sandbox: الوصول، التفعيلات، أولى الاستدعاءات

كل ما يجب الحصول عليه والتحقق منه قبل بدء التكامل: مفتاح API، الوحدات المفعّلة لحسابكم، رصيد اختباري. اتباع هذا الدليل يجنّبكم أكثر العوائق الزائفة شيوعًا (404 على وحدة غير مفعّلة، كتالوجات فارغة، محافظ غير موجودة).

المتطلبات المسبقة

•تواصل مع فريق Chari (يُسلَّم لكم نموذج التكامل التقني عند فتح الملف).

1
الحصول على الوصول إلى sandbox
املؤوا نموذج «الحصول على وصول sandbox» أسفل هذه الصفحة (رابط مباشر: ‎#sandbox-access). تتوصلون في المقابل بمفتاح API الخاص ببيئة sandbox (يُرسل عبر رابط آمن لاستخدام واحد) ودعوة إلى Partner Back Office. عنوان sandbox الأساسي هو https://sandbox.charimoney.com؛ ويُبلَّغ عنوان الإنتاج بعد التحقق من اختباراتكم.
2
التحقق من المفتاح: أول استدعاء
تحمل كل الطلبات الترويسة Chari-Api-Key (إلزامية) ويُستحسن إضافة C-Request-Id فريد (UUID v4) للتتبع. اختبروا مفتاحكم باستدعاء لا يتطلب أي شرط مسبق:
bash
```
curl -X 'GET' \
  'https://sandbox.charimoney.com/api/customers/status?phoneNumber=+2126xxxxxxxx' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID'
```
الاستجابة
json
```
{
  "data": {
    "status": 0,
    "message": "Not exists"
  }
}
```
check-status-chari
3
طلب تفعيل الوحدات اللازمة
تُفعِّل فرق Chari بعض الوحدات لحساب الشريك عند الطلب: تعبئة رصيد الاتصالات، دفع الفواتير، القسائم (كتالوج مجهّز في sandbox)، بوابة البطاقات، ومفتاح webhook (X-Api-Key) لاستقبال الإشعارات. كما تحدّد نطاقات (scopes) مفتاح API نقاط النهاية المتاحة. اطلبوا التفعيلات الموافقة لحالات الاستخدام لديكم فور فتح الحساب — أعراض الوحدة غير المفعّلة مدرجة أدناه.
Erreur métier — تعبئة رصيد الاتصالات: الخدمة غير مفعّلة لحسابكم — اطلبوا تفعيل المشغّلين.
200/204 vide — كتالوج القسائم فارغ: يجب أن تجهّز Chari العلامات التجارية في sandbox.
403 — نطاقات ناقصة — تتطلب نقطة النهاية نطاقًا لا يحمله مفتاحكم (مثل operations:admin-read على GET /api/operations/all).
4
طلب رصيد اختباري
لتنفيذ عمليات مدينة (تحويلات، دفع فواتير، تعبئات، قسائم) يجب تزويد وكيلكم الرئيسي بالرصيد. زوّدوا جهة الاتصال في Chari برمز وكيلكم الرئيسي (ومعرّف الشريك) لإضافة رصيد اختباري في sandbox.
get-principal-agent
5
استخدام البطاقة التجريبية (3D Secure)
تستخدم الإيداعات والمدفوعات بالبطاقة في sandbox البطاقة التجريبية الموثقة أعلى هذه الصفحة: PAN 4918914107195005، CVV 123، انتهاء الصلاحية 08/26 (أو أي تاريخ مستقبلي)، رمز 3DS هو 555.
6
تجهيز أدوات التكامل
حمّلوا من هذه الصفحة مواصفة OpenAPI (مولَّدة من الإنتاج)، ومجموعة Postman (114 طلبًا جاهزًا مع المتغيرين {{host}} و{{apiKey}})، وحزمة LLM إن كنتم تعملون بمساعدات الذكاء الاصطناعي. وهي متطابقة تمامًا مع هذا التوثيق.
7
التحضير للانتقال إلى الإنتاج
بعد التحقق من اختباراتكم في sandbox: قدّموا قائمة عناوين IP العمومية أو النطاقات لإدراجها في القائمة البيضاء، ثم تتوصلون بمفتاح API الخاص بالإنتاج وعنوان البيئة الحية. المفاتيح خاصة بكل بيئة — لا تعيدوا أبدًا استخدام مفتاح sandbox في الإنتاج.

إنشاء محفظة عميل وتفعيلها من البداية إلى النهاية

المسار الكامل لمحفظة M-Wallet لعميل: التحقق من حالة الرقم، تسجيل العميل (walletType)، تأكيد رمز OTP (مع autoActivate أو بدونه)، إنشاء الرمز السري PIN، التحقق من تسجيل الدخول، ثم الاطلاع على الرصيد والملف الشخصي. تعرض كل خطوة رموز الخطأ النمطية الموثقة (مثل 20005 مستخدم غير موجود، و26005 صيغة PIN غير صالحة).

المتطلبات المسبقة

•مفتاح API صالح لبيئة sandbox مع الترويستين Chari-Api-Key وC-Request-Id في كل طلب (انظر دليل «البدء في بيئة sandbox»).
•رقم اختباري مغربي بالصيغة +212********* غير مسجَّل بعد (يُتوقع الحصول على الحالة 0 في الخطوة 1).

1
التحقق من حالة الرقم
قبل أي تسجيل، استعلموا عن حالة الرقم لدى Chari. تُرجع الاستجابة حالة من 0 إلى 5: 0 Not exists (الرقم غير موجود لدى ChariMoney)، 1 Not confirmed (لم يُدخل رمز OTP)، 2 Confirmed (مسجّل لدى Switch)، 3 Active (تم إنشاء الرمز السري PIN)، 4 Locked temporary (تم تجاوز الحد الأقصى للمحاولات)، 5 Locked. بالنسبة لعميل جديد، توقّعوا الحالة 0:
bash
```
curl -X 'GET' \
  'https://sandbox.charimoney.com/api/customers/status?phoneNumber=+2126xxxxxxxx' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID'
```
الاستجابة
json
```
{
  "data": {
    "status": 0,
    "message": "Not exists"
  }
}
```
check-status-chari
20005 — تعذّر العثور على المستخدم المحدد.
2
تسجيل العميل (walletType)
ابدؤوا التسجيل برقم الهاتف، والاسم الشخصي والعائلي (حرفان على الأقل، أحرف لاتينية فقط)، وcin (5 أحرف على الأقل)، وwalletType: "P" للفرد و"C" للتاجر. يُرسَل رمز OTP إلى العميل عبر SMS وتردّ الواجهة API بالرمز 202. اختياري: ضبط closeLoopOnly على true يسجّل العميل في وضع CloseLoop فقط — وفي هذه الحالة تُرسل CHARI رمز OTP مباشرة.
bash
```
curl --location 'https://sandbox.charimoney.com/api/customers/register' \
  --header 'Chari-Api-Key: YOUR_API_KEY' \
  --header 'C-Request-Id: YOUR_REQUEST_ID' \
  --header 'Content-Type: application/json' \
  --data '{
    "phoneNumber": "+2126xxxxxxxx",
    "firstName": "Mohammed",
    "lastName": "Chairi",
    "cin": "K000000",
    "walletType": "P"
  }'
```
الاستجابة
json
```
{
  "data": true
}
```
register
20000 — صيغة رقم الهاتف غير صالحة (الصيغة المتوقعة: +212*********).
20006 — المعاملات الأولية المقدَّمة غير صحيحة أو غير صالحة.
20008 — التسجيل مقفل مؤقتًا بسبب قيود أمنية أو تنظيمية.
20009 — الطلب في انتظار التأكيد. يُرجى انتظار استكمال المعالجة.
3
تأكيد رمز OTP (autoActivate)
أكّدوا التسجيل بإرسال رمز OTP المستلَم عبر SMS (بالصيغة xxx-xxx). يحدّد الحقل الاختياري autoActivate (القيمة الافتراضية: false) ما يلي: إذا كان false، يجب على المستخدم إتمام التفعيل بإنشاء الرمز السري PIN (الخطوة التالية)؛ وإذا كان true، تُفعَّل المحفظة تلقائيًا دون الحاجة إلى PIN. لا تُرسلوا walletType هنا: يُحدَّد نوع المحفظة عند التسجيل. إذا لم يتوصل العميل بالرمز، أعيدوا إرساله عبر POST /api/customers/confirm/resend-otp.
bash
```
curl --location 'https://sandbox.charimoney.com/api/customers/confirm' \
  --header 'Chari-Api-Key: YOUR_API_KEY' \
  --header 'C-Request-Id: YOUR_REQUEST_ID' \
  --header 'Content-Type: application/json' \
  --data '{
    "phoneNumber": "+2126xxxxxxxx",
    "code": "365-768"
  }'
```
الاستجابة
json
```
{
  "data": true
}
```
confirm resend-otp
20000 — صيغة رقم الهاتف غير صالحة.
20017 — لا يوجد طلب معلّق مرتبط بالرقم المقدَّم — أعيدوا خطوة Register.
4
إنشاء الرمز السري PIN لتفعيل المحفظة
إذا لم تستخدموا autoActivate، أنشئوا الرمز السري PIN للعميل (4 أرقام مطلوبة) لإتمام التفعيل. بعد إنشاء PIN، تصبح حالة الرقم (الخطوة 1) هي 3: Active — مسجّل لدى Switch ونشِط لدى ChariMoney.
bash
```
curl -X 'POST' \
  'https://sandbox.charimoney.com/api/customers/pin' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID' \
  -H 'Content-Type: application/json' \
  -d '{
    "phoneNumber": "+2126xxxxxxxx",
    "pin": "0000"
  }'
```
الاستجابة
json
```
{
  "data": true
}
```
create-pin
26004 — تم بالفعل تعيين رمز سري PIN لهذه المحفظة — استخدموا Update PIN أو Reset PIN.
26005 — الرمز السري PIN المقدَّم لا يستوفي الصيغة المطلوبة (يجب أن يكون رقمًا من 4 خانات).
5
التحقق من تسجيل الدخول بالرمز السري PIN
صادِقوا على العميل باستخدام رمزه السري PIN للتأكد من التفعيل. تُبيّن الاستجابة logged (تكون true إذا نجحت المصادقة) وremainingAttempts (عدد المحاولات المتبقية قبل قفل الحساب).
bash
```
curl -X 'POST' \
  'https://sandbox.charimoney.com/api/customers/login' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID' \
  -H 'Content-Type: application/json' \
  -d '{
    "phoneNumber": "+2126xxxxxxxx",
    "pin": "0000"
  }'
```
الاستجابة
json
```
{
  "data": {
    "logged": true,
    "remainingAttempts": 5
  }
}
```
login-pin
20005 — تعذّر العثور على المستخدم المحدد — تحققوا من الرقم ومن الحالة (الخطوة 1).
26001 — الرمز السري PIN المُدخل غير صحيح — راقبوا remainingAttempts لتفادي قفل الحساب.
6
الاطلاع على رصيد المحفظة
يُستعلَم عن المحفظة المفعَّلة برقم الهاتف: تُرجع الاستجابة الرصيد الحالي (balance) لمحفظة العميل المسجَّل.
bash
```
curl -X 'GET' \
  'https://sandbox.charimoney.com/api/customers/balance?phoneNumber=+2126xxxxxxxx' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID'
```
الاستجابة
json
```
{
  "data": {
    "balance": 174.0
  }
}
```
get-balance
20005 — تعذّر العثور على المستخدم المحدد.
7
استرجاع الملف الشخصي الكامل للعميل
للتعمق أكثر، استرجعوا الملف التفصيلي للعميل: الهوية، الرصيد، rib المرتبط بالمحفظة، accountLevel (مستوى KYC من 1 إلى 4 — انظر جدول «مستويات الحساب»)، customerStatus (نفس قيم حالة الخطوة 1)، ومعلومات الشريك المرتبط.
bash
```
curl -X 'GET' \
  'https://sandbox.charimoney.com/api/customers/info?phoneNumber=+2126xxxxxxxx' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID'
```
الاستجابة
json
```
{
  "data": {
    "id": 72,
    "fullName": "Mohammed Chairi",
    "firstName": "Mohammed",
    "lastName": "Chairi",
    "phoneNumber": "+2126xxxxxxxx",
    "balance": 78,
    "accountType": 2,
    "rib": "82764000001000000000xxxx",
    "accountLevel": 1,
    "customerStatus": 3,
    "partnerId": 1
  }
}
```
get-customer-info
20005 — تعذّر العثور على المستخدم المحدد.

الإيداع بالبطاقة مع 3D Secure: من المعاينة إلى webhook

أضيفوا رصيدًا إلى محفظة عميل انطلاقًا من بطاقة بنكية: معاينة الرسوم، التنفيذ بالبطاقة التجريبية في sandbox، مصادقة 3D Secure، إشعار webhook بالحدث cashin.card.authorized — ثم متغيّرا الوكيل والبطاقة المرمَّزة.

المتطلبات المسبقة

•مفتاح API نشِط لبيئة sandbox (انظروا دليل «البدء في بيئة sandbox»).
•عميل مسجَّل في sandbox: يُقيَّد الإيداع في المحفظة المرتبطة برقم هاتفه.
•لاستقبال الإشعارات: نقطة نهاية HTTPS ومفتاح webhook (X-Api-Key) الذي تزوّدون به Chari.

1
معاينة الإيداع
قبل أي خصم، تحققوا من إمكانية الإيداع واحصلوا على الرسوم (feesAmount) عبر نقطة نهاية preview. يُمرَّر رقم هاتف العميل في سلسلة الاستعلام (بالصيغة +212*********) والمبلغ في المتن:
bash
```
curl -X 'POST' \
  'https://sandbox.charimoney.com/api/operations/cashin/card/preview?phoneNumber=+2126xxxxxxxx' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID' \
  -H 'Content-Type: application/json' \
  -d '{ "amount": 100 }'
```
الاستجابة
json
```
{
  "data": {
    "type": 1,
    "operation": {
      "phoneNumber": "+2126xxxxxxxx",
      "amount": 100,
      "method": 2,
      "acceptedBy": 0,
      "description": ""
    },
    "feesAmount": 0,
    "checkedAt": "2025-04-12T12:55:39.213Z",
    "openLoop": false
  }
}
```
cashin-card-preview
401 — بيانات المصادقة (API KEY) غير مصرَّح بها — تحققوا من الترويسة Chari-Api-Key.
10001 — Missing Parameters — أحد المعاملات المطلوبة ناقص (مثل phoneNumber في الاستعلام أو amount في المتن).

التنفيذ بالبطاقة التجريبية في sandbox

نفّذوا الإيداع بالبطاقة التجريبية في sandbox: PAN 4918914107195005، CVV 123، انتهاء الصلاحية 08/26 (أو أي تاريخ مستقبلي) — أي "2608" بصيغة YYMM المطلوبة في expiryDate. القيمة keepAlive: true تحفظ (ترمّز) البطاقة للخطوة الأخيرة؛ و3D Secure مفعَّل افتراضيًا. تبيّن الاستجابة ما إذا كانت إعادة توجيه 3DS مطلوبة (redirect) وتوفّر redirectionURL:

bash

curl -X 'POST' \
  'https://sandbox.charimoney.com/api/operations/cashin/card?phoneNumber=+2126xxxxxxxx' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID' \
  -H 'Content-Type: application/json' \
  -d '{
    "firstName": "Mohammed",
    "lastName": "Chairi",
    "cvv": "123",
    "amount": 100,
    "pan": "4918914107195005",
    "expiryDate": "2608",
    "keepAlive": true,
    "cardName": "my_test_card"
  }'

الاستجابة

json

{
  "data": {
    "redirect": true,
    "amount": 100,
    "transactionTrackId": "80832126-848",
    "orderId": "edc5608819",
    "transactionReferenceId": "2003",
    "redirectionURL": "https://staging-api.charipay.ma/...",
    "acceptURL": null,
    "declineURL": null
  }
}

cashin-card-execute

3
إتمام مصادقة 3D Secure
إذا كانت redirect = true، افتحوا redirectionURL في متصفح وأدخِلوا رمز 3DS الخاص بالبطاقة التجريبية: 555. بعد المصادقة، يُعاد توجيه المستخدم إلى acceptURL أو declineURL؛ ويتضمن عنوان إعادة التوجيه RESPONSE_CODE (0 = نجاح، وأي قيمة أخرى = فشل) وREASON_CODE (سبب النتيجة بصيغة مقروءة، مثل SUCCESS أو DECLINED). تحققوا من RESPONSE_CODE وREASON_CODE لتحديد الإجراء التالي في تطبيقكم.
cashin-card-execute
4
استقبال webhook بالحدث cashin.card.authorized
عند قبول إيداع CashIn بالبطاقة، تُشعِر Chari نقطة النهاية لديكم بالحدث cashin.card.authorized (طلب POST بصيغة JSON مع الترويستين C-Webhook-Id وX-Api-Key). يعيد الحقل CRequestId معرّف التتبّع المستلَم من الشريك، وOperationType 1 = CASHIN، وOperationStatus 2 = Completed، وMethod = Card، بينما تحدّد الحقول GatewayTrackId / GatewayOrderId / GatewayReferenceId المعاملة لدى البوابة. أجيبوا بـ 200 OK خلال 5 ثوانٍ (بمحتوى فارغ) — أي رمز غير 2xx يؤدي إلى إعادة المحاولة (دقيقة، 5 دقائق، 30 دقيقة، 60 دقيقة، ثم كل 6 ساعات حتى 72 ساعة إجمالًا).
الاستجابة
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"
  }
}
```

التحقق من العملية

باستخدام OperationId الوارد في webhook، استرجعوا تفاصيل العملية: operationType 1 = CASHIN وtransactionStatus 2 = COMPLETED (انظروا جدول «الأنواع والمراجع»). القيمة totalAmount هي المبلغ بعد تطبيق الرسوم والعمولات.

bash

curl -X 'GET' \
  'https://sandbox.charimoney.com/api/operations/123?phoneNumber=%2B2126XXXXXXXX' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID'

الاستجابة

json

{
  "data": {
    "operationId": 1525,
    "transactionId": 2710,
    "transactionReference": "T0101-25062515-1110",
    "amount": 30,
    "operationType": 1,
    "transactionDate": "2025-06-25T16:42:41.982Z",
    "sens": 1,
    "transactionStatus": 2,
    "feesAmount": 0,
    "totalAmount": 30,
    "sender": "+2126XXXXXXXX",
    "receiver": "+2126XXXXXXXX"
  }
}

get-operation-by-id

6
متغيّر الوكيل: إضافة رصيد إلى محفظة وكيل
المسار نفسه متاح من جهة الوكيل: تأخذ نقطتا النهاية /api/operations/cashin/card/agent/preview و/api/operations/cashin/card/agent في الاستعلام المعامل code (رمز الوكيل الذي تُقيَّد الأموال في محفظته) بدل phoneNumber. متن التنفيذ مطابق (نفس البطاقة التجريبية) ومسار 3D Secure هو نفسه:
bash
```
curl -X 'POST' \
  'https://sandbox.charimoney.com/api/operations/cashin/card/agent/preview?code=21011' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID' \
  -H 'Content-Type: application/json' \
  -d '{ "amount": 100 }'
```
الاستجابة
json
```
{
  "data": {
    "type": 1,
    "operation": {
      "code": "21011",
      "phoneNumber": "+2126xxxxxxxx",
      "amount": 100,
      "method": 2
    },
    "feesAmount": 0,
    "checkedAt": "2025-04-12T12:55:39.213Z",
    "openLoop": false
  }
}
```
cashin-card-agent-preview cashin-card-agent-execute

إعادة الإيداع بالبطاقة المرمَّزة

إذا كانت keepAlive تساوي true عند التنفيذ، تُحفَظ البطاقة (تُرمَّز). استرجعوا معرّفها customerBankCardId عبر GET /api/customers/tokenized/cards?phoneNumber=…، ثم أعيدوا الإيداع باستخدام CVV والمبلغ فقط — دون إرسال PAN مجددًا:

bash

curl -X 'POST' \
  'https://sandbox.charimoney.com/api/operations/cashin/card/123?phoneNumber=+2126xxxxxxxx' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID' \
  -H 'Content-Type: application/json' \
  -d '{ "cvv": "123", "amount": 200 }'

الاستجابة

json

{
  "data": {
    "redirect": true,
    "amount": 200,
    "transactionTrackId": "80832126-848",
    "orderId": "edc5608819",
    "transactionReferenceId": "2003",
    "redirectionURL": "https://staging-api.charipay.ma/...",
    "acceptURL": null,
    "declineURL": null
  }
}

cashin-card-saved get-tokenized-cards

الدفع للتاجر بالبطاقة: من المعاينة إلى الاسترداد

دورة الحياة الكاملة للدفع بالبطاقة (Card to Wallet): التحقق من الجدوى، التحصيل مع 3D Secure، الاختيار بين التحصيل التلقائي ومسار التفويض ← التحصيل/الإلغاء، الاسترداد، ثم إعادة استخدام بطاقة مرمَّزة. تعتمد كل خطوة على المعرّفين orderId وtransactionTrackId المُعادين من عملية الدفع.

المتطلبات المسبقة

•مفتاح API صالح لبيئة sandbox وبوابة البطاقات مفعّلة لحسابكم (راجعوا دليل «البدء في بيئة sandbox»).
•رقم هاتف محفظة التاجر المُحصِّل، بالصيغة +212*********.
•البطاقة التجريبية في sandbox: PAN 4918914107195005، CVV 123، انتهاء الصلاحية 08/26، رمز 3DS هو 555.

1
معاينة الدفعة (الرسوم، الجدوى)
قبل التحصيل، تحققوا من جدوى الدفع بالبطاقة نحو التاجر. يُمرَّر رقم هاتف التاجر في query string والمبلغ في جسم الطلب. تُعيد الاستجابة نوع العملية والرسوم (feesAmount) وطابع وقت التحقق.
bash
```
curl -X 'POST' \
  'https://sandbox.charimoney.com/api/operations/merchant/payment/card/preview?phoneNumber=+2126xxxxxxxx' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID' \
  -H 'Content-Type: application/json' \
  -d '{ "amount": 250 }'
```
الاستجابة
json
```
{
  "data": {
    "type": 5,
    "operation": {
      "phoneNumber": "+2126xxxxxxxx",
      "amount": 250,
      "method": 2
    },
    "feesAmount": 0,
    "checkedAt": "2025-04-12T12:55:39.213Z",
    "openLoop": false
  }
}
```
merchant-card-preview
401 — مفتاح API غير مصرَّح به — تحققوا من الترويسة Chari-Api-Key.
10001 — Missing Parameters — معامل مطلوب ناقص (مثل amount في جسم الطلب).
20005 — تعذّر العثور على المستخدم المحدد — تحققوا من رقم هاتف التاجر (الصيغة +212*********).

أول تحصيل: التنفيذ مع autoCapture

نفّذوا الدفعة بالبطاقة التجريبية (expiryDate بصيغة YYMM: 2608). مع autoCapture = true تُحصَّل الدفعة تلقائيًا. تعمل keepAlive = true على ترميز البطاقة لإعادة استخدامها لاحقًا (الخطوة 7). مسار 3DS: تُرجِع الاستجابة redirectionURL الذي يجب فتحه (redirect = true)؛ أدخلوا فيه رمز 3DS وهو 555. احتفظوا بـ orderId وtransactionTrackId — تعتمد عليهما بقية دورة الحياة كلها.

bash

curl -X 'POST' \
  'https://sandbox.charimoney.com/api/operations/merchant/payment/card?phoneNumber=+2126xxxxxxxx' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID' \
  -H 'Content-Type: application/json' \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "cvv": "123",
    "amount": 250,
    "pan": "4918914107195005",
    "expiryDate": "2608",
    "keepAlive": true,
    "3dSecure": true,
    "autoCapture": true,
    "notificationUrl": "https://merchant.example.com/webhook",
    "acceptUrl": "https://merchant.example.com/success",
    "declineUrl": "https://merchant.example.com/failure",
    "externalReference": "ORDER-1001"
  }'

الاستجابة

json

{
  "data": {
    "redirect": true,
    "responseCode": 0,
    "amount": 250,
    "transactionTrackId": "600789381213",
    "orderId": "CH473bbe51d546",
    "transactionReferenceId": "5852",
    "redirectionURL": "https://staging-api.charipay.ma:443/chari-frontend/home_card3?ORDER_ID=CH473bbe51d546&REFERENCE_ID=5852&TRACK_ID=600789381213",
    "gateway": "CHARIPAY",
    "operationId": null,
    "feesAmount": null
  }
}

merchant-card-execute

3
التحقق من عودة 3D Secure
بعد مصادقة 3D Secure، يُعاد توجيه المستخدم إلى acceptUrl أو declineUrl حسب النتيجة. يتضمن عنوان العودة RESPONSE_CODE (0 = نجاح، وأي قيمة أخرى = فشل) وREASON_CODE (سبب مقروء: SUCCESS، DECLINED…) وOPERATION (مثال: PAYMENT): تحققوا منها عند استلام إعادة التوجيه. كما يُشعَر عنوان notificationUrl عند انتهاء المعاملة (نجاح/فشل)، ويشير حدث webhook المسمى payment.card.authorized إلى قبول الدفع بالبطاقة.
merchant-card-execute
4
الدفع على مرحلتين: التفويض ثم التحصيل
لفصل التفويض عن الخصم، نفّذوا الدفعة (الخطوة 2) مع autoCapture = false: تُفوَّض الأموال دون خصمها. ثم أتمّوا العملية بالتحصيل، مستهدفين المعاملة عبر orderId وtransactionTrackId المُعادين من الدفعة. المسار النموذجي: دفع بالبطاقة مع AutoCapture = false ← تفويض ← تحصيل (نقطة النهاية هذه) أو إلغاء (reverse). النطاق المطلوب: operations:merchant-payment.
bash
```
curl -X 'POST' \
  'https://sandbox.charimoney.com/api/operations/merchant/payment/card/capture' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID' \
  -H 'Content-Type: application/json' \
  -d '{
    "phoneNumber": "+2126xxxxxxxx",
    "amount": 250,
    "orderId": "CH473bbe51d546",
    "transactionTrackId": "600789381213",
    "skipGatewayCall": false
  }'
```
الاستجابة
json
```
{
  "data": {
    "phoneNumber": "+2126xxxxxxxx",
    "operationId": 5231,
    "refundAmount": 250,
    "orderId": "CH473bbe51d546",
    "transactionTrackId": "600789381213"
  }
}
```
merchant-card-capture
5
إلغاء تفويض غير محصَّل (reverse)
إذا أُلغي الطلب قبل التحصيل، فألغوا التفويض: تُحرَّر الأموال المفوَّضة دون خصمها. جسم الطلب مطابق لجسم التحصيل — استهدفوا المعاملة عبر orderId وtransactionTrackId. ينطبق الإلغاء reversal على تفويض غير محصَّل؛ أما الدفعة المحصَّلة فعلًا فاستخدموا لها نقطة نهاية الاسترداد Refund (الخطوة التالية).
bash
```
curl -X 'POST' \
  'https://sandbox.charimoney.com/api/operations/merchant/payment/card/reverse' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID' \
  -H 'Content-Type: application/json' \
  -d '{
    "phoneNumber": "+2126xxxxxxxx",
    "amount": 250,
    "orderId": "CH473bbe51d546",
    "transactionTrackId": "600789381213",
    "skipGatewayCall": false
  }'
```
الاستجابة
json
```
{
  "data": {
    "phoneNumber": "+2126xxxxxxxx",
    "operationId": 5231,
    "refundAmount": 250,
    "orderId": "CH473bbe51d546",
    "transactionTrackId": "600789381213"
  }
}
```
merchant-card-reverse

استرداد دفعة محصَّلة (كليًا أو جزئيًا)

تُسترد الدفعة المحصَّلة فعلًا عبر نقطة نهاية الاسترداد Refund، محدَّدةً بـ operationId. قيمة RefundAmount الأقل من المبلغ المحصَّل تُنفِّذ استردادًا جزئيًا. انتبهوا إلى النطاق: operations:refund، وهو يختلف عن نطاق operations:merchant-payment الخاص بنقاط نهاية البطاقة الأخرى.

bash

curl -X 'POST' \
  'https://sandbox.charimoney.com/api/operations/merchant/payment/card/refund' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID' \
  -H 'Content-Type: application/json' \
  -d '{
    "phoneNumber": "+2126xxxxxxxx",
    "operationId": 5231,
    "refundAmount": 100,
    "orderId": "CH473bbe51d546",
    "transactionTrackId": "600789381213"
  }'

الاستجابة

json

{
  "data": {
    "phoneNumber": "+2126xxxxxxxx",
    "operationId": 5231,
    "refundAmount": 100,
    "orderId": "CH473bbe51d546",
    "transactionTrackId": "600789381213"
  }
}

merchant-card-refund

التحصيل مجددًا بالبطاقة المرمَّزة

تُعاد إعادة استخدام البطاقة المرمَّزة في الخطوة 2 (keepAlive = true) عبر معرّفها cardId في المسار: رمز CVV هو الوحيد المطلوب في جسم الطلب، إلى جانب المبلغ. للاستجابة البنية نفسها كما في الدفع بالبطاقة العادي — المعالجة نفسها لمسار 3DS (redirectionURL، والعودة بـ RESPONSE_CODE / REASON_CODE / OPERATION)، والمعرّفان نفسهما orderId وtransactionTrackId لبقية دورة الحياة.

bash

curl -X 'POST' \
  'https://sandbox.charimoney.com/api/operations/merchant/payment/tokenized/card/277?phoneNumber=+2126xxxxxxxx' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID' \
  -H 'Content-Type: application/json' \
  -d '{ "cvv": "123", "amount": 188 }'

الاستجابة

json

{
  "data": {
    "redirect": true,
    "responseCode": 0,
    "amount": 188,
    "transactionTrackId": "600789381214",
    "orderId": "CH8f2a1b9e4d7c",
    "transactionReferenceId": "5853",
    "redirectionURL": "https://staging-api.charipay.ma:443/chari-frontend/home_card3?ORDER_ID=CH8f2a1b9e4d7c&REFERENCE_ID=5853&TRACK_ID=600789381214",
    "gateway": "CHARIPAY",
    "operationId": null,
    "feesAmount": null
  }
}

merchant-card-tokenized-execute

8
خطوة إضافية: حالة رمز QR الخاص بالتاجر
إذا كان تجّاركم يُحصِّلون أيضًا عبر رمز QR، فتحققوا من حالة رمز QR الخاص بالتاجر انطلاقًا من مرجعه: تُعيد الاستجابة محتوى الرمز (qrContent، الحمولة المرمَّزة للعرض/المسح) ومرجعه (qrCodeReference). أما معاملات البطاقة فيبقى تتبّعها عبر orderId من خلال نقطة نهاية حالة ChariPay في الخطوة 3.
bash
```
curl -X 'GET' \
  'https://sandbox.charimoney.com/api/operations/merchant/qrcode/status?reference=1122334455' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID'
```
الاستجابة
json
```
{
  "data": {
    "qrContent": "00020101021126xxxxxx",
    "qrCodeReference": "1122334455"
  }
}
```
merchant-qrcode-status

الإيداع/السحب بمرجع (cash-in / cash-out): من الطلب إلى التنفيذ

مسار المرجع في ثلاث مراحل: ينشئ تطبيقكم طلب إيداع CashIn أو سحب CashOut يولّد مرجعًا فريدًا بصلاحية محدودة؛ يبلّغه العميل إلى وكيل؛ يطّلع الوكيل على الطلب ثم ينفّذ العملية. يستعرض هذا الدليل المسار الكامل في sandbox، بما في ذلك التنفيذ الشبكي المحاكى ونسخة Fatourati.

المتطلبات المسبقة

•مفتاح API صالح لبيئة sandbox (انظر دليل « البدء في بيئة sandbox »).
•لخطوة التنفيذ: رمز الوكيل الذي ينفّذ العملية.
•لاستقبال الإشعارات: نقطة نهاية webhook لديكم والمفتاح X-Api-Key الذي زوّدتم به Chari.

1
إنشاء طلب الإيداع CashIn
يولّد طلب الإيداع CashIn مرجعًا فريدًا بصلاحية محدودة؛ يُستخدم هذا المرجع لاحقًا من طرف وكيل لتنفيذ العملية. يحمل الجسم حقلين إلزاميين: PhoneNumber (رقم العميل) وAmount (مبلغ الإيداع). تعود الاستجابة بالحالة operationStatus 1 (open) — والقيم الممكنة هي 1 = open و2 = completed و3 = failed و4 = canceled، بينما يساوي operationType القيمة 1 للإيداع CashIn و2 للسحب CashOut.
bash
```
curl -X 'POST' \
  'https://sandbox.charimoney.com/api/operations/cashin/request' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID' \
  -H 'Content-Type: application/json' \
  -d '{
    "PhoneNumber": "+2126xxxxxxxx",
    "amount": 10
  }'
```
الاستجابة
json
```
{
  "data": {
    "createdAt": "2025-05-15T23:55:55.082Z",
    "closedAt": null,
    "reference": "1122334455",
    "phoneNumber": "+2126xxxxxxxx",
    "operationType": 1,
    "operationStatus": 1,
    "amount": 10
  }
}
```
request-cashin
10001 — Missing Parameters — حقل إلزامي (PhoneNumber أو Amount) ناقص في الجسم.
401 — بيانات المصادقة (API KEY) غير مصرَّح بها — تحققوا من الترويسة Chari-Api-Key.
2
الاطلاع على الطلب عبر مرجعه
يبلّغ العميل المرجع إلى الوكيل. قبل التنفيذ، يمكن للوكيل (أو نظامكم الخلفي) استرجاع تفاصيل الطلب — المبلغ والحالة — عبر المسار نفسه بطريقة GET، مع المرجع كمعامل استعلام. وما دامت العملية غير منفَّذة، يبقى executedAt بقيمة null وتبقى status عند 1 (open).
bash
```
curl -X 'GET' \
  'https://sandbox.charimoney.com/api/operations/cashin/request?reference=1122334455' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID'
```
الاستجابة
json
```
{
  "data": {
    "reference": "1122334455",
    "createdAt": "2025-05-15T23:55:55.082Z",
    "executedAt": null,
    "phoneNumber": "+2126xxxxxxxx",
    "amount": 10,
    "partner": "ChariMoney",
    "status": 1,
    "type": 1
  }
}
```
get-cashin-reference

تنفيذ الإيداع CashIn من جهة الوكيل

ينفّذ الوكيل العملية باستخدام المرجع المولَّد للعميل: يحمل الجسم code (رمز الوكيل الذي ينفّذ العملية) وreference. هذه هي الخطوة التي تجسّد إيداع النقد.

bash

curl -X 'POST' \
  'https://sandbox.charimoney.com/api/operations/cashin/agent' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID' \
  -H 'Content-Type: application/json' \
  -d '{
    "code": "123",
    "reference": "1122334455"
  }'

الاستجابة

json

{
  "data": {
    "createdAt": "2025-05-15T23:55:55.0821309Z",
    "closedAt": null,
    "reference": "1122334455",
    "phoneNumber": "+2126xxxxxxxx",
    "operationType": 1,
    "operationStatus": 1,
    "amount": 10
  }
}

execute-cashin-reference

4
تنفيذ السحب CashOut المماثل
يتبع سحب النقد المخطط الثلاثي نفسه تمامًا على مسارات cashout: يولّد POST /api/operations/cashout/request (بالحقلين PhoneNumber وAmount) المرجع، ويطّلع عليه GET /api/operations/cashout/request?reference=...، وينفّذه POST /api/operations/cashout/agent (بالحقلين code وreference). وفي الاستجابات يساوي operationType القيمة 2 (CashOut).
bash
```
curl -X 'POST' \
  'https://sandbox.charimoney.com/api/operations/cashout/request' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID' \
  -H 'Content-Type: application/json' \
  -d '{
    "PhoneNumber": "+2126xxxxxxxx",
    "amount": 100
  }'
```
الاستجابة
json
```
{
  "data": {
    "createdAt": "2025-05-15T23:56:55.082Z",
    "closedAt": null,
    "reference": "1122334456",
    "phoneNumber": "+2126xxxxxxxx",
    "operationType": 2,
    "operationStatus": 1,
    "amount": 100
  }
}
```
request-cashout get-cashout-reference execute-cashout-reference
5
محاكاة التنفيذ الشبكي في sandbox
تنفّذ نقاط نهاية الشبكة إيداع CashIn أو سحب CashOut بمرجع من كيان شبكة (خطوة وكيل الشبكة). في sandbox، استدعوها بأنفسكم لإتمام مسارات الاختبار دون شبكة وكلاء حقيقية: يحمل الجسم reference (إلزامي) وentity (اختياري)، ويعيد معامل الاستعلام الاختياري withContext النتيجة مع سياقها إن وُجد (القيمة الافتراضية false). أما المسار المماثل POST /api/network/operations/cashout فينفّذ السحب CashOut.
bash
```
curl -X 'POST' \
  'https://sandbox.charimoney.com/api/network/operations/cashin' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID' \
  -H 'Content-Type: application/json' \
  -d '{
    "reference": "1122334455",
    "entity": "AGENCY"
  }'
```
الاستجابة
json
```
{
  "data": {
    "reference": "1122334455",
    "entity": "AGENCY",
    "createdAt": "2025-05-15T23:55:55.082Z",
    "executedAt": "2025-05-15T23:57:07.000Z",
    "phoneNumber": "+2126xxxxxxxx",
    "amount": 10,
    "description": "CashIn by reference",
    "partner": "PARTNER_NAME"
  }
}
```
simulate-cashin simulate-cashout
6
استقبال التأكيد عبر webhook
يُطلق التنفيذ حدث webhook باسم cashin.network.executed (تنفيذ إيداع CashIn بمرجع) أو cashout.network.executed (تنفيذ سحب CashOut بمرجع) نحو نقطة نهاية HTTPS لديكم. يحمل جسم JSON الحقول المشتركة (OperationId وOperationType وOperationStatus وAmount وCreatedAt وExecutedAt...) إضافةً، لهذه العمليات الشبكية، إلى Reference وNetworkName. أجيبوا بـ 200 OK خلال 5 ثوانٍ؛ فأي رمز غير 2xx يؤدي إلى إعادة المحاولة (دقيقة، 5 دقائق، 30 دقيقة، 60 دقيقة، ثم كل 6 ساعات حتى 72 ساعة إجمالًا).
7
نسخة Fatourati: طلب الإيداع CashIn المخصص
Fatourati مزوّد خاص له مسار توليد مراجع خاص به (بادئة FATREF-): استخدموا المسار المخصص POST /api/operations/fatourati/cashin/request بدلًا من نقطة نهاية cashin القياسية — فقد يختلف سلوك توليد المرجع وقواعد انتهاء الصلاحية. وبالنسبة للوكيل الرئيسي، استبدلوا phoneNumber برمز الوكيل (PhoneNumber => Code)؛ أما Description وFeesPercent فاختياريان.
bash
```
curl -X 'POST' \
  'https://sandbox.charimoney.com/api/operations/fatourati/cashin/request' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID' \
  -H 'Content-Type: application/json' \
  -d '{
    "code": "1880375",
    "Amount": 100,
    "FeesPercent": 1,
    "Description": "Test it"
  }'
```
الاستجابة
json
```
{
  "data": {
    "reference": "FATREF-E6C8ECC690AC",
    "createdAt": "2026-06-11T00:42:09.654Z",
    "executedAt": null,
    "phoneNumber": null,
    "code": "1880375",
    "amount": 100,
    "description": "Test it",
    "status": 1,
    "type": 1
  }
}
```
request-cashin-fatourati

دفع الفواتير عبر Fatourati: من الدائن إلى الإيصال

حصّلوا فاتورة Fatourati (RADEEMA وLYDEC وIAM وTGR…) من البداية إلى النهاية: عرض قائمة الدائنين، عرض المستحقات، بناء نموذج التعريف الديناميكي، استرجاع غير المدفوعات، تأكيد الدفع، ثم تتبّع المعاملة (الحالة، الإيصال، أحداث Webhook). نموذج بدائن واحد؛ الدفع الجزئي مدعوم.

المتطلبات المسبقة

•مفتاح API صالح لبيئة sandbox (الترويستان Chari-Api-Key وC-Request-Id) — انظر دليل « البدء في بيئة sandbox ».
•وحدة دفع الفواتير مفعّلة لحساب الشريك من طرف فريق Chari.
•مستخدم نهائي موجود لدى Chari Money (رقم phoneNumber بالصيغة الدولية) ورصيد اختباري للعمليات المدينة.

عرض قائمة دائني Fatourati

استرجعوا قائمة الدائنين النشطين المتاحين لحسابكم (مصفّاة حسب عقدكم وإعدادات Fatourati لديكم). احتفظوا بـ codeCreancier لكل مُصدِر فواتير (4 أرقام، ≥ 1000). codeRetour: 000 = ACCEPTE (نجاح)، 908 = خطأ تقني لدى Fatourati. ولأن الاستجابة مستقرة نسبيًا، فإن تخزينها المؤقت لبضع ساعات لدى الشريك مقبول.

bash

curl -X 'GET' \
  'https://sandbox.charimoney.com/api/bills/creanciers' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID'

الاستجابة

json

{
  "codeRetour": "000",
  "msg": "ACCEPTE",
  "nbreCreancier": 9,
  "listeCreanciers": [
    {
      "codeCreancier": "1002",
      "nomCreancier": "RADEEMA",
      "descriptionCreancier": "Régie autonome de Marrakech",
      "logoPath": "https://cdn.charimoney.com/logos/radeema.png",
      "siteWeb": "https://www.radeema.ma"
    },
    {
      "codeCreancier": "1008",
      "nomCreancier": "LYDEC",
      "descriptionCreancier": "Lyonnaise des eaux de Casablanca",
      "logoPath": "https://cdn.charimoney.com/logos/lydec.png",
      "siteWeb": "https://www.lydec.ma"
    }
  ]
}

billpay-creanciers

401 — بيانات المصادقة (API KEY) غير مصرَّح بها — تحققوا من الترويسة Chari-Api-Key.

2
عرض مستحقات الدائن المختار
قد يعرض دائن واحد عدة مستحقات (يقابل المستحق نوع خدمة: فاتورة، تعبئة، ضريبة…). اعرضوها باستخدام creancierId المُحصَّل عليه في الخطوة 1. يتكوّن codeCreance دائمًا من خانتين (مثال: 01). codeRetour: 000 = ACCEPTE، 104 = دائن غير موجود أو غير نشط، 908 = خطأ تقني.
bash
```
curl -X 'GET' \
  'https://sandbox.charimoney.com/api/bills/creances?creancierId=1002' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID'
```
الاستجابة
json
```
{
  "codeRetour": "000",
  "msg": "ACCEPTE",
  "nbreCreance": 2,
  "listeCreance": [
    { "codeCreance": "01", "nomCreance": "Factures Eau et Electricité" },
    { "codeCreance": "02", "nomCreance": "Frais de raccordement" }
  ]
}
```
billpay-creances
3
بناء نموذج التعريف الديناميكي
للزوج (دائن، مستحق)، استرجعوا مخطط الحقول المراد عرضها: التسمية، النوع، الصيغة، الحجم، القيود. يجب عليكم بناء شاشة الإدخال من هذه الاستجابة (لا نموذج مكتوب يدويًا) للبقاء متوافقين مع الدائنين الجدد المضافين إلى شبكة Fatourati. typeChamp: text، select، password، libelle — الحقل من نوع libelle نص ثابت (غير قابل للتحرير) ويجب ألّا يُرسَل أبدًا في creancierVals. contrainte: 0 = اختياري، 1 = مطلوب. إذا كانت قيمة refTxFatourati تساوي 1 (الافتراضي)، فالخطوة التالية هي /impayes.
bash
```
curl -X 'GET' \
  'https://sandbox.charimoney.com/api/bills/form?creancierId=1008&creanceId=01' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID'
```
الاستجابة
json
```
{
  "codeRetour": "000",
  "msg": "ACCEPTE",
  "nbreParams": 2,
  "creancierParams": [
    {
      "libelle": "Contract number",
      "nomChamp": "numeroProduit",
      "typeChamp": "text",
      "formatChamp": "2",
      "tailleMin": 8,
      "tailleMax": 12,
      "contrainte": "1"
    },
    {
      "libelle": "To find your number, check your latest bill in the top right.",
      "nomChamp": "",
      "typeChamp": "libelle",
      "formatChamp": "1",
      "tailleMin": 0,
      "tailleMax": 0,
      "contrainte": "0"
    }
  ],
  "refTxFatourati": "1"
}
```
billpay-form
4
استرجاع غير المدفوعات الخاصة بالعميل
أرسلوا بيانات التعريف المُدخلة: يحمل الجسم creancierVals، وهو مصفوفة كائنات { nomChamp, valChamp } — تنبيه: تُسمى الخاصية valChamp (وليس valeurChamp كما في استجابتي /form و/impayes)، ويجب ألّا تُدرَج فيها الحقول من نوع typeChamp=libelle. يفتح هذا الاستدعاء المعاملة (حالة EN_ATTENTE) ويُرجِع refTxFatourati (12 رقمًا) يجب الاحتفاظ به من أجل /confirm؛ ويبقى الربط صالحًا لمدة 7 أيام تقويمية (مهلة Fatourati). تعرض impayesParams المقالات (typeArticle: 0 = مستحق، 1 = رسوم، 2 = إلزامي، 3 = رسوم تنبر)؛ والمعاملات التقنية في globalParams ذات التسمية libelle الفارغة (contrPaiement وisConfTO وisAnnul وrejoue) يجب ألّا تُعرض أبدًا على العميل. رموز رئيسية: 107 = لا توجد فاتورة للدفع، 109 = حقل مطلوب ناقص.
bash
```
curl -X 'POST' \
  'https://sandbox.charimoney.com/api/bills/impayes?phoneNumber=%2B212670770743&creancierId=1008&creanceId=01' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID' \
  -H 'Content-Type: application/json' \
  -d '{
  "creancierVals": [
    { "nomChamp": "numeroProduit", "valChamp": "16422270229" }
  ]
}'
```
الاستجابة
json
```
{
  "codeRetour": "000",
  "msg": "ACCEPTE",
  "refTxFatourati": "100003141347",
  "codeDevise": "504",
  "nbreCreances": 2,
  "montantTotalTTC": "150.50",
  "globalParams": [
    { "libelle": "Customer name", "nomChamp": "nomClient", "valeurChamp": "ALERGE DE LAREDO" },
    { "libelle": "", "nomChamp": "contrPaiement", "valeurChamp": "1" }
  ],
  "impayesParams": [
    {
      "idArticle": "1005533319",
      "description": "Water bill July 2026",
      "dateFacture": "26/07/2026",
      "prixTTC": "120.16",
      "typeArticle": 0
    },
    {
      "idArticle": "1005533320",
      "description": "Water bill August 2026",
      "dateFacture": "26/08/2026",
      "prixTTC": "30.34",
      "typeArticle": 0
    }
  ]
}
```
billpay-impayes
10001 — Missing Parameters — معامل مطلوب ناقص (phoneNumber أو creancierId أو creanceId أو مصفوفة creancierVals).
5
تأكيد الدفع (بعد المعاينة)
دعوا المستخدم يختار مقالاته (totalPayment: القيمة true = جميع غير المدفوعات، وfalse = اختيار جزئي)، ثم أكّدوا. يحمل الجسم creancierId وcreanceId ورمز refTxFatourati من الخطوة 4 وlisteArticleSelectionnes (كائنات { idArticle, prixTTC, typeArticle, dateFacture, description } مأخوذة من impayesParams) وcreancierVals ({ nomChamp, valChamp }) وglobalParams. يمكنكم أولًا التحقق من هذا الجسم نفسه دون تنفيذ الدفع عبر POST /api/bills/preview (الجسم مطابق لجسم /confirm). codeRetour 000 = CONFIRME (تسوية فعلية لدى الدائن)؛ 301 = عولجت من قبل (تُعامَل كنجاح، اعرضوا الإيصال). يجب أن يظهر refReglement على الإيصال؛ وتُعرض numCRC / texteCRC (من params) على الإيصال إن وُجدت.
bash
```
curl -X 'POST' \
  'https://sandbox.charimoney.com/api/bills/confirm?phoneNumber=%2B212670770743' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID' \
  -H 'Content-Type: application/json' \
  -d '{
  "creancierId": "1008",
  "creanceId": "01",
  "refTxFatourati": "100003141347",
  "totalPayment": false,
  "listeArticleSelectionnes": [
    { "idArticle": "1005533320", "prixTTC": "30.34", "typeArticle": 0, "dateFacture": "26/08/2026", "description": "Water bill August 2026" }
  ],
  "creancierVals": [
    { "nomChamp": "numeroProduit", "valChamp": "16422270229" }
  ],
  "globalParams": [
    { "libelle": "", "nomChamp": "contrPaiement", "valeurChamp": "1" }
  ]
}'
```
الاستجابة
json
```
{
  "codeRetour": "000",
  "msg": "ACCEPTE",
  "refTxFatourati": "100003141347",
  "codeAutorisation": "A1B2C3",
  "refReglement": "REGL20260512000183",
  "montantTotalTTC": "30.34",
  "codeDevise": "504",
  "params": [
    { "nomChamp": "numCRC", "valeurChamp": "0801007777" },
    { "nomChamp": "texteCRC", "valeurChamp": "For any complaint, contact LYDEC customer service." }
  ]
}
```
billpay-preview billpay-confirm
20005 — The specified user could not be found — يجب أن يطابق phoneNumber مستخدمًا موجودًا لدى Chari Money، وإلا تُرفض المعاملة قبل أي استدعاء لـ Fatourati.
6
تتبّع المعاملة وتسليم الإيصال
يُرجِع GET /api/bills/reference/status حالة cash-in عبر Fatourati انطلاقًا من مرجعه: مؤشر التنفيذ، الحالة، المبلغ، الطوابع الزمنية وchariOperationId (استجابة 204 No Content إذا لم توجد معاملة مطابقة؛ وتُعاد الاستجابة في الجذر دون غلاف { "data": … }). يمكن استخدام معرّف عملية Chari هذا مع GET /api/bills/bill-receipt/{operationId}?phoneNumber=… لتنزيل الإيصال — تحتوي استجابة 200 على ملف الإيصال (محتوى ثنائي) وليس جسم JSON، ويجب أن يذكر الإيصال مرجع refReglement المُعاد من /confirm. كما يتوفر السجل المقسّم إلى صفحات لمدفوعات العميل عبر GET /api/bills/history.
bash
```
curl -X 'GET' \
  'https://sandbox.charimoney.com/api/bills/reference/status?reference=1000031413470' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID'
```
الاستجابة
json
```
{
  "fatouratiReference": "1000031413470",
  "executed": true,
  "status": "CONFIRME",
  "created_at": "2026-07-12T10:15:23Z",
  "amount": 150.50,
  "executed_at": "2026-07-12T10:16:05Z",
  "chariOperationId": 2181
}
```
billpay-reference-status billpay-receipt billpay-history
7
الاستماع إلى أحداث Webhook من نوع payment.*
السلوك غير المتزامن (القناة الرقمية): على /confirm، الرموز 908/909/910 ليست حالات فشل نهائية — تبقى المعاملة في حالة AUTORISE ويُبلَّغ عن حلّها النهائي عبر Webhook. أحداث الوحدة هي: payment.confirmed (الحالة CONFIRME) وpayment.cancelled (ANNULE) وpayment.refunded (REMBOURSE) وpayment.failed (FAILED). تصل الإشعارات كطلبات POST موقَّعة مع الترويسة X-Api-Key (المفتاح السري الذي تزوّدون به Chari)؛ أجيبوا بـ 200 OK خلال 5 ثوانٍ — أي رمز غير 2xx يؤدي إلى إعادة المحاولة (دقيقة، 5 دقائق، 30 دقيقة، 60 دقيقة، ثم كل 6 ساعات حتى 72 ساعة إجمالًا).
billpay-confirm

تعبئة الرصيد الهاتفية B2B: الكتالوج، التعبئة، صيغة العميل

عبّئوا رصيد رقم هاتف محمول مغربي من حساب وكيلكم الرئيسي باستدعاءين اثنين: كتالوج العروض ثم تنفيذ التعبئة. يغطي الدليل بعد ذلك صيغة «العميل» (خصم من wallet العميل، مع معاينة مسبقة) وسجلّ التعبئات. المشغّلون المدعومون: اتصالات المغرب (IAM) وOrange وInwi.

المتطلبات المسبقة

•مفتاح API صالح لبيئة sandbox (انظر دليل «البدء في بيئة sandbox»).
•خدمة telco مفعّلة لحساب الشريك الخاص بكم من طرف فريق Chari.
•رمز وكيلكم الرئيسي (الحساب المخصوم في التعبئة B2B)، مزوَّدًا برصيد اختباري.

1
التحقق من تفعيل خدمة telco
تعبئة رصيد الاتصالات وحدة تُفعِّلها فرق Chari لحساب الشريك عند الطلب. ستحتاجون أيضًا إلى رمز وكيلكم الرئيسي: وهو الحساب الذي سيُخصم منه في التعبئة B2B، وتوفّره Chari بعد تفعيل حساب الشريك الخاص بكم. إذا لم تكن الخدمة مفعّلة، تفشل استدعاءات telco بخطأ أعمال يشير إلى أن الخدمة غير مفعّلة لحسابكم — اطلبوا حينها تفعيل المشغّلين (انظر دليل «البدء في بيئة sandbox»).
guide-sandbox-onboarding get-principal-agent

استرجاع كتالوج العروض (B2B)

يُرجِع كتالوج B2B قائمة منتجات التعبئة المتاحة لرقم هاتف ومبلغ ومشغّل معيّنين (1 = اتصالات المغرب، 2 = Orange، 3 = Inwi). يحمل كل منتج رمز productCode فريدًا يُستخدم عند طلب التعبئة، ومؤشر التوفّر enabled.

bash

curl -X 'POST' \
  'https://sandbox.charimoney.com/api/services/telco/catalog/b2b' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID' \
  -H 'Content-Type: application/json' \
  -d '{
  "recipientPhoneNumber": "+21266123123",
  "amount": 10,
  "operator": 2
}'

الاستجابة

json

{
  "data": [
    { "productCode": 3, "description": "Pass Internet sur mobile", "arDescription": "عرض الإنترنت", "enabled": true },
    { "productCode": 1, "description": "Pass Appels vers le national", "arDescription": "روشارج المكالمات", "enabled": true },
    { "productCode": 0, "description": "Recharge Dirhams", "arDescription": "روشارج الدراهم", "enabled": true }
  ]
}

telco-catalog

3
تنفيذ التعبئة B2B
أطلقوا التعبئة باستخدام productCode المختار من الكتالوج. الحقل code هو رمز وكيلكم الرئيسي — الحساب الذي سيُخصم منه. تكون قيمة rechargeType هي 0 للتعبئة الكلاسيكية (بالدراهم) و1 للتعبئة من نوع منتج (عرض من الكتالوج). تحمل الاستجابة operationType = 10 ‏(RECHARGE، انظر جدول «الأنواع والمراجع»).
bash
```
curl -X 'POST' \
  'https://sandbox.charimoney.com/api/operations/service/telco/recharge/b2b' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID' \
  -H 'Content-Type: application/json' \
  -d '{
  "recipientPhoneNumber": "+21266123123",
  "amount": 10,
  "operator": 2,
  "rechargeType": 1,
  "productCode": 3,
  "code": "12003"
}'
```
الاستجابة
json
```
{
  "data": {
    "operationType": 10,
    "Amount": 10,
    "feesAmount": 0,
    "checkedAt": "2025-04-12T12:31:59.31347Z",
    "openLoop": false
  }
}
```
telco-recharge

صيغة العميل: معاينة التعبئة

إذا كانت التعبئة مدفوعة من wallet العميل (وليس من حساب وكيلكم الرئيسي)، استخدموا صيغة «العميل». استدعوا المعاينة أولًا للتحقق من إمكانية التنفيذ والمبلغ والرسوم قبل التنفيذ: customerPhoneNumber هو wallet المخصوم، وrecipientPhoneNumber هو الرقم المُعبَّأ. تُرجِع الاستجابة feesAmount وtotalAmount (المبلغ + الرسوم).

bash

curl -X 'POST' \
  'https://sandbox.charimoney.com/api/operations/service/telco/recharge/preview' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID' \
  -H 'Content-Type: application/json' \
  -d '{
  "customerPhoneNumber": "+2126xxxxxxxx",
  "recipientPhoneNumber": "+2127xxxxxxxx",
  "amount": 100.00,
  "operator": 2,
  "rechargeType": 0
}'

الاستجابة

json

{
  "data": {
    "type": 10,
    "operation": {
      "customerPhoneNumber": "+2126xxxxxxxx",
      "recipientPhoneNumber": "+2127xxxxxxxx",
      "amount": 100.00,
      "operator": 2,
      "rechargeType": 0
    },
    "feesAmount": 0,
    "totalAmount": 100.00,
    "checkedAt": "2026-07-12T10:22:05.118Z",
    "openLoop": false
  }
}

telco-recharge-preview

صيغة العميل: تنفيذ التعبئة

بعد التحقق من المعاينة، نفّذوا التعبئة بنفس متن الطلب: يُخصم من wallet العميل (customerPhoneNumber) — بخلاف صيغة /b2b التي تخصم من حساب الوكيل الرئيسي. للتعبئة من نوع منتج، أضيفوا productCode المُعاد من الكتالوج.

bash

curl -X 'POST' \
  'https://sandbox.charimoney.com/api/operations/service/telco/recharge' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID' \
  -H 'Content-Type: application/json' \
  -d '{
  "customerPhoneNumber": "+2126xxxxxxxx",
  "recipientPhoneNumber": "+2127xxxxxxxx",
  "amount": 100.00,
  "operator": 2,
  "rechargeType": 0
}'

الاستجابة

json

{
  "data": {
    "operationType": 10,
    "amount": 100.00,
    "feesAmount": 0,
    "totalAmount": 100.00,
    "reason": null,
    "recipientPhoneNumber": "+2127xxxxxxxx",
    "checkedAt": "2026-07-12T10:24:31.204Z"
  }
}

telco-recharge-client

الاطلاع على سجلّ تعبئات العميل

استرجعوا قائمة عمليات تعبئة عميل مع تقسيم الصفحات (pageSize/pageNumber) والتصفية حسب الحالة. المُعامل status (قيم enum في swagger: من 0 إلى 4) قابل للتكرار للتصفية حسب عدة حالات، مثال: status=2&status=3. الاستجابة قائمة عمليات، بدون غلاف تقسيم صفحات.

bash

curl -X 'GET' \
  'https://sandbox.charimoney.com/api/operations/service/telco/recharge?phoneNumber=%2B2126xxxxxxxx&pageSize=20&pageNumber=1&status=2' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID'

الاستجابة

json

{
  "data": [
    {
      "telcoRechargeOperationId": 3151,
      "customerId": 1200,
      "createdAt": "2026-07-10T09:15:24.512Z",
      "completedAt": "2026-07-10T09:15:31.240Z",
      "operatorId": 2,
      "amount": 50.00,
      "product": "Recharge Dirhams",
      "type": 0,
      "status": 2,
      "destinationPhoneNumber": "+2127xxxxxxxx"
    }
  ]
}

telco-recharge-history

7
التعامل مع الأخطاء
تتبع الأخطاء رموز HTTP القياسية؛ ويحمل الخطأ 400 Bad Request رمز خطأ خاصًا بـ Chari في متن الاستجابة ({ "errorCode": ..., "errorDescription": "..." }). أدرجوا C-Request-Id فريدًا (UUID v4) في كل طلب: فهو يُعاد في الاستجابة ويسهّل التتبّع مع فريق الدعم.
401 Unauthorized — بيانات المصادقة (API KEY) غير مصرَّح بها — تحقّقوا من الترويسة Chari-Api-Key ومن البيئة (المفاتيح خاصة بكل بيئة).
10001 — Missing Parameters — حقل إلزامي ناقص في متن الطلب (مثل code أو productCode أو rechargeType في التعبئة B2B).

بيع القسائم: العلامات التجارية، المقالات، المعاينة، الرمز

المسار الكامل لبيع قسيمة رقمية (بطاقة هدايا، تعبئة ألعاب…): تصفّح العلامات التجارية، اختيار مقال، معاينة المبلغ والرسوم، ثم تأكيد الشراء للحصول على الرمز المراد تسليمه إلى المستفيد. يتبع مسار الشراء نموذج معاينة/تأكيد؛ ونوع العملية هو 23 ‏(VOUCHER).

المتطلبات المسبقة

•مفتاح API صالح لبيئة sandbox (انظر دليل «البدء في بيئة sandbox»).
•وحدة القسائم مفعّلة لحسابكم، مع كتالوج مجهّز في sandbox من طرف Chari — وإلا فستعود قوائم العلامات التجارية والمقالات فارغة.
•وكيل رئيسي مزوَّد برصيد اختباري لتنفيذ العمليات المدينة.

1
التحقق من تجهيز الكتالوج
يجب أن تجهّز Chari العلامات التجارية للقسائم في sandbox لحسابكم: الكتالوج الفارغ ليس خللًا في التكامل بل وحدة غير مجهّزة — اطلبوا التفعيل من جهة الاتصال لديكم في Chari. كذلك فإن تأكيد الشراء عملية مدينة: يجب تزويد وكيلكم الرئيسي برصيد اختباري. النقطتان مفصّلتان في دليل onboarding الخاص بـ sandbox.
guide-sandbox-onboarding
2
عرض العلامات التجارية المتاحة
استرجعوا القائمة المقسّمة إلى صفحات لعلامات القسائم التجارية (تبدأ page من 1، وقيمة take الافتراضية 10). حقل phoneNumber الخاص بالعميل إلزامي، بالصيغة +212*********. دوّنوا معرّف العلامة المختارة. لا يوجد مرشِّح brandId في نقطة النهاية هذه: للاطلاع على علامة تجارية محددة، استخدموا GET /api/vouchers/brands/{id}.
bash
```
curl -X 'GET' \
  'https://sandbox.charimoney.com/api/vouchers/brands?phoneNumber=%2B2126xxxxxxxx&page=1&take=10' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID'
```
الاستجابة
json
```
{
  "data": {
    "collection": [
      {
        "id": 14,
        "name": "Razer",
        "description": "Step 1: From the payment ....",
        "image": "string",
        "expirationDelay": "none"
      }
    ],
    "count": 3
  }
}
```
voucher-brands voucher-brand-by-id
3
استرجاع مقالات علامة تجارية
استرجعوا كتالوج مقالات العلامة المختارة عبر brandId الخاص بها. يعرض كل مقال سعره (price)، والأهم المعرّفين اللذين تتطلبهما بقية المسار: providerSkuId (معرّف المقال لدى المزوّد) وproviderId (معرّف المزوّد). احتفظوا بهما للمعاينة والتأكيد.
bash
```
curl -X 'GET' \
  'https://sandbox.charimoney.com/api/vouchers/articles?phoneNumber=%2B2126xxxxxxxx&brandId=14&page=1&take=10' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID'
```
الاستجابة
json
```
{
  "data": {
    "collection": [
      {
        "providerSkuId": "string",
        "productName": "string",
        "imageUrl": "string",
        "price": 0,
        "description": "string",
        "providerId": 0,
        "brandId": 0
      }
    ],
    "count": 3
  }
}
```
voucher-catalog voucher-articles-by-brand

معاينة الشراء

تحققوا من إمكانية تنفيذ الشراء قبل أي تنفيذ. يحمل متن الطلب خمسة حقول إلزامية: customerPhoneNumber وdestinationPhoneNumber وbeneficiaryName (حقل نصي حر) وproviderSkuId وproviderId. تُرجِع الاستجابة type بقيمة 23 ‏(VOUCHER، انظر جدول «الأنواع والمراجع») وfeesAmount (الرسوم) وtotalAmount (المبلغ الإجمالي شامل الضريبة) — اعرضوها على العميل قبل التأكيد.

bash

curl -X 'POST' \
  'https://sandbox.charimoney.com/api/operations/voucher/preview' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID' \
  -H 'Content-Type: application/json' \
  -d '{
  "customerPhoneNumber": "+2126xxxxxxxx",
  "providerSkuId": "1212AAABBBccc",
  "destinationPhoneNumber": "+2126xxxxxxxx",
  "beneficiaryName": "abdennour",
  "providerId": 2
}'

الاستجابة

json

{
  "data": {
    "type": 23,
    "operation": {
      "customerPhoneNumber": "+2126xxxxxxxx",
      "amount": 2.16,
      "reason": "",
      "beneficiaryId": null,
      "recipientPhoneNumber": "+2126xxxxxxxx"
    },
    "feesAmount": 0.15,
    "totalAmount": 2.16,
    "checkedAt": "2026-03-31T14:52:07",
    "openLoop": false
  }
}

voucher-preview

التأكيد وتسليم رمز القسيمة

نفّذوا الشراء بنفس متن طلب المعاينة. هذه الاستجابة هي التي تحمل المطلوب: يتضمن operation.code رمز القسيمة المراد مشاركته مع المستفيد، مع voucherName (اسم القسيمة المشتراة) وdescription وcashBack (مبلغ استرداد نقدي اختياري). خزّنوا الرمز بشكل آمن وسلّموه إلى المستفيد.

bash

curl -X 'POST' \
  'https://sandbox.charimoney.com/api/operations/voucher/confirm' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID' \
  -H 'Content-Type: application/json' \
  -d '{
  "customerPhoneNumber": "+2126xxxxxxxx",
  "providerSkuId": "1212AAABBBccc",
  "destinationPhoneNumber": "+2126xxxxxxxx",
  "beneficiaryName": "abdennour",
  "providerId": 2
}'

الاستجابة

json

{
  "data": {
    "type": 23,
    "operation": {
      "operationType": 23,
      "voucherName": "Soho 101 Okey 92000 Gold Coin",
      "amount": 2.16,
      "cashBack": 0.14,
      "totalAmount": 1.96,
      "reason": null,
      "recipientPhoneNumber": "+2126xxxxxxxx",
      "checkedAt": "2026-03-31T14:53:50.6078466Z",
      "urlActivateCard": null,
      "destinationPhoneNumber": "+2126xxxxxxxx",
      "beneficiaryName": "abdennour",
      "code": "01X01X01X",
      "description": "80000 Gold Coin"
    },
    "feesAmount": 0.15,
    "totalAmount": 2.16,
    "checkedAt": "2026-03-31T14:52:07",
    "openLoop": false
  }
}

voucher-confirm

6
التعمق أكثر: الكتالوج المحلي (SKU)
إلى جانب مسار العلامات/المقالات أعلاه، تعرض الواجهة كتالوج قسائم محلية قابلًا للتصفية حسب brandId والكلمة المفتاحية. يغذّي skuId الخاص بالقسائم المُعادة مسار شراء ثانيًا مستقلًا: POST /api/operations/service/voucher/preview (الذي يُرجِع كائن القسيمة مكتملًا، لا سيما amount) ثم POST /api/operations/service/voucher (النطاق operation:voucher). تنبيه: لا يوثّق swagger مخطط الاستجابة 200 للقائمة، ويجب عدم الخلط بين هذا المسار «service» و/api/operations/voucher/preview المستخدم في الخطوات السابقة.
bash
```
curl -X 'GET' \
  'https://sandbox.charimoney.com/api/vouchers?phoneNumber=%2B2126xxxxxxxx&page=1&take=20&brandId=14' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID'
```
vouchers-local-list voucher-service-preview voucher-service-purchase
7
معالجة الأخطاء
تتبع أخطاء API رموز HTTP القياسية، مع رموز أخطاء خاصة بـ Chari لأخطاء الأعمال، تُعاد برمز 400 بالصيغة { "errorCode": …, "errorDescription": "…" }. أكثر الحالات شيوعًا في هذا المسار مدرجة أدناه؛ والجدول الكامل موجود في قسم «رموز الأخطاء».
401 — بيانات المصادقة (API KEY) غير مصرَّح بها — تحققوا من الترويسة Chari-Api-Key.
10001 — معاملات ناقصة (Missing Parameters) — أحد الحقول الخمسة الإلزامية في المتن (customerPhoneNumber، destinationPhoneNumber، beneficiaryName، providerSkuId، providerId) مفقود.
422 — الخادم غير قادر على معالجة الطلب.

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

إدارة كاملة لدورة حياة العميل: التحقق من الحالة، التسجيل، تأكيد رمز 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
`autoActivate`	boolean	body	اختياري	القيمة الافتراضية: false. تحدّد ما إذا كان يجب تفعيل المحفظة تلقائيًا بعد التحقق من رمز OTP. إذا كانت false، يجب على المستخدم إتمام التفعيل بإنشاء أو إدخال الرمز السري PIN. إذا كانت true، تُفعَّل المحفظة تلقائيًا دون الحاجة إلى PIN.

ملاحظات

•يُحدَّد نوع المحفظة ("P" فرد / "C" تاجر) عند التسجيل (Register): لا يُرسَل walletType عند التأكيد.

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 للعميل بعد التحقق من رمز OTP.

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

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يستدعي تطبيقكم /api/kyc/shareid/auth للحصول على رمز KYC قصير الصلاحية.
2يفتح التطبيق حزمة ShareID SDK بهذا الرمز.
3يمسح المستخدم بطاقة هويته ويُكمل سيلفي موجَّهًا.
4تُجري ShareID عمليات التحقق.
5بعد اكتمال التحقق عبر ShareID، يطلب تطبيقكم ترقية الحساب عبر PUT /api/customers/upgrade/request (انظر «تأكيد KYC»).
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.

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

التأكيد

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

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

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

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

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

Parameter	Type	In	مطلوب	Description
`phoneNumber`	string	query	اختياري	رقم هاتف التاجر. الصيغة: +212*********
`kycDocuments`	multipart form	form	مطلوب	مصفوفة من كائنات مستندات KYC. يمكن إرسال عدة مستندات في طلب واحد بتكرار الحقول المفهرسة (مثال: kycDocuments[0]، kycDocuments[1]، ...).
`kycDocuments[n].docType`	int	form	مطلوب	نوع المستند (انظر جدول أنواع المستندات).
`kycDocuments[n].docFront`	file	form	مطلوب	الصورة الأمامية للمستند. الصيغ المقبولة: PNG وJPG/JPEG وPDF.
`kycDocuments[n].docBack`	file	form	اختياري	الصورة الخلفية (مطلوبة للمستندات 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	مطلوب	المبلغ المراد إيداعه.
`pan`	string	body	مطلوب	رقم البطاقة الكامل (PAN).
`expiryDate`	string	body	مطلوب	تاريخ الانتهاء بصيغة YYMM.
`keepAlive`	bool	body	مطلوب	true: حفظ البطاقة للاستخدام اللاحق / false: استخدام لمرة واحدة.
`cardName`	string	body	اختياري	الاسم الذي يختاره المستخدم للبطاقة المحفوظة.
`3dSecure`	bool	body	اختياري	تفعيل 3D Secure. القيمة الافتراضية: true.
`autoCapture`	bool	body	اختياري	تحصيل الدفع تلقائيًا.
`allowInternationalCards`	bool	body	اختياري	قبول البطاقات الدولية.
`feesPercent`	decimal	body	اختياري	نسبة الرسوم المطبَّقة على الدافع.
`internationalFeesPercent`	decimal	body	اختياري	نسبة الرسوم الخاصة بالبطاقات الدولية.
`acceptUrl`	string	body	اختياري	عنوان URL لإعادة التوجيه عند نجاح 3DS.
`declineUrl`	string	body	اختياري	عنوان URL لإعادة التوجيه عند فشل 3DS.
`notificationUrl`	string	body	اختياري	عنوان URL الذي يُشعَر عند انتهاء المعاملة (نجاح/فشل).
`externalReference`	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
`code`	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	مطلوب	حفظ البطاقة للاستخدام اللاحق.
`cardName`	string	body	اختياري	الاسم الذي يختاره المستخدم لحفظ البطاقة.
`3dSecure`	bool	body	اختياري	تفعيل 3D Secure. القيمة الافتراضية: true.
`autoCapture`	bool	body	اختياري	تحصيل الدفع تلقائيًا.
`allowInternationalCards`	bool	body	اختياري	قبول البطاقات الدولية.
`feesPercent`	decimal	body	اختياري	نسبة الرسوم المطبَّقة على الدافع.
`internationalFeesPercent`	decimal	body	اختياري	نسبة الرسوم الخاصة بالبطاقات الدولية.
`acceptUrl`	string	body	اختياري	عنوان URL لإعادة التوجيه عند نجاح 3DS.
`declineUrl`	string	body	اختياري	عنوان URL لإعادة التوجيه عند فشل 3DS.
`notificationUrl`	string	body	اختياري	عنوان URL الذي يُشعَر عند انتهاء المعاملة (نجاح/فشل).
`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/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/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	مطلوب	ترميز البطاقة لإعادة استخدامها عبر نقطة نهاية البطاقة المرمَّزة.
`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.
`declineUrl`	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
`customerPhoneNumber`	string	query	اختياري	رقم هاتف التاجر (العميل) المراد توليد رمز QR له. الصيغة: +212*********
`maskedNumber`	bool	query	اختياري	إخفاء رقم التاجر في محتوى رمز QR. مثال: +2126######74
`billNumber`	string	body	اختياري	رقم الفاتورة المراد تضمينه في محتوى رمز QR (اختياري).
`additionalData`	string	body	اختياري	بيانات إضافية حرة تُضمَّن في محتوى رمز QR (اختياري).

ملاحظات

•يُسمّى معامل الاستعلام customerPhoneNumber (وليس phoneNumber).
•يُرسَل billNumber وadditionalData في متن الطلب (اختياريان).

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

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

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

Parameter	Type	In	مطلوب	Description
`customerPhoneNumber`	string	query	اختياري	رقم هاتف التاجر (العميل) المراد توليد رمز QR له. الصيغة: +212*********
`maskedNumber`	bool	query	اختياري	إخفاء رقم التاجر.
`amount`	decimal	body	مطلوب	المبلغ الثابت لرمز QR.
`billNumber`	string	body	اختياري	رقم الفاتورة المراد تضمينه في محتوى رمز QR (اختياري).
`additionalData`	string	body	اختياري	بيانات إضافية حرة تُضمَّن في محتوى رمز QR (اختياري).

ملاحظات

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

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

عبر البطاقة — تحصيل

تحصيل تفويض دفع بالبطاقة لدى التاجر. يُستخدم لإتمام دفعة بدأت بـ `AutoCapture = false`: عندها تُخصم الأموال المفوَّضة فعليًا.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	body	مطلوب	رقم هاتف التاجر. الصيغة: +212*********
`Amount`	decimal	body	مطلوب	المبلغ المراد تحصيله.
`OrderId`	string	body	مطلوب	معرّف الطلب المُعاد من دفعة البطاقة (`orderId`).
`TransactionTrackId`	string	body	مطلوب	معرّف التتبّع المُعاد من دفعة البطاقة (`transactionTrackId`).
`SkipGatewayCall`	bool	body	اختياري	إذا كانت القيمة true، لا يتم استدعاء بوابة الدفع أثناء التحصيل.

ملاحظات

•النطاق المطلوب: operations:merchant-payment.
•يأتي orderId وtransactionTrackId من استجابة دفعة البطاقة (نقطة النهاية «عبر البطاقة — تنفيذ»).
•المسار النموذجي: دفع بالبطاقة مع AutoCapture = false ← تفويض ← تحصيل (نقطة النهاية هذه) أو إلغاء (reverse).

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

عبر البطاقة — إلغاء (Reverse)

إلغاء (reversal) تفويض دفع بالبطاقة لدى التاجر لم يُحصَّل بعد: تُحرَّر الأموال المفوَّضة دون خصمها.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	body	مطلوب	رقم هاتف التاجر. الصيغة: +212*********
`Amount`	decimal	body	مطلوب	مبلغ التفويض المراد إلغاؤه.
`OrderId`	string	body	مطلوب	معرّف الطلب المُعاد من دفعة البطاقة (`orderId`).
`TransactionTrackId`	string	body	مطلوب	معرّف التتبّع المُعاد من دفعة البطاقة (`transactionTrackId`).
`SkipGatewayCall`	bool	body	اختياري	إذا كانت القيمة true، لا يتم استدعاء بوابة الدفع أثناء الإلغاء.

ملاحظات

•النطاق المطلوب: operations:merchant-payment.
•جسم الطلب مطابق لنقطة نهاية التحصيل Capture: استهدفوا المعاملة عبر orderId وtransactionTrackId.
•ينطبق الإلغاء reversal على تفويض غير محصَّل؛ أما الدفعة المحصَّلة فعلًا فاستخدموا لها نقطة نهاية الاسترداد Refund.

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

عبر البطاقة — استرداد

استرداد دفعة بالبطاقة لدى التاجر سبق تحصيلها، كليًا أو جزئيًا عبر `RefundAmount`.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	body	مطلوب	رقم هاتف التاجر. الصيغة: +212*********
`OperationId`	int	body	مطلوب	معرّف العملية المراد استردادها.
`RefundAmount`	decimal	body	مطلوب	المبلغ المراد استرداده.
`OrderId`	string	body	اختياري	معرّف طلب المعاملة الأصلية (`orderId`).
`TransactionTrackId`	string	body	اختياري	معرّف تتبّع المعاملة الأصلية (`transactionTrackId`).

ملاحظات

•النطاق المطلوب: operations:refund (يختلف عن نطاق operations:merchant-payment الخاص بنقاط نهاية البطاقة الأخرى).
•قيمة RefundAmount الأقل من المبلغ المحصَّل تُنفِّذ استردادًا جزئيًا.

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

حالة رمز QR

التحقق من حالة رمز QR الخاص بالتاجر انطلاقًا من مرجعه.

Parameter	Type	In	مطلوب	Description
`reference`	string	query	مطلوب	مرجع رمز QR المراد التحقق منه.

الاسترجاع 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، 23=VOUCHER، 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	اختياري	تاريخ/وقت نهاية التصفية.
`Keyword`	string	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
`pageNumber`	int	query	اختياري	رقم الصفحة (يبدأ من 1). القيمة الافتراضية: 1.
`pageSize`	int	query	اختياري	عدد النتائج في الصفحة. القيمة الافتراضية: 10.
`operationType`	list int	query	اختياري	التصفية حسب نوع (أنواع) العملية. معامل قابل للتكرار.
`operationStatus`	list int	query	اختياري	التصفية حسب حالة (حالات) العملية. معامل قابل للتكرار.
`from`	datetime	query	اختياري	العمليات ابتداءً من تاريخ/وقت.
`to`	datetime	query	اختياري	العمليات حتى تاريخ/وقت.
`search`	string	query	اختياري	كلمة مفتاحية للبحث.
`openLoop`	boolean	query	اختياري	تصفية عمليات open loop (خارج محافظ Chari).
`method`	string	query	اختياري	التصفية حسب طريقة الدفع.
`includeDetails`	boolean	query	اختياري	تضمين تفاصيل كل عملية في الاستجابة.

ملاحظات

•نقطة نهاية على مستوى الشريك: لا يُطلب phoneNumber. للاطلاع على عمليات عميل محدد، استخدموا GET /api/operations.
•يقبل operationType وoperationStatus عدة قيم بتكرار المعامل (مثال: ?operationType=1&operationType=2).

ردّ المبلغ

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.
`SortBy`	string	query	اختياري	حقل الفرز.
`SortOrder`	string	query	اختياري	اتجاه الفرز (asc أو desc).
`Name`	string	query	اختياري	التصفية حسب اسم المستفيد.
`BeneficiaryNumber`	string	query	اختياري	التصفية حسب رقم هاتف المستفيد.
`Rib`	string	query	اختياري	التصفية حسب RIB المستفيد.
`Search`	string	query	اختياري	التصفية بكلمة مفتاحية.
`From`	datetime	query	اختياري	تاريخ الإنشاء — البداية.
`To`	datetime	query	اختياري	تاريخ الإنشاء — النهاية.

POST{host}/api/customer/beneficiaries

إضافة مستفيد

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

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

ملاحظات

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

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

تعديل مستفيد

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

Parameter	Type	In	مطلوب	Description
`phoneNumber`	string	query	مطلوب	رقم هاتف العميل (المالك).
`beneficiaryId`	int	path	مطلوب	معرّف المستفيد المراد تعديله.
`name`	string	body	مطلوب	اسم المستفيد. حرفان على الأقل.
`phoneNumber`	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/{cardId}

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

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

Parameter	Type	In	مطلوب	Description
`cardId`	int	path	مطلوب	معرّف البطاقة المرمَّزة المراد حذفها.
`phoneNumber`	string	query	مطلوب	رقم هاتف العميل. الصيغة: +212*********

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

الاطلاع على بطاقات وكيل

الحصول على القائمة المقسَّمة إلى صفحات للبطاقات المرمَّزة الخاصة بوكيل.

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

ملاحظات

•customerTokenizedCardId: المعرّف الفريد للبطاقة المرمَّزة، ويُستخدم كـ {cardId} في نقاط التفاصيل وإعادة التسمية والحذف.
•maskedPan: رقم البطاقة المقنَّع (آخر 4 أرقام).
•requiredCvv: تكون true إذا وجب إدخال رمز CVV مجددًا عند كل إيداع CashIn بهذه البطاقة.
•تُستخدم هذه البطاقات للإيداع بالبطاقة من جهة الوكيل (CashIn بالبطاقة للوكيل).

GET{host}/api/agents/tokenized/cards/{cardId}

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

استرجاع بطاقة مرمَّزة محددة خاصة بوكيل عبر معرّفها.

Parameter	Type	In	مطلوب	Description
`code`	string	query	مطلوب	رمز الوكيل.
`cardId`	int	route	مطلوب	معرّف البطاقة المرمَّزة.

ملاحظات

•يجب أن تكون البطاقة مملوكة للوكيل المحدَّد عبر code، وإلا فلن تُعاد.

PUT{host}/api/agents/tokenized/cards/{cardId}

إعادة تسمية بطاقة وكيل

تحديث اسم (cardName) بطاقة مرمَّزة خاصة بوكيل.

Parameter	Type	In	مطلوب	Description
`code`	string	query	مطلوب	رمز الوكيل.
`cardId`	int	route	مطلوب	معرّف البطاقة المرمَّزة المراد إعادة تسميتها.
`cardName`	string	body	مطلوب	الاسم الجديد للبطاقة.

ملاحظات

•رمز HTTP 200 يؤكد التحديث (دون محتوى استجابة مفصَّل).
•يمكن تعديل التسمية cardName فقط: بقية خصائص البطاقة المرمَّزة غير قابلة للتغيير.

DELETE{host}/api/agents/tokenized/cards/{cardId}

حذف بطاقة وكيل

حذف بطاقة مرمَّزة خاصة بوكيل.

Parameter	Type	In	مطلوب	Description
`cardId`	int	route	مطلوب	معرّف البطاقة المرمَّزة المراد حذفها.
`code`	string	query	مطلوب	رمز الوكيل.

ملاحظات

•رمز HTTP 200 يؤكد الحذف (دون محتوى استجابة مفصَّل).
•الحذف نهائي: لإعادة استخدام البطاقة، يجب ترميزها من جديد.

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

إدارة وكلاء التجزئة: عرض القائمة، إضافة، وتنفيذ عمليات الإيداع/السحب 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}

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

تعديل وكيل تجزئة موجود، يُحدَّد عبر رمزه.

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

ملاحظات

•جميع حقول الجسم اختيارية (nullable) في مخطط swagger.
•استجابة 204 No Content تؤكد التحديث؛ ولا ينشر swagger الإنتاج جسم استجابة.
•400 / 401: استجابة بصيغة ProblemDetails (طلب غير صالح / غير مصرَّح).

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/{code}

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

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

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

ملاحظات

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

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

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

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

GET{host}/api/cards/programs

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

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

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

ملاحظات

•collection : قائمة البرامج.
•count : عدد البرامج.
•يعتمد تقسيم الصفحات على page وtake (وليس PageNumber/PageSize).

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
`status`	int	query	اختياري	التصفية حسب الحالة: 1=Pending، 2=Validated، 3=Rejected.
`page`	int	query	اختياري	رقم صفحة النتائج المراد استرجاعها. يبدأ من 1. القيمة الافتراضية = 1.
`take`	int	query	اختياري	عدد النتائج المعادة في كل صفحة. القيمة الافتراضية = 10.

ملاحظات

•collection : قائمة الطلبات.
•count : عدد الطلبات.
•CardApplicationStatus — 1: PENDING، 2: VALIDATED، 3: REJECTED.
•يعتمد تقسيم الصفحات على page وtake (وليس PageNumber/PageSize).

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

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

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

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

ملاحظات

•collection : قائمة الطلبات.
•count : عدد الطلبات.
•يعتمد تقسيم الصفحات على page وtake (وليس PageNumber/PageSize).

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

قبول طلب

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

Parameter	Type	In	مطلوب	Description
`id`	int	path	مطلوب	معرّف الطلب المراد قبوله.

ملاحظات

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

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

رفض طلب

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

Parameter	Type	In	مطلوب	Description
`id`	int	path	مطلوب	معرّف الطلب المراد رفضه.
`reason`	string	body	اختياري	سبب الرفض (اختياري)، ويُرجَع لاحقًا في rejectionReason.

ملاحظات

•يقبل متن الطلب حقلًا اختياريًا reason: ويُرجَع السبب في rejectionReason الخاص بالطلب.

GET{host}/api/cards

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

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

Parameter	Type	In	مطلوب	Description
`pageNumber`	int	query	اختياري	رقم صفحة النتائج المراد استرجاعها. يبدأ من 1. القيمة الافتراضية = 1.
`pageSize`	int	query	اختياري	عدد النتائج المعادة في كل صفحة. القيمة الافتراضية = 10.
`customerId`	int	query	اختياري	التصفية حسب معرّف العميل.
`accountId`	int	query	اختياري	التصفية حسب معرّف الحساب.
`cardProgramId`	int	query	اختياري	معرّف برنامج البطاقات.
`status`	int	query	اختياري	حالة البطاقة: 1=ISSUED، 2=ACTIVATED، 3=BLOCKED، 4=SUSPENDED، 5=EXPIRED، 6=CANCELLED.
`isVirtual`	boolean	query	اختياري	تصفية البطاقات الافتراضية (true) أو المادية (false).
`schemaId`	int	query	اختياري	معرّف شبكة البطاقة (مثال: VISA).
`deliveryStatusId`	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.
•يُسمّى مرشِّح الحالة status (وليس CardStatusId)؛ وتتم التصفية حسب العميل عبر customerId (لا يوجد PhoneNumber).

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

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

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

Parameter	Type	In	مطلوب	Description
`id`	int	path	مطلوب	معرّف البطاقة.

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

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

تفعيل البطاقة وجعلها جاهزة للاستخدام.

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

ملاحظات

•الاستجابة: كائن البطاقة بعد التحديث. cardStatus 2 = ACTIVATED.

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

حظر البطاقة

حظر البطاقة مؤقتًا عن أي معاملات.

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

ملاحظات

•الاستجابة: كائن البطاقة بعد التحديث. cardStatus 3 = BLOCKED.

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

تعليق البطاقة

تعليق استخدام البطاقة حتى إشعار آخر.

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

ملاحظات

•الاستجابة: كائن البطاقة بعد التحديث. cardStatus 4 = SUSPENDED.

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

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

إعادة تفعيل بطاقة سبق تعليقها.

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

ملاحظات

•الاستجابة: كائن البطاقة بعد التحديث. cardStatus 2 = ACTIVATED.

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

إلغاء البطاقة

إلغاء البطاقة وتعطيلها نهائيًا.

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

ملاحظات

•الاستجابة: كائن البطاقة بعد التحديث. cardStatus 6 = CANCELLED. هذا الإجراء نهائي: لا يمكن إعادة تفعيل البطاقة بعده.

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/card-transactions/card/{cardId}

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

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

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

ملاحظات

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

عمليات الشبكة (Sandbox)

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

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

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

PAN

انقر للنسخ

CVV

انقر للنسخ

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

انقر للنسخ — API: 2608 (أو أي تاريخ مستقبلي)

رمز 3D Secure

انقر للنسخ

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

تنفيذ إيداع CashIn عبر الشبكة

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

Parameter	Type	In	مطلوب	Description
`withContext`	bool	query	اختياري	إعادة النتيجة مع سياقها إن وُجد. القيمة الافتراضية: false.
`reference`	string	body	مطلوب	المرجع الرقمي المُعاد عند إنشاء طلب الإيداع CashIn.
`entity`	string	body	اختياري	كيان الشبكة الذي ينفّذ العملية.

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

تنفيذ سحب CashOut عبر الشبكة

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

Parameter	Type	In	مطلوب	Description
`withContext`	bool	query	اختياري	إعادة النتيجة مع سياقها إن وُجد. القيمة الافتراضية: false.
`reference`	string	body	مطلوب	المرجع الرقمي المُعاد عند إنشاء طلب السحب CashOut.
`entity`	string	body	اختياري	كيان الشبكة الذي ينفّذ العملية.

أحداث 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`	استلام التاجر للدفعة
`payment.confirmed`	تأكيد دفع الفاتورة (الحالة CONFIRME)
`payment.cancelled`	إلغاء دفع الفاتورة (الحالة ANNULE)
`payment.refunded`	ردّ مبلغ دفع الفاتورة (الحالة REMBOURSE)
`payment.failed`	فشل دفع الفاتورة (الحالة FAILED)
`bank-transfer.initiated`	إرسال التحويل البنكي
`bank-transfer.completed`	اكتمال التحويل البنكي (تمت تسويته أو رُفض أو أُعيد — راجعوا OperationStatus)
`bank-transfer.received`	استلام التحويل البنكي
`transfer.received`	استلام التحويل
`cashin.network.executed`	تنفيذ إيداع CashIn بمرجع
`cashout.network.executed`	تنفيذ سحب CashOut بمرجع

مثال body الحدث

customer.level.updated — تحديث مستوى حساب العميل

json

{
  "data": {
    "WebhookId": 12344,
    "EventId": "customer.level.updated",
    "CRequestId": "3f2c8d71-4b6e-4a2f-9c58-1e7d0a6b3c44",
    "OperationId": 0,
    "CreatedAt": "2025-11-05T08:55:00Z",
    "ExecutedAt": "2025-11-05T08:55:04Z",
    "PrimaryAccountNumber": "+212711111111",
    "CustomData": "kyc-upgrade-7841"
  }
}

cashin.card.authorized — قبول إيداع CashIn بالبطاقة

json

{
  "data": {
    "WebhookId": 12346,
    "EventId": "cashin.card.authorized",
    "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"
  }
}

payment.card.authorized — قبول الدفع بالبطاقة

json

{
  "data": {
    "WebhookId": 12347,
    "EventId": "payment.card.authorized",
    "CRequestId": "c91d2a47-6f3b-4e8d-a1c5-7b9e0d2f4a61",
    "OperationId": 641205,
    "OperationType": 24,
    "OperationStatus": 2,
    "CreatedAt": "2025-11-05T09:47:00Z",
    "ExecutedAt": "2025-11-05T09:47:21Z",
    "Amount": 450.00,
    "FeeAmount": 0.00,
    "CustomData": "order-88123",
    "PrimaryAccountNumber": "+212711111111",
    "SecondaryAccountNumber": "+212722222222",
    "Method": "Card",
    "GatewayTrackId": "9ad2f3b1",
    "GatewayOrderId": "20251105_00072",
    "GatewayReferenceId": "4b7e91cc"
  }
}

payment.received — استلام التاجر للدفعة

json

{
  "data": {
    "WebhookId": 12348,
    "EventId": "payment.received",
    "CRequestId": "5e8a1c3d-92f4-4b7a-8d6e-0c1b3a5f7e92",
    "OperationId": 652118,
    "OperationType": 5,
    "OperationStatus": 2,
    "CreatedAt": "2025-11-05T11:02:00Z",
    "ExecutedAt": "2025-11-05T11:02:09Z",
    "Amount": 250.00,
    "FeeAmount": 0.00,
    "CustomData": "pos-ticket-4521",
    "PrimaryAccountNumber": "+212711111111",
    "SecondaryAccountNumber": "+212722222222",
    "Method": null
  }
}

payment.confirmed — تأكيد دفع الفاتورة (CONFIRME)

json

{
  "data": {
    "WebhookId": 12349,
    "EventId": "payment.confirmed",
    "CRequestId": "d2f7b9e1-3c5a-4d8f-b6a0-9e4c1d7a2b53",
    "OperationId": 673402,
    "OperationType": 25,
    "OperationStatus": 2,
    "CreatedAt": "2025-11-05T11:30:00Z",
    "ExecutedAt": "2025-11-05T11:30:41Z",
    "Amount": 286.50,
    "FeeAmount": 5.00,
    "CustomData": "invoice-2025-1105",
    "PrimaryAccountNumber": "+212711111111",
    "Method": null
  }
}

payment.cancelled — إلغاء دفع الفاتورة (ANNULE)

json

{
  "data": {
    "WebhookId": 12350,
    "EventId": "payment.cancelled",
    "CRequestId": "e6a3c8d5-1b7f-4a2e-9c4d-3f8b0a6e1d27",
    "OperationId": 673415,
    "OperationType": 25,
    "OperationStatus": 4,
    "CreatedAt": "2025-11-05T11:32:00Z",
    "ExecutedAt": "2025-11-05T11:32:38Z",
    "Amount": 286.50,
    "FeeAmount": 0.00,
    "CustomData": "invoice-2025-1105",
    "PrimaryAccountNumber": "+212711111111",
    "Method": null
  }
}

payment.refunded — ردّ مبلغ دفع الفاتورة (REMBOURSE)

json

{
  "data": {
    "WebhookId": 12351,
    "EventId": "payment.refunded",
    "CRequestId": "f1b4d7a2-8e6c-4f3a-b5d9-2a7c0e4b8f16",
    "OperationId": 674033,
    "OperationType": 25,
    "OperationStatus": 2,
    "CreatedAt": "2025-11-05T14:05:00Z",
    "ExecutedAt": "2025-11-05T14:05:33Z",
    "Amount": 286.50,
    "FeeAmount": 0.00,
    "CustomData": "invoice-2025-1105",
    "PrimaryAccountNumber": "+212711111111",
    "Method": null
  }
}

payment.failed — فشل دفع الفاتورة (FAILED)

json

{
  "data": {
    "WebhookId": 12352,
    "EventId": "payment.failed",
    "CRequestId": "0a5c9e2f-7d1b-4c6a-8f3e-b9d4a2c7e051",
    "OperationId": 674590,
    "OperationType": 25,
    "OperationStatus": 3,
    "CreatedAt": "2025-11-05T14:18:00Z",
    "ExecutedAt": "2025-11-05T14:18:27Z",
    "Amount": 286.50,
    "FeeAmount": 0.00,
    "CustomData": "invoice-2025-1105",
    "PrimaryAccountNumber": "+212711111111",
    "Method": null
  }
}

bank-transfer.initiated — إرسال التحويل البنكي

json

{
  "data": {
    "WebhookId": 12353,
    "EventId": "bank-transfer.initiated",
    "CRequestId": "9c2e5a7b-4d8f-4b1c-a6e3-0f7d2b5c8a94",
    "OperationId": 918274,
    "OperationType": 9,
    "OperationStatus": 1,
    "CreatedAt": "2025-11-05T10:05:00Z",
    "ExecutedAt": "2025-11-05T10:05:12Z",
    "Amount": 12000.00,
    "FeeAmount": 200.00,
    "CustomData": "supplier-invoice-1188",
    "PrimaryAccountNumber": "+212711111111",
    "SecondaryAccountNumber": "+212722222222",
    "Method": null,
    "Reference": "BANK-REF-7Q4TZ9",
    "BankTransferBeneficiaryName": "Hicham Bouzid"
  }
}

bank-transfer.completed — اكتمال التحويل البنكي

json

{
  "data": {
    "WebhookId": 12345,
    "EventId": "bank-transfer.completed",
    "CRequestId": "a4d1e0b5-9f6a-4c1d-bc7b-2d0a7f4b9b12",
    "OperationId": 924381,
    "OperationType": 9,
    "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": null,
    "Reference": "BANK-REF-9FJ2X7",
    "BankTransferBeneficiaryName": "Aminata Diop"
  }
}

bank-transfer.received — استلام التحويل البنكي

json

{
  "data": {
    "WebhookId": 12354,
    "EventId": "bank-transfer.received",
    "CRequestId": "1d6f3b8a-5c9e-4a7d-b2f4-8e0a3c6d9b15",
    "OperationId": 926504,
    "OperationType": 9,
    "OperationStatus": 2,
    "CreatedAt": "2025-11-05T12:20:00Z",
    "ExecutedAt": "2025-11-05T12:20:31Z",
    "Amount": 8000.00,
    "FeeAmount": 0.00,
    "PrimaryAccountNumber": "+212722222222",
    "Method": null,
    "Reference": "BANK-REF-5N1WD4",
    "BankTransferBeneficiaryName": "Yassine El Amrani"
  }
}

transfer.received — استلام التحويل

json

{
  "data": {
    "WebhookId": 12355,
    "EventId": "transfer.received",
    "CRequestId": "2b7d0f4c-9a3e-4d5b-8c1f-6e9b2d4a7c38",
    "OperationId": 934187,
    "OperationType": 3,
    "OperationStatus": 2,
    "CreatedAt": "2025-11-05T13:10:00Z",
    "ExecutedAt": "2025-11-05T13:10:06Z",
    "Amount": 500.00,
    "FeeAmount": 0.00,
    "CustomData": "p2p-note-201",
    "PrimaryAccountNumber": "+212711111111",
    "SecondaryAccountNumber": "+212722222222",
    "Method": null
  }
}

cashin.network.executed — تنفيذ إيداع CashIn بمرجع

json

{
  "data": {
    "WebhookId": 12356,
    "EventId": "cashin.network.executed",
    "CRequestId": "4e9b2d6f-0c5a-4e8b-a3d7-1f6c8b0e5a29",
    "OperationId": 947261,
    "OperationType": 1,
    "OperationStatus": 2,
    "CreatedAt": "2025-11-05T15:40:00Z",
    "ExecutedAt": "2025-11-05T15:41:12Z",
    "Amount": 250.00,
    "FeeAmount": 0.00,
    "CustomData": "cashin-req-778",
    "PrimaryAccountNumber": "+212711111111",
    "Method": "Network",
    "NetworkName": "AGENCY",
    "Reference": "1122334455"
  }
}

cashout.network.executed — تنفيذ سحب CashOut بمرجع

json

{
  "data": {
    "WebhookId": 12357,
    "EventId": "cashout.network.executed",
    "CRequestId": "8f0d4b7e-2a6c-4c9f-b1e5-3d8a0f2c6b47",
    "OperationId": 948730,
    "OperationType": 2,
    "OperationStatus": 2,
    "CreatedAt": "2025-11-05T16:22:00Z",
    "ExecutedAt": "2025-11-05T16:23:05Z",
    "Amount": 200.00,
    "FeeAmount": 5.00,
    "CustomData": "cashout-req-902",
    "PrimaryAccountNumber": "+212711111111",
    "Method": "Network",
    "NetworkName": "AGENCY",
    "Reference": "5566778899"
  }
}

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

تُغلَّف جميع استجابات 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/operations/service/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 (انظر جدول "الأنواع والمراجع").

POST{host}/api/operations/service/telco/recharge/preview

تعبئة رصيد العميل — معاينة

التحقق من إمكانية تنفيذ تعبئة رصيد هاتفية مدفوعة من wallet العميل (المبلغ، الرسوم) قبل التنفيذ.

Parameter	Type	In	مطلوب	Description
`customerPhoneNumber`	string	body	مطلوب	رقم هاتف العميل الذي سيُخصم من wallet الخاص به. الصيغة: +212*********
`recipientPhoneNumber`	string	body	مطلوب	رقم الهاتف المراد تعبئته. الصيغة: +212*********
`amount`	decimal	body	مطلوب	مبلغ التعبئة.
`operator`	int	body	مطلوب	المشغّل: 1 = اتصالات المغرب، 2 = Orange، 3 = Inwi.
`rechargeType`	int	body	مطلوب	نوع التعبئة: 0 = كلاسيكية، 1 = منتج (قيم enum في swagger: من 0 إلى 3).
`productCode`	int	body	اختياري	رمز المنتج المُعاد من نقطة نهاية الكتالوج (يُستخدم للتعبئة من نوع منتج).
`rechargeStatus`	int	body	اختياري	حالة التعبئة (قيم enum في swagger: من 0 إلى 4). حقل ضمن DTO المشترك مع الاستجابات.
`beneficiaryId`	int	body	اختياري	مرجع إلى مستفيد موجود (اختياري).

ملاحظات

•صيغة «العميل»: يُخصم من wallet العميل (customerPhoneNumber) — بخلاف /api/operations/service/telco/recharge/b2b التي تخصم من حساب الوكيل الرئيسي.
•operator: 1 = اتصالات المغرب، 2 = Orange، 3 = Inwi.
•rechargeType: 0 = كلاسيكية، 1 = منتج؛ للتعبئة من نوع منتج، استخدموا productCode المُعاد من الكتالوج.

POST{host}/api/operations/service/telco/recharge

تعبئة رصيد العميل — تنفيذ

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

Parameter	Type	In	مطلوب	Description
`customerPhoneNumber`	string	body	مطلوب	رقم هاتف العميل الذي سيُخصم من wallet الخاص به. الصيغة: +212*********
`recipientPhoneNumber`	string	body	مطلوب	رقم الهاتف المراد تعبئته. الصيغة: +212*********
`amount`	decimal	body	مطلوب	مبلغ التعبئة.
`operator`	int	body	مطلوب	المشغّل: 1 = اتصالات المغرب، 2 = Orange، 3 = Inwi.
`rechargeType`	int	body	مطلوب	نوع التعبئة: 0 = كلاسيكية، 1 = منتج (قيم enum في swagger: من 0 إلى 3).
`productCode`	int	body	اختياري	رمز المنتج المُعاد من نقطة نهاية الكتالوج (يُستخدم للتعبئة من نوع منتج).
`rechargeStatus`	int	body	اختياري	حالة التعبئة (قيم enum في swagger: من 0 إلى 4). حقل ضمن DTO المشترك مع الاستجابات.
`beneficiaryId`	int	body	اختياري	مرجع إلى مستفيد موجود (اختياري).

ملاحظات

•استدعوا أولًا /api/operations/service/telco/recharge/preview للتحقق من المبلغ والرسوم.
•صيغة «العميل»: يُخصم من wallet العميل — بينما تخصم صيغة /b2b من حساب الوكيل الرئيسي.

GET{host}/api/operations/service/telco/recharge

سجلّ تعبئات العميل

استرجاع قائمة عمليات تعبئة الرصيد الهاتفية لعميل، مع تقسيم الصفحات والتصفية حسب الحالة.

Parameter	Type	In	مطلوب	Description
`phoneNumber`	string	query	مطلوب	رقم هاتف العميل. الصيغة: +212*********
`pageSize`	int	query	اختياري	عدد العناصر في الصفحة.
`pageNumber`	int	query	اختياري	رقم الصفحة المراد استرجاعها.
`status`	list int	query	اختياري	حالة (حالات) التعبئة للتصفية (قيم enum في swagger: من 0 إلى 4). مُعامل قابل للتكرار.

ملاحظات

•الاستجابة هي قائمة عمليات تعبئة (بدون غلاف تقسيم صفحات: استخدموا pageSize/pageNumber للتنقّل).
•المُعامل status قابل للتكرار للتصفية حسب عدة حالات، مثال: status=2&status=3.

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

كتالوج الاتصالات (الصيغة العامة)

صيغة عامة لنقطة نهاية الكتالوج: تستقبل رقم هاتف ومبلغًا ومشغّلًا، وتُرجِع قائمة من السلاسل النصية.

Parameter	Type	In	مطلوب	Description
`phoneNumber`	string	body	اختياري	رقم الهاتف المعني. الصيغة: +212*********
`amount`	int	body	مطلوب	مبلغ التعبئة المزمعة.
`operator`	int	body	مطلوب	المشغّل: 1 = اتصالات المغرب، 2 = Orange، 3 = Inwi.

ملاحظات

•لا يوفّر swagger أي summary لهذه النقطة؛ تلتزم هذه البطاقة حصريًا بالمخططات المعلنة.
•الاستجابة 200 معلنة كمصفوفة بسيطة من السلاسل النصية، دون بنية إضافية موثّقة.
•للحصول على كتالوج مُهيكل (productCode، التسميات، التوفّر)، استخدموا /api/services/telco/catalog/b2b.

GET{host}/api/services/telco/export

تصدير بيانات الاتصالات

إطلاق تصدير بيانات الاتصالات لفترة زمنية محددة. تُرجِع قيمة منطقية تدل على نجاح الطلب.

Parameter	Type	In	مطلوب	Description
`from`	datetime	query	مطلوب	تاريخ/وقت بداية الفترة المراد تصديرها (ISO 8601).
`to`	datetime	query	مطلوب	تاريخ/وقت نهاية الفترة المراد تصديرها (ISO 8601).

ملاحظات

•المُعاملان from وto إلزاميان.
•الاستجابة 200 قيمة منطقية: true إذا قُبل طلب التصدير.

القسائم

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

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*********.
`page`	int	query	اختياري	رقم صفحة النتائج المراد استرجاعها. يبدأ من 1. القيمة الافتراضية: 1.
`take`	int	query	اختياري	عدد النتائج المعادة في كل صفحة. القيمة الافتراضية: 10.

ملاحظات

•لا يوجد مرشِّح brandId في نقطة النهاية هذه: للاطلاع على علامة تجارية محددة، استخدموا GET /api/vouchers/brands/{id}.

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: مبلغ استرداد نقدي اختياري.

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

خدمة القسائم — معاينة

التحقق من إمكانية شراء قسيمة محلية معرَّفة عبر SKU الخاص بها، قبل التنفيذ. تُرجِع كائن القسيمة مكتملًا (بما في ذلك المبلغ).

Parameter	Type	In	مطلوب	Description
`customerPhoneNumber`	string	body	مطلوب	رقم هاتف العميل، بالصيغة +212*********.
`skuId`	int	body	مطلوب	معرّف SKU للقسيمة المحلية (انظر قائمة القسائم المحلية).
`providerSkuId`	string	body	اختياري	معرّف SKU لدى المزوّد (إن وُجد).
`destinationPhoneNumber`	string	body	اختياري	رقم هاتف المستلِم، بالصيغة +212*********.
`beneficiaryName`	string	body	اختياري	حقل نصي حر يصف اسم المستفيد.
`amount`	decimal	body	اختياري	مبلغ القسيمة (يملؤه الخادم في الاستجابة).
`providerId`	int	body	اختياري	معرّف المزوّد الذي يوفّر القسيمة.

ملاحظات

•النطاق (scope) المطلوب: operations:voucher (كما هو مذكور في swagger).
•تُرجِع الاستجابة نفس كائن القسيمة الوارد في الطلب، مكتملًا (لا سيما amount).
•يجب عدم الخلط مع /api/operations/voucher/preview (بطاقة «شراء قسيمة — معاينة») التي تستخدم متن طلب مختلفًا وتُرجِع غلاف معاينة عملية.

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

خدمة القسائم — شراء

تنفيذ شراء قسيمة محلية معرَّفة عبر SKU الخاص بها. يُخصم من wallet العميل وتُعاد معلومات العملية.

Parameter	Type	In	مطلوب	Description
`customerPhoneNumber`	string	body	مطلوب	رقم هاتف العميل، بالصيغة +212*********.
`skuId`	int	body	مطلوب	معرّف SKU للقسيمة المحلية (انظر قائمة القسائم المحلية).
`providerSkuId`	string	body	اختياري	معرّف SKU لدى المزوّد (إن وُجد).
`destinationPhoneNumber`	string	body	اختياري	رقم هاتف المستلِم، بالصيغة +212*********.
`beneficiaryName`	string	body	اختياري	حقل نصي حر يصف اسم المستفيد.
`amount`	decimal	body	اختياري	مبلغ القسيمة (إن وُجد).
`providerId`	int	body	اختياري	معرّف المزوّد الذي يوفّر القسيمة.

ملاحظات

•النطاق (scope) المطلوب: operation:voucher (كما هو مذكور في swagger).
•استدعوا أولًا /api/operations/service/voucher/preview للتحقق من القسيمة ومبلغها.

GET{host}/api/vouchers

قائمة القسائم المحلية

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

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

ملاحظات

•لا يوثّق swagger مخطط الاستجابة 200 لهذه النقطة (تُوصف فقط أخطاء 400/500).
•يُستخدم skuId الخاص بالقسائم المُعادة في نقطتي المعاينة والشراء (/api/operations/service/voucher).

GET{host}/api/vouchers/product

منتجات Click & Collect

استرجاع القائمة المقسّمة إلى صفحات لمنتجات «click & collect» المتاحة.

Parameter	Type	In	مطلوب	Description
`page`	int	query	اختياري	رقم الصفحة المراد استرجاعها.
`take`	int	query	اختياري	عدد العناصر في الصفحة.

ملاحظات

•لا يوثّق swagger مخطط الاستجابة 200 لهذه النقطة (تُوصف فقط أخطاء 400/500).
•استخدموا configId الخاص بالمنتج مع نقطة نهاية التفاصيل /api/vouchers/products/{configId}.

GET{host}/api/vouchers/products/{configId}

تفاصيل منتج

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

Parameter	Type	In	مطلوب	Description
`configId`	string	path	مطلوب	معرّف إعداد المنتج (تُعيده قائمة المنتجات).

ملاحظات

•لا يوثّق swagger مخطط الاستجابة 200 لهذه النقطة (تُوصف فقط أخطاء 400/500).
•يأتي configId من قائمة منتجات «click & collect» ‏(/api/vouchers/product).

دفع الفواتير

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

GET{host}/api/bills/creanciers

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

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

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

ملاحظات

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

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

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

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

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

ملاحظات

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

GET{host}/api/bills/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/bills/impayes?phoneNumber={phoneNumber}&creancierId={creancierId}&creanceId={creanceId}

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

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

Parameter	Type	In	مطلوب	Description
`phoneNumber`	string	query	مطلوب	رقم هاتف المستخدم النهائي لدى Chari Money، بالصيغة الدولية (مثال: +212670770743).
`creancierId`	string	query	مطلوب	معرّف الدائن (4 أرقام).
`creanceId`	string	query	مطلوب	معرّف المستحق (خانتان).
`creancierVals`	array	body	مطلوب	مصفوفة القيم المُدخلة من المستخدم: كائنات { nomChamp, valChamp } (باستثناء الحقول من نوع typeChamp=libelle). تنبيه: تُسمى الخاصية valChamp (وليس valeurChamp) في هذا الجسم.
`alias`	string	body	اختياري	الاسم (alias) المراد حفظه إذا أُضيفت الفاتورة إلى المفضلات.
`addToFavorites`	boolean	body	اختياري	true لإضافة الفاتورة إلى مفضلات العميل.
`qrCodeContent`	string	body	اختياري	محتوى رمز QR ممسوح، كبديل لإدخال حقول التعريف.

ملاحظات

•تنتقل المعاملة إلى حالة EN_ATTENTE؛ احتفظوا بـ refTxFatourati من أجل /confirm. صالحة لمدة 7 أيام تقويمية.
•creancierVals: تُسمى خاصية القيمة valChamp في هذا الجسم (وليس valeurChamp كما في استجابتي /form و/impayes)؛ لا تُرسلوا الحقول من نوع typeChamp=libelle.
•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/bills/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. يربط الاستدعاء بالمعاملة المفتوحة.
`totalPayment`	boolean	body	اختياري	true لتسوية جميع غير المدفوعات، وfalse لاختيار جزئي.
`listeArticleSelectionnes`	array	body	مطلوب	مجموعة جزئية من impayesParams اختارها المستخدم: كائنات { idArticle, prixTTC, typeArticle, dateFacture, description }.
`creancierVals`	array	body	مطلوب	حقول التعريف المُدخلة: كائنات { nomChamp, valChamp }. تنبيه: تُسمى الخاصية valChamp (وليس valeurChamp) في هذا الجسم، ولا يُقبل فيه libelle.
`globalParams`	array	body	اختياري	المعاملات العامة المُعادة من /impayes: كائنات { libelle, nomChamp, valeurChamp }.

ملاحظات

•الجسم مطابق لجسم /preview: يستخدم creancierVals كائنات { nomChamp, valChamp } (دون libelle)، ولا تقبل عناصر listeArticleSelectionnes سوى { idArticle, prixTTC, typeArticle, dateFacture, description } (دون extraArticleParams).
•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).

POST{host}/api/bills/preview?phoneNumber={phoneNumber}

معاينة الدفع

معاينة تسوية مجموعة المقالات المختارة قبل التأكيد. الجسم مطابق لجسم /confirm: يتحقق الاستدعاء من الاختيار (الدائن، المستحق، المقالات) للمستخدم المحدَّد بـ phoneNumber، دون تنفيذ الدفع.

Parameter	Type	In	مطلوب	Description
`phoneNumber`	string	query	مطلوب	رقم هاتف المستخدم النهائي لدى Chari Money، بالصيغة الدولية (+212*********).
`creancierId`	string	body	مطلوب	معرّف الدائن (4 أرقام، نفس قيم /impayes).
`creanceId`	string	body	مطلوب	معرّف المستحق (خانتان).
`refTxFatourati`	string	body	مطلوب	المرجع المُعاد من /impayes (12 رقمًا). يربط الاستدعاء بالمعاملة المفتوحة.
`totalPayment`	boolean	body	اختياري	true لتسوية جميع غير المدفوعات، وfalse لاختيار جزئي.
`listeArticleSelectionnes`	array	body	مطلوب	المقالات التي اختارها المستخدم: كائنات { idArticle, prixTTC, typeArticle, dateFacture, description } مأخوذة من impayesParams.
`creancierVals`	array	body	مطلوب	حقول التعريف المُدخلة: كائنات { nomChamp, valChamp }. تنبيه: تُسمى الخاصية valChamp (وليس valeurChamp) في هذا الجسم.
`globalParams`	array	body	اختياري	المعاملات العامة المُعادة من /impayes: كائنات { libelle, nomChamp, valeurChamp }.

ملاحظات

•الجسم مطابق لجسم /confirm: ابنوه من استجابتي /form و/impayes، ثم أعيدوا إرساله كما هو إلى /confirm بعد تأكيد المستخدم.
•creancierVals: تُسمى خاصية القيمة valChamp في هذا الجسم (وليس valeurChamp كما في استجابتي /form و/impayes).
•totalPayment: القيمة true = تسوية جميع غير المدفوعات، وfalse = اختيار جزئي (الدفع الجزئي مدعوم في الوحدة).
•لا ينشر swagger الإنتاج مخطط استجابة مفصّلًا لهذه النقطة (200 Success)؛ المثال أعلاه إرشادي.

GET{host}/api/bills/history?phoneNumber={phoneNumber}&pageNumber={pageNumber}&pageSize={pageSize}

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

تُرجِع الفواتير القابلة للدفع وسجل دفع الفواتير للعميل المحدَّد برقم هاتفه لدى Chari Money. النتائج مقسّمة إلى صفحات عبر pageNumber وpageSize.

Parameter	Type	In	مطلوب	Description
`phoneNumber`	string	query	مطلوب	رقم هاتف العميل لدى Chari Money، بالصيغة الدولية (+212*********).
`pageNumber`	int	query	اختياري	رقم الصفحة المراد إرجاعها.
`pageSize`	int	query	اختياري	عدد العناصر في كل صفحة.

ملاحظات

•التقسيم إلى صفحات: pageNumber وpageSize اختياريان؛ وعند غيابهما يُطبَّق التقسيم الافتراضي للخادم.
•لا ينشر swagger الإنتاج المخطط المفصّل للاستجابة (200 Success)؛ المثال أعلاه إرشادي ويعيد استخدام مفردات الوحدة (refTxFatourati وmontantTotalTTC والحالات CONFIRME/ANNULE…).

GET{host}/api/bills/reference/status?reference={reference}

حالة cash-in حسب المرجع

تُرجِع حالة cash-in عبر Fatourati انطلاقًا من مرجعه: مؤشر التنفيذ، الحالة، المبلغ، الطوابع الزمنية، ومعرّف عملية Chari المرتبطة.

Parameter	Type	In	مطلوب	Description
`reference`	string	query	اختياري	مرجع Fatourati الخاص بعملية cash-in المراد الاستعلام عنها.

ملاحظات

•تُعاد الاستجابة في الجذر، دون غلاف { "data": … }.
•204 No Content: لا توجد معاملة مطابقة للمرجع المُقدَّم.
•400 / 401: استجابة بصيغة ProblemDetails (طلب غير صالح / غير مصرَّح).

GET{host}/api/bills/bill-receipt/{operationId}?phoneNumber={phoneNumber}

تنزيل إيصال الدفع

تنزيل إيصال دفع فاتورة انطلاقًا من معرّف عملية Chari. يُحدَّد العميل برقم هاتفه لدى Chari Money.

Parameter	Type	In	مطلوب	Description
`operationId`	int	path	مطلوب	معرّف عملية Chari الخاصة بدفع الفاتورة (انظر chariOperationId في /reference/status أو في السجل).
`phoneNumber`	string	query	مطلوب	رقم هاتف العميل لدى Chari Money، بالصيغة الدولية (+212*********). يجب أن يطابق العميل الذي نفّذ العملية.

ملاحظات

•تحتوي استجابة 200 على ملف إيصال الدفع (محتوى ثنائي للتنزيل)، وليس جسم JSON.
•يجب أن يذكر الإيصال مرجع التسوية (refReglement) المُعاد من /confirm.

GET{host}/api/bills/favorite?phoneNumber={phoneNumber}

قائمة المفضلات

تُرجِع قائمة الفواتير المفضلة لدى العميل، مجمّعة حسب فئة الدائن. تتيح المفضلات إعادة بدء دفع فاتورة متكررة بسرعة دون إعادة إدخال بيانات التعريف.

Parameter	Type	In	مطلوب	Description
`phoneNumber`	string	query	مطلوب	رقم هاتف العميل لدى Chari Money، بالصيغة الدولية (+212*********).

ملاحظات

•تُجمَّع المفضلات حسب فئة الدائن.
•favoriteId هو المعرّف المستخدم مع PUT وDELETE /api/bills/favorite/{favoriteId}.
•لا ينشر swagger الإنتاج المخطط المفصّل للاستجابة (200 Success)؛ المثال أعلاه إرشادي.

PUT{host}/api/bills/favorite/{favoriteId}?phoneNumber={phoneNumber}

تحديث مفضلة

تحديث alias لفاتورة مفضلة لدى العميل. الـ alias هو التسمية المعروضة للمستخدم (مثال: « Maison Marrakech »).

Parameter	Type	In	مطلوب	Description
`favoriteId`	int	path	مطلوب	معرّف المفضلة (المُحصَّل عليه عبر GET /api/bills/favorite).
`phoneNumber`	string	query	مطلوب	رقم هاتف العميل مالك المفضلة لدى Chari Money، بالصيغة الدولية (+212*********).
`alias`	string	body	مطلوب	الاسم الجديد (alias) للمفضلة.

ملاحظات

•alias هو الحقل الوحيد القابل للتعديل عبر هذه النقطة.
•استجابة 200 تؤكد التحديث؛ ولا ينشر swagger الإنتاج جسم استجابة.

DELETE{host}/api/bills/favorite/{favoriteId}?phoneNumber={phoneNumber}

حذف مفضلة

حذف فاتورة مفضلة لدى العميل. لا يؤثر الحذف على المدفوعات المنجزة سابقًا.

Parameter	Type	In	مطلوب	Description
`favoriteId`	int	path	مطلوب	معرّف المفضلة المراد حذفها (المُحصَّل عليه عبر GET /api/bills/favorite).
`phoneNumber`	string	query	مطلوب	رقم هاتف العميل مالك المفضلة لدى Chari Money، بالصيغة الدولية (+212*********).

ملاحظات

•استجابة 200 تؤكد الحذف؛ ولا ينشر swagger الإنتاج جسم استجابة.

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

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

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	السجل التجاري

نطاقات API

النطاقات المصرَّح بها في مواصفة واجهة الإنتاج. نقاط النهاية غير المدرجة هنا لا تصرّح المواصفة بأي نطاق لها؛ ويظل مفتاح API محدِّدًا للوصول الإجمالي في جميع الأحوال.

Scope	Endpoints
`cards:read`	`GET /api/cards`
`operation:voucher`	`POST /api/operations/service/voucherPOST /api/operations/voucher/confirm`
`operations:cashin`	`POST /api/operations/cashin/cardPOST /api/operations/cashin/card/agentPOST /api/operations/cashin/card/agent/previewPOST /api/operations/cashin/card/previewPOST /api/operations/cashin/card/{cardId}GET /api/operations/cashin/requestGET /api/operations/cashout/requestPOST /api/operations/cashin/agentPOST /api/operations/cashin/requestPOST /api/operations/fatourati/cashin/request`
`operations:cashout`	`GET /api/operations/cashin/requestGET /api/operations/cashout/requestPOST /api/operations/cashout/agentPOST /api/operations/cashout/request`
`operations:merchant-payment`	`POST /api/operations/merchant/payment/cardPOST /api/operations/merchant/payment/card/capturePOST /api/operations/merchant/payment/card/previewPOST /api/operations/merchant/payment/card/reversePOST /api/operations/merchant/payment/push/manual/previewPOST /api/operations/merchant/payment/push/qrcodePOST /api/operations/merchant/payment/push/qrcode/previewPOST /api/operations/merchant/payment/tokenized/card/{cardId}`
`operations:read`	`GET /api/operationsGET /api/operations/allGET /api/operations/{operationId}`
`operations:refund`	`POST /api/operations/merchant/payment/card/refundPOST /api/operations/refundPOST /api/operations/refund/preview`
`operations:transfer`	`POST /api/operations/transferPOST /api/operations/transfer/preview`
`operations:voucher`	`POST /api/operations/service/voucher/previewPOST /api/operations/voucher/preview`

رموز الأخطاء

رموز حالة 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 الخاص بالبيئة الحقيقية.

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

الحصول على وصول sandbox

املؤوا هذا النموذج لإطلاق عملية الإدماج التقني: مفتاح API الخاص بـ sandbox، إدراج عناوين IP في القائمة البيضاء، تفعيل الوحدات، ودعوة Partner Back Office. يعود إليكم فريق ChariBaaS سريعًا. الوصول إلى بيئة sandbox خطوة تقنية: يبقى أي استغلال للخدمات في الإنتاج خاضعًا لموافقة بنك المغرب (اتفاق عدم ممانعة).

وثائق API

البدء

Headers المصادقة

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

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

مرجع تفاعلي (Swagger UI)

مواصفة OpenAPI (Swagger)

Postman Collection

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

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

ما هو M-Wallet؟

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

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

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

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

أدلة التكامل

البدء في بيئة sandbox: الوصول، التفعيلات، أولى الاستدعاءات

الحصول على الوصول إلى sandbox

التحقق من المفتاح: أول استدعاء

طلب تفعيل الوحدات اللازمة

طلب رصيد اختباري

استخدام البطاقة التجريبية (3D Secure)

تجهيز أدوات التكامل

التحضير للانتقال إلى الإنتاج

إنشاء محفظة عميل وتفعيلها من البداية إلى النهاية

التحقق من حالة الرقم

تسجيل العميل (walletType)

تأكيد رمز OTP (autoActivate)

إنشاء الرمز السري PIN لتفعيل المحفظة

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

الاطلاع على رصيد المحفظة

استرجاع الملف الشخصي الكامل للعميل

الإيداع بالبطاقة مع 3D Secure: من المعاينة إلى webhook

معاينة الإيداع

التنفيذ بالبطاقة التجريبية في sandbox

إتمام مصادقة 3D Secure

استقبال webhook بالحدث cashin.card.authorized

التحقق من العملية

متغيّر الوكيل: إضافة رصيد إلى محفظة وكيل

إعادة الإيداع بالبطاقة المرمَّزة

الدفع للتاجر بالبطاقة: من المعاينة إلى الاسترداد

معاينة الدفعة (الرسوم، الجدوى)

أول تحصيل: التنفيذ مع autoCapture

التحقق من عودة 3D Secure

الدفع على مرحلتين: التفويض ثم التحصيل

إلغاء تفويض غير محصَّل (reverse)

استرداد دفعة محصَّلة (كليًا أو جزئيًا)

التحصيل مجددًا بالبطاقة المرمَّزة

خطوة إضافية: حالة رمز QR الخاص بالتاجر

الإيداع/السحب بمرجع (cash-in / cash-out): من الطلب إلى التنفيذ

إنشاء طلب الإيداع CashIn

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

تنفيذ الإيداع CashIn من جهة الوكيل

تنفيذ السحب CashOut المماثل

محاكاة التنفيذ الشبكي في sandbox

استقبال التأكيد عبر webhook

نسخة Fatourati: طلب الإيداع CashIn المخصص

دفع الفواتير عبر Fatourati: من الدائن إلى الإيصال

عرض قائمة دائني Fatourati

عرض مستحقات الدائن المختار

بناء نموذج التعريف الديناميكي

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

تأكيد الدفع (بعد المعاينة)

تتبّع المعاملة وتسليم الإيصال

الاستماع إلى أحداث Webhook من نوع payment.*

تعبئة الرصيد الهاتفية B2B: الكتالوج، التعبئة، صيغة العميل

التحقق من تفعيل خدمة telco

استرجاع كتالوج العروض (B2B)

تنفيذ التعبئة B2B

صيغة العميل: معاينة التعبئة

صيغة العميل: تنفيذ التعبئة

الاطلاع على سجلّ تعبئات العميل

التعامل مع الأخطاء

بيع القسائم: العلامات التجارية، المقالات، المعاينة، الرمز

التحقق من تجهيز الكتالوج

عرض العلامات التجارية المتاحة

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

معاينة الشراء

التأكيد وتسليم رمز القسيمة

التعمق أكثر: الكتالوج المحلي (SKU)