البدء

الإصدار 2.0 · آخر تحديث 14 avril 2026

Bienvenue dans la documentation officielle de l'API Banking-as-a-Service (BAAS) de Chari Money. Cette API REST permet aux fintechs, plateformes et développeurs d'intégrer une infrastructure financière complète dans leurs applications : ouverture de comptes avec vérification KYC, transactions wallet-à-wallet, dépôts par carte bancaire (3D Secure), virements bancaires via RIB, paiements marchands multi-canal (téléphone, QR Code, carte), gestion des bénéficiaires, agents retail et webhooks temps réel. Tous les endpoints suivent un modèle preview/execute avec confirmation asynchrone par webhook.

Headers المصادقة

Incluez les en-têtes suivants dans toutes vos requêtes API :

Header	Type	مطلوب	Description
`Chari-Api-Key`	string	مطلوب	Clé API pour l'authentification. Fournie par Chari pour chaque environnement.
`C-Request-Id`	string	اختياري	Identifiant unique par requête pour le traçage. Renvoyé dans la réponse. Format recommandé : UUID v4. Ex : 69906411-0aa24a89-ab2005ca-9d18dc15

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

PAN

4918914107195005

CVV

123

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

08/26 (ou toute date future)

رمز 3D Secure

555

جديد

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

Pack complet optimisé pour les LLMs et assistants IA : documentation Markdown, JSON Schemas, diagrammes Mermaid, spécification OpenAPI 3.0, exemples cURL et règles de validation. Idéal pour RAG, code generation et intégration avec Cursor, Copilot ou Claude.

OpenAPI 3.0JSON SchemaMermaidMarkdowncURL

تنزيل .zip

Postman Collection

Téléchargez la collection Postman complète pour tester tous les endpoints de l'API.

تنزيل

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

v1.8

2025-11-05

Documentation initiale. Couverture complète de l'API v1.8.

v1.8.1

2025-12-01

Ajout de l'endpoint merchant-kyc-upload. Tables de référence enrichies (docTypes, customerStatuses, accountLevels). Codes d'erreur détaillés avec mapping endpoint. Paramètre autoActivate sur confirm. Correction de la route confirm.

v1.9

2026-04-14

Ajout de la section Simulation (Sandbox). Nouveaux Operation Types : 10=RECHARGE, 25=BILL_PAYMENT ; renommage 5→MOBILE_PAYMENT, 24→CARD_PAYMENT. Transaction Status formalisé : OPEN/COMPLETED/FAILED/CANCELED. Webhooks simplifiés : ajout payment.received, retrait de operation.created/operation.updated/customer.kyc/bank-transfer.failed. Format de référence CashIn/CashOut : numérique (ex : 1122334455).

v2.0

2026-06-04

Passage à la documentation v2.0 (Preliminary Release). Ajout de la section « Gestion des cartes » (bêta) : programmes, demandes (applications), cartes, actions de carte, contrôle d'usage, transactions et énumérations de cartes. La section cartes est préliminaire et sera enrichie avec les endpoints manquants — elle peut contenir des erreurs.

P

Présentation — M-Wallet au Maroc

ما هو M-Wallet؟

Un M-Wallet (portefeuille mobile) est un compte de monnaie électronique réglementé qui permet aux particuliers et aux commerçants d'effectuer des transactions financières en utilisant un numéro de mobile comme identifiant. Il s'inscrit dans le cadre national de Bank Al-Maghrib (BAM) pour l'inclusion financière et les paiements numériques. Chaque wallet est lié à une identité vérifiée (KYC) et stocké sous la licence d'Établissement de Paiement CHARI MONEY, supervisée par Bank Al-Maghrib.

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

Identifiant unique

Le MSISDN (numéro de mobile) de l'utilisateur sert d'identifiant du wallet.

Réseau interopérable

Tous les M-Wallets peuvent échanger de la monnaie entre différents fournisseurs via le switch national.

Niveaux KYC

Les permissions et plafonds du compte dépendent du niveau de vérification de l'utilisateur (CIN, selfie, justificatif de domicile, etc.).

Opérations temps réel

Les virements, cash-in/out, paiements marchands et de factures sont exécutés instantanément avec confirmation.

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

النوع	المالك	Description	العمليات
Consommateur (Particulier)	Particuliers	Wallet personnel lié à un numéro de mobile et une CIN.	Cash-in/out, transferts P2P, paiements marchands, autres services de paiement.
Commerçant	Petit commerce, boutique ou prestataire	Wallet professionnel lié à un compte marchand ou magasin.	Recevoir des paiements, transférer vers une banque, rembourser un client, autres services de paiement.
Agent détaillant	Réseau d'agents agréés / partenaire	Utilisé par les agents de distribution pour faciliter le cash-in/out des utilisateurs.	Alimenter / retirer des wallets clients.
Agent principal	Partenaire / EDP	Wallet dédié aux entreprises avec des plafonds plus élevés et des solutions d'intégration.	Virements en masse, paie, encaissements, et autres opérations.

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

المستوى	متطلبات KYC	حد الرصيد
Niveau 1	Nom + numéro de téléphone valide + numéro de CIN	1 000 MAD
Niveau 2	KYC complet (CIN + selfie ou scan du document)	4 000 MAD
Niveau 3	Pièce d'identité vérifiée (KYC), entretien, dossier client numérique	20 000 MAD
Niveau 4	KYC complet, entretien, dossier client numérique, justificatif de revenus, justificatif de domicile	100 000 MAD
Marchand	KYB complet + immatriculation (IF/RC)	Négocié

G

Glossaire

المصطلح	التعريف
M-Wallet	Compte de monnaie électronique réglementé, lié à un numéro de mobile, permettant transferts, paiements et opérations de caisse.
Wallet	Compte utilisateur du système qui stocke la monnaie électronique, associé à un identifiant unique (MSISDN).
MSISDN	Numéro de téléphone mobile utilisé comme identifiant principal d'un wallet.
KYC (Know Your Customer)	Processus de vérification pour identifier et valider l'identité d'un utilisateur selon les exigences réglementaires.
Niveau KYC	Niveau réglementaire assigné à un wallet en fonction de son état de vérification, définissant les plafonds de transactions et de solde.
Opération	Action métier de haut niveau initiée par un utilisateur ou partenaire (ex. cash-in, transfert, paiement).
Transaction	Mouvement financier (débit, crédit, frais, ajustement) généré dans le cadre d'une opération.
Type d'opération	Catégorie d'action métier (ex. CASHIN, TRANSFER, PAYMENT).
Type de transaction	Type de mouvement financier associé à une opération (ex. débit, crédit, frais).
Statut d'opération	État actuel du cycle de vie d'une opération (ex. OPEN, COMPLETED, FAILED).
Statut de transaction	État de traitement d'une transaction (ex. COMPLETED, FAILED).
Référence	Identifiant unique généré pour une opération en attente (ex. cash-in/out), utilisé pour compléter la transaction via un réseau externe.
Agent / Réseau	Entité tierce autorisée ou canal de distribution utilisé pour exécuter les opérations de cash-in et cash-out.
Clé API	Jeton sécurisé utilisé pour authentifier les requêtes d'un partenaire vers l'API BAAS.
Webhook	Callback HTTP automatisé envoyé par le système pour notifier les partenaires des mises à jour d'opération ou de transaction.

I

Inscription client

Gestion complète du cycle de vie client : vérification de statut, inscription, confirmation OTP, gestion du PIN, consultation du solde et des informations, et désinscription.

GET{host}/api/customers/status

Vérifier le statut (Chari)

Récupère le statut d'inscription actuel d'un client auprès de Chari uniquement.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	Numéro de téléphone du client. Format : +212*********

ملاحظات

•0 : Not exists — Le numéro n'existe pas chez ChariMoney.
•1 : Not confirmed — Le numéro existe chez ChariMoney mais n'est pas encore enrôlé chez Switch (OTP non saisi).
•2 : Confirmed — Le numéro existe et est enregistré auprès de Switch.
•3 : Active — Enregistré auprès de Switch et actif chez ChariMoney (PIN créé).
•4 : Locked temporary — Le numéro est temporairement bloqué (nombre de tentatives dépassé).
•5 : Locked — Le numéro est bloqué.

GET{host}/api/customers/default

Vérifier le wallet par défaut

Vérifie si Chari est le wallet par défaut du client auprès de Switch.

Parameter	Type	In	مطلوب	Description
`phoneNumber`	string	query	مطلوب	Numéro de téléphone du client. Format : +212*********

ملاحظات

•true : Chari est le wallet par défaut du client.
•false : Chari n'est PAS le wallet par défaut du client.

POST{host}/api/customers/register202

Inscription

Lance le processus d'inscription d'un nouveau client. Un OTP sera envoyé par SMS pour confirmation.

Parameter	Type	In	مطلوب	Description
`phoneNumber`	string	body	مطلوب	Numéro de téléphone du client. Format : +212*********
`firstName`	string	body	مطلوب	Prénom. Minimum 2 lettres (caractères latins uniquement).
`lastName`	string	body	مطلوب	Nom de famille. Minimum 2 lettres (caractères latins uniquement).
`cin`	string	body	مطلوب	Numéro de carte d'identité. Minimum 5 caractères.
`walletType`	string	body	مطلوب	"P" : Particulier / "C" : Commerçant
`closeLoopOnly`	boolean	body	اختياري	Si true, inscrit le client uniquement en mode CloseLoop. Dans ce cas, un OTP est envoyé directement par CHARI.

POST{host}/api/customers/confirm200

Confirmation OTP

Confirme l'inscription d'un client en saisissant le code OTP reçu par SMS.

Parameter	Type	In	مطلوب	Description
`phoneNumber`	string	body	مطلوب	Numéro de téléphone du client. Format : +212*********
`code`	string	body	مطلوب	Code OTP reçu par SMS. Format : xxx-xxx
`walletType`	string	body	مطلوب	2 types acceptés : "P" : Particulier, "C" : Commerçant (Merchant).
`autoActivate`	boolean	body	اختياري	Valeur par défaut : false. Indique si le wallet doit être activé automatiquement après la validation de l'OTP. Si false, l'utilisateur doit terminer l'activation en définissant ou saisissant un PIN. Si true, le wallet est activé automatiquement, sans PIN.

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

Renvoyer l'OTP

Renvoie le code OTP pour l'inscription ou la confirmation.

Parameter	Type	In	مطلوب	Description
`phoneNumber`	string	query	مطلوب	Numéro de téléphone du client. Format : +212*********

POST{host}/api/customers/login

Connexion par PIN

Authentifie un client existant avec son code PIN.

Parameter	Type	In	مطلوب	Description
`phoneNumber`	string	body	مطلوب	Numéro de téléphone du client. Format : +212*********
`pin`	string	body	مطلوب	Code PIN du client.

ملاحظات

•logged : true si l'authentification a réussi, false sinon.
•remainingAttempts : nombre de tentatives restantes avant le verrouillage du compte.

POST{host}/api/customers/pin

Créer un PIN

Définit un code PIN sécurisé pour un client inscrit et confirmé.

Parameter	Type	In	مطلوب	Description
`phoneNumber`	string	body	مطلوب	Numéro de téléphone du client. Format : +212*********
`pin`	string	body	مطلوب	Code PIN du client (4 chiffres obligatoires).

PATCH{host}/api/customers/pin

Modifier le PIN

Modifie le code PIN existant d'un client.

Parameter	Type	In	مطلوب	Description
`phoneNumber`	string	body	مطلوب	Numéro de téléphone du client. Format : +212*********
`oldPin`	string	body	مطلوب	PIN actuel du client.
`newPin`	string	body	مطلوب	Nouveau PIN du client.

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

Réinitialiser le PIN

Réinitialise le code PIN d'un client. Disponible dans une prochaine version.

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

GET{host}/api/customers/balance

Consulter le solde

Récupère le solde actuel du wallet d'un client inscrit.

Parameter	Type	In	مطلوب	Description
`phoneNumber`	string	query	مطلوب	Numéro de téléphone du client. Format : +212*********

GET{host}/api/customers/info

Informations client

Récupère les données de profil détaillées d'un client inscrit (identité, solde, RIB, niveau de compte, partenaire).

Parameter	Type	In	مطلوب	Description
`phoneNumber`	string	query	مطلوب	Numéro de téléphone du client. Format : +212*********

ملاحظات

•accountLevel : niveau de compte (1 = basique, 2-4 = niveaux KYC supérieurs).
•customerStatus : statut du client (voir l'endpoint "Check Status with Chari").
•rib : Relevé d'Identité Bancaire associé au wallet.

PUT{host}/api/customers/unregister

Désinscription

Désactive ou supprime un client de la plateforme. Une raison de clôture doit être fournie.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	body	مطلوب	Numéro de téléphone du client. Format : +212*********
`Reason`	int	body	مطلوب	Code de la raison de clôture (voir notes).

ملاحظات

•1 : Clôture à l'initiative de l'EDP — Raison non spécifiée
•2 : Clôture à l'initiative de l'EDP — Suspicion de fraude
•3 : Clôture à l'initiative du client — Résiliation du contrat
•4 : Clôture à l'initiative du client — Téléphone perdu ou volé
•5 : Clôture à l'initiative du client — Raison non spécifiée

K

KYC (Vérification d'identité)

Flux KYC mobile (iOS/Android) propulsé par ShareID. Votre application lance le SDK ShareID pour le scan de document et la capture de selfie ; ShareID effectue les contrôles de qualité, d'authenticité et de correspondance visage/document. Sur demande, nous vous fournissons les SDK ShareID (Android/iOS) et les credentials d'installation.

مسار التكامل

1Votre app appelle "/kyc/shareid/auth" pour obtenir un token KYC temporaire.
2L'app ouvre le SDK ShareID avec ce token.
3L'utilisateur scanne sa pièce d'identité et effectue un selfie guidé.
4ShareID exécute les vérifications.
5Votre app appelle "/kyc/session/complete" pour signaler la fin du flux côté appareil.
6Un callback est envoyé à notre API avec le statut et les documents — nous stockons/validons et exposons le résultat KYC final.

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

Authentification KYC

Obtient un token KYC temporaire pour lancer le SDK ShareID.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	Numéro de téléphone du client. Format : +212*********

ملاحظات

•baseUrl : URL de base du SDK ShareID à utiliser.
•applicant_id : identifiant unique de la demande KYC.
•token : jeton JWT temporaire pour l'authentification côté SDK.

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

Confirmation KYC

Signale la fin du flux KYC côté appareil et demande la mise à niveau du compte.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	Numéro de téléphone du client. Format : +212*********
`AccountLevel`	int	query	مطلوب	Niveau de compte cible (2, 3 ou 4).

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

Upload documents marchand

Téléverse les documents KYC d'un commerçant pour demander une mise à niveau de compte (multipart/form-data).

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	Numéro de téléphone du commerçant. Format : +212*********
`KycDocuments`	multipart form	body	مطلوب	Tableau d'objets document KYC. Plusieurs documents peuvent être envoyés dans la même requête en répétant les champs indexés (ex. kycDocuments[0], kycDocuments[1], ...).
`KycDocuments[n].DocType`	int	body	مطلوب	Type de document (voir la table "Types de documents").
`KycDocuments[n].DocFront`	file	body	مطلوب	Image recto du document. Formats acceptés : PNG, JPG/JPEG, PDF.
`KycDocuments[n].DocBack`	file	body	اختياري	Image verso (requis pour IdentityCard, DrivingLicense, ResidencePermit).

O

Opérations

Toutes les opérations financières : dépôts par carte, transferts wallet-à-wallet, virements bancaires, paiements marchand, chargebacks, remboursements et requêtes par référence.

Dépôt par carte (CashIn Card)

Carte de test

Numéros de carte valides pour ajouter des fonds en environnement sandbox.

PAN

4918914107195005

CVV

123

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

08/26 (ou toute date future)

رمز 3D Secure

555

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

Aperçu (par téléphone)

Vérifie la faisabilité du dépôt de fonds sur le wallet d'un client depuis une carte bancaire.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	Numéro de téléphone du client. Format : +212*********
`Amount`	decimal	body	مطلوب	Montant à déposer. Doit être un nombre positif.

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

Exécuter (par téléphone)

Dépose des fonds sur le wallet d'un client depuis une carte bancaire. Déclenche une authentification 3D Secure.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	Numéro de téléphone du client.
`FirstName`	string	body	مطلوب	Prénom du titulaire de la carte.
`LastName`	string	body	مطلوب	Nom du titulaire de la carte.
`Cvv`	string	body	مطلوب	Code de sécurité à 3 chiffres (CVV).
`Amount`	decimal	body	مطلوب	Montant à déposer.
`Currency`	string	body	اختياري	Code devise ISO 3 lettres (ex : MAD).
`Pan`	string	body	مطلوب	Numéro complet de la carte (PAN).
`ExpiryDate`	string	body	مطلوب	Date d'expiration au format YYMM.
`KeepAlive`	bool	body	مطلوب	true : sauvegarder la carte pour usage futur / false : usage unique.
`CardName`	string	body	اختياري	Nom choisi par l'utilisateur pour sauvegarder la carte.

ملاحظات

•Après l'authentification 3D Secure, l'utilisateur est redirigé vers acceptURL ou declineURL.
•RESPONSE_CODE dans l'URL de redirection : 0 = succès, toute autre valeur = échec.
•REASON_CODE : raison lisible du résultat (ex : SUCCESS, DECLINED).
•Validez RESPONSE_CODE et REASON_CODE pour déterminer la suite dans votre application.

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

Exécuter avec carte sauvegardée

Dépose des fonds depuis une carte déjà tokenisée et sauvegardée.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	Numéro de téléphone du client.
`CardId`	int	route	مطلوب	Identifiant de la carte sauvegardée.
`Cvv`	string	body	مطلوب	Code de sécurité à 3 chiffres.
`Amount`	decimal	body	مطلوب	Montant à déposer.

ملاحظات

•Après l'authentification 3D Secure, l'utilisateur est redirigé vers acceptURL ou declineURL selon le résultat.
•L'URL de redirection inclut des paramètres : RESPONSE_CODE (0 = succès, autre = échec), REASON_CODE (raison lisible : SUCCESS, DECLINED…) et OPERATION (type d'opération, ex : PAYMENT).
•Validez RESPONSE_CODE et REASON_CODE à la réception du retour pour déterminer la suite dans votre application.

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

Aperçu (par agent)

Vérifie la faisabilité du dépôt via un code agent.

Parameter	Type	In	مطلوب	Description
`code`	string	query	مطلوب	Code de l'agent.
`Amount`	decimal	body	مطلوب	Montant à déposer.

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

Exécuter (par agent)

Dépose des fonds sur le wallet d'un client via un agent.

Parameter	Type	In	مطلوب	Description
`agent`	string	query	مطلوب	Code de l'agent.
`FirstName`	string	body	مطلوب	Prénom du titulaire de la carte.
`LastName`	string	body	مطلوب	Nom du titulaire de la carte.
`Cvv`	string	body	مطلوب	Code de sécurité à 3 chiffres.
`Amount`	decimal	body	مطلوب	Montant à déposer.
`Pan`	string	body	مطلوب	Numéro complet de la carte.
`ExpiryDate`	string	body	مطلوب	Date d'expiration au format YYMM.
`KeepAlive`	bool	body	مطلوب	Sauvegarder la carte pour usage futur.
`Currency`	string	body	اختياري	Code devise ISO 3 lettres (ex : MAD).
`CardName`	string	body	اختياري	Nom choisi par l'utilisateur pour sauvegarder la carte.

ملاحظات

•Après l'authentification 3D Secure, l'utilisateur est redirigé vers acceptURL ou declineURL selon le résultat.
•L'URL de redirection inclut des paramètres : RESPONSE_CODE (0 = succès, autre = échec), REASON_CODE (raison lisible : SUCCESS, DECLINED…) et OPERATION (type d'opération, ex : PAYMENT).
•Validez RESPONSE_CODE et REASON_CODE à la réception du retour pour déterminer la suite dans votre application.

Transfert wallet-à-wallet

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

Aperçu

Vérifie la faisabilité d'un transfert de fonds entre wallets.

Parameter	Type	In	مطلوب	Description
`CustomerPhoneNumber`	string	body	مطلوب	Numéro de l'émetteur. Format : +212*********
`Amount`	decimal	body	مطلوب	Montant à transférer.
`Reason`	string	body	مطلوب	Motif du transfert.
`RecipientPhoneNumber`	string	body	مطلوب	Numéro du bénéficiaire. Format : +212*********
`BeneficiaryId`	int	body	اختياري	Référence à un bénéficiaire existant (optionnel).

POST{host}/api/operations/transfer

Exécuter

Exécute un transfert de fonds entre wallets.

Parameter	Type	In	مطلوب	Description
`CustomerPhoneNumber`	string	body	مطلوب	Numéro de l'émetteur.
`Amount`	decimal	body	مطلوب	Montant à transférer.
`Reason`	string	body	مطلوب	Motif du transfert.
`RecipientPhoneNumber`	string	body	مطلوب	Numéro du bénéficiaire.
`BeneficiaryId`	int	body	اختياري	Référence à un bénéficiaire existant (optionnel).

Virement bancaire

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

Aperçu

Vérifie la faisabilité d'un virement vers un compte bancaire externe.

Parameter	Type	In	مطلوب	Description
`CustomerPhoneNumber`	string	body	اختياري	Requis si AgentCode est vide. Exclusif avec AgentCode (l'un OU l'autre).
`AgentCode`	string	body	اختياري	Requis si CustomerPhoneNumber est vide. Code Agent (Principal ou Retail). Exclusif avec CustomerPhoneNumber.
`Amount`	decimal	body	مطلوب	Montant à virer.
`Reason`	string	body	مطلوب	Motif du virement (caractères latins uniquement, 35 caractères max).
`BeneficiaryId`	int	body	اختياري	Optionnel si rib + beneficiaryName sont fournis.
`BeneficiaryName`	string	body	اختياري	Optionnel si beneficiaryId est fourni.
`Rib`	string	body	اختياري	RIB : chaîne numérique de 24 chiffres. Optionnel si beneficiaryId est fourni.

ملاحظات

•Au moins un identifiant parmi beneficiaryId ou (rib + beneficiaryName) doit être fourni.

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

Exécuter

Envoie de l'argent d'un wallet vers un compte bancaire externe.

Parameter	Type	In	مطلوب	Description
`CustomerPhoneNumber`	string	body	اختياري	Requis si AgentCode est vide. Exclusif avec AgentCode (l'un OU l'autre).
`AgentCode`	string	body	اختياري	Requis si CustomerPhoneNumber est vide. Exclusif avec CustomerPhoneNumber.
`Amount`	decimal	body	مطلوب	Montant à virer.
`Reason`	string	body	اختياري	Motif du virement (optionnel à l'exécution).
`BeneficiaryId`	int	body	اختياري	Optionnel si rib + beneficiaryName sont fournis.
`BeneficiaryName`	string	body	اختياري	Optionnel si beneficiaryId est fourni.
`Rib`	string	body	اختياري	RIB : 24 chiffres. Requis si pas de beneficiaryId.

Paiement marchand

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

Par téléphone — Aperçu

Vérifie la faisabilité d'un paiement marchand par numéro de téléphone.

Parameter	Type	In	مطلوب	Description
`CustomerPhoneNumber`	string	body	مطلوب	Numéro du client payeur.
`Amount`	decimal	body	مطلوب	Montant du paiement.
`Reason`	string	body	مطلوب	Motif du paiement.
`RecipientPhoneNumber`	string	body	مطلوب	Numéro du marchand.
`BeneficiaryId`	int	body	اختياري	Référence à un bénéficiaire existant (optionnel).

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

Par téléphone — Exécuter

Effectue un paiement marchand par numéro de téléphone.

Parameter	Type	In	مطلوب	Description
`CustomerPhoneNumber`	string	body	مطلوب	Numéro du client payeur.
`Amount`	decimal	body	مطلوب	Montant du paiement.
`Reason`	string	body	مطلوب	Motif du paiement.
`RecipientPhoneNumber`	string	body	مطلوب	Numéro du marchand.
`BeneficiaryId`	int	body	اختياري	Référence à un bénéficiaire existant (optionnel).

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

Par QR Code — Aperçu

Vérifie la faisabilité d'un paiement marchand par QR Code.

Parameter	Type	In	مطلوب	Description
`CustomerPhoneNumber`	string	body	مطلوب	Numéro du client payeur.
`QrCodeContent`	string	body	مطلوب	Contenu du QR Code scanné.
`Amount`	decimal	body	مطلوب	Montant du paiement.

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

Par QR Code — Exécuter

Effectue un paiement marchand par QR Code.

Parameter	Type	In	مطلوب	Description
`CustomerPhoneNumber`	string	body	مطلوب	Numéro du client payeur.
`QrCodeContent`	string	body	مطلوب	Contenu du QR Code.
`Amount`	decimal	body	مطلوب	Montant du paiement.

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

Par carte — Aperçu

Vérifie la faisabilité d'un paiement marchand par carte (Card to Wallet).

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	Numéro du marchand.
`Amount`	decimal	body	مطلوب	Montant du paiement.

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

Par carte — Exécuter

Effectue un paiement marchand par carte (Card to Wallet). Flux 3DS : la réponse fournit `redirectionURL` à ouvrir.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	Numéro du marchand. Format : +212*********
`FirstName`	string	body	مطلوب	Prénom du titulaire.
`LastName`	string	body	مطلوب	Nom du titulaire.
`Cvv`	string	body	مطلوب	CVV (3 chiffres).
`Amount`	decimal	body	مطلوب	Montant du paiement.
`Pan`	string	body	مطلوب	Numéro de carte (PAN).
`ExpiryDate`	string	body	مطلوب	Date d'expiration au format `YYMM`. Ex : `2608`.
`KeepAlive`	bool	body	مطلوب	Tokenizer la carte pour réutilisation via l'endpoint Tokenized Card.
`Currency`	string	body	اختياري	Devise. Par défaut : MAD.
`3dSecure`	bool	body	اختياري	Activer 3D Secure. Par défaut : true.
`FeesPercent`	decimal	body	اختياري	Pourcentage de frais appliqués au payeur.
`AllowInternationalCards`	bool	body	اختياري	Accepter les cartes internationales.
`InternationalFeesPercent`	decimal	body	اختياري	Frais % spécifiques aux cartes internationales.
`AutoCapture`	bool	body	اختياري	Capture automatique du paiement.
`NotificationUrl`	string	body	اختياري	URL notifiée après fin de transaction (succès/échec).
`AcceptUrl`	string	body	اختياري	URL de redirection en cas de succès 3DS.
`CardName`	string	body	اختياري	Libellé de la carte (pour tokenisation).
`ExternalReference`	string	body	اختياري	Référence externe du marchand.

ملاحظات

•Après l'authentification 3D Secure, l'utilisateur est redirigé vers acceptURL ou declineURL selon le résultat.
•L'URL de redirection inclut des paramètres : RESPONSE_CODE (0 = succès, autre = échec), REASON_CODE (raison lisible : SUCCESS, DECLINED…) et OPERATION (type d'opération, ex : PAYMENT).
•Validez RESPONSE_CODE et REASON_CODE à la réception du retour pour déterminer la suite dans votre application.

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

Par carte tokenisée — Exécuter

Effectue un paiement marchand via une carte précédemment tokenisée (`KeepAlive = true`). Seul le CVV est requis.

Parameter	Type	In	مطلوب	Description
`cardId`	int	path	مطلوب	ID de la carte tokenisée.
`PhoneNumber`	string	query	مطلوب	Numéro du marchand. Format : +212*********
`Cvv`	string	body	مطلوب	CVV (3 chiffres).
`Amount`	decimal	body	مطلوب	Montant du paiement.

ملاحظات

•Même structure de réponse que « Paiement marchand par carte — Exécuter ».
•Après l'authentification 3D Secure, l'utilisateur est redirigé vers acceptURL ou declineURL selon le résultat.
•L'URL de redirection inclut des paramètres : RESPONSE_CODE (0 = succès, autre = échec), REASON_CODE (raison lisible) et OPERATION.

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

Génération QR statique

Génère un QR Code statique (sans montant pré-intégré) pour un marchand. Le client saisit le montant lors du paiement.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	Numéro du marchand.
`MaskedNumber`	bool	query	اختياري	Masquer le numéro du marchand dans le contenu QR. Ex : +2126######74

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

Génération QR dynamique

Génère un QR Code dynamique avec un montant fixe intégré, associé à une référence unique.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	Numéro du marchand.
`MaskedNumber`	bool	query	اختياري	Masquer le numéro du marchand.
`Amount`	decimal	body	مطلوب	Montant fixe du QR Code.

ملاحظات

•QR statique (GET) : aucun montant intégré, le client saisit le montant au paiement.
•QR dynamique (POST) : montant fixe intégré, référence unique `qrCodeReference`.

Chargeback (Rétrofacturation)

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

Aperçu

Vérifie la faisabilité d'un chargeback.

Parameter	Type	In	مطلوب	Description
`SourcePhoneNumber`	string	body	مطلوب	Numéro du client à l'origine. Format : +212*********
`Amount`	decimal	body	مطلوب	Montant du chargeback.
`Description`	string	body	مطلوب	Motif du chargeback.
`DestinationPhoneNumber`	string	body	مطلوب	Numéro du destinataire. Format : +212*********
`OriginalOperationId`	int	body	مطلوب	ID de l'opération d'origine qui a déclenché le chargeback.

POST{host}/api/operations/chargeback

Exécuter

Exécute un chargeback.

Parameter	Type	In	مطلوب	Description
`SourcePhoneNumber`	string	body	مطلوب	Numéro du client à l'origine.
`Amount`	decimal	body	مطلوب	Montant du chargeback.
`Description`	string	body	مطلوب	Motif du chargeback.
`DestinationPhoneNumber`	string	body	مطلوب	Numéro du destinataire.
`OriginalOperationId`	int	body	مطلوب	ID de l'opération d'origine.

Opérations par référence (Request)

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

Demander un CashIn

Crée une demande de CashIn. Génère une référence unique avec une durée de validité limitée.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	body	مطلوب	Numéro de téléphone du client.
`Amount`	decimal	body	مطلوب	Montant du CashIn.

ملاحظات

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

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

Demander un CashOut

Crée une demande de CashOut. Génère une référence unique avec une durée de validité limitée.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	body	مطلوب	Numéro de téléphone du client.
`Amount`	decimal	body	مطلوب	Montant du CashOut.

Consulter les opérations

GET{host}/api/operations

Par client

Récupère la liste des opérations d'un client avec filtres optionnels.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	Numéro de téléphone du client.
`PageSize`	int	query	اختياري	Résultats par page. Par défaut : 10
`PageNumber`	int	query	اختياري	Numéro de page. Par défaut : 1
`OperationType`	list int	query	اختياري	1=CASHIN, 2=CASHOUT, 3=TRANSFER, 5=MOBILE_PAYMENT, 7=PAYMENT_REFUND, 9=BANK_TRANSFER, 10=RECHARGE, 12=CHARGEBACK, 24=CARD_PAYMENT, 25=BILL_PAYMENT
`TransactionStatus`	int	query	اختياري	1=OPEN, 2=COMPLETED, 3=FAILED, 4=CANCELED
`Sens`	int	query	اختياري	1=CREDIT, 2=DEBIT
`From`	datetime	query	اختياري	Date/heure de début du filtre.
`To`	datetime	query	اختياري	Date/heure de fin du filtre.

ملاحظات

•collection : liste paginée des opérations.
•count : nombre total d'opérations correspondant aux filtres.
•accountNumber : peut être un numéro de téléphone, un RIB ou un accountId.

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

Par ID

Récupère le détail d'une opération spécifique par son ID.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	Numéro de téléphone du client.
`Id`	int	route	مطلوب	ID de l'opération.

ملاحظات

•operationId : identifiant de l'opération globale.
•transactionId : identifiant de la transaction principale (une opération peut générer plusieurs transactions : débit émetteur, crédit destinataire, frais, etc.).
•transactionReference : référence de la transaction principale.
•amount : montant initial.
•totalAmount : montant après application des frais et commissions.

GET{host}/api/operations/all

Toutes (par partenaire)

Récupère la liste de toutes les opérations du partenaire.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	Numéro de téléphone du client. Format : +212*********
`PageSize`	int	query	اختياري	Résultats par page. Par défaut : 10
`PageNumber`	int	query	اختياري	Numéro de page (commence à 1). Par défaut : 1
`OperationType`	list int	query	اختياري	Filtrer par type d'opération.
`TransactionStatus`	int	query	اختياري	Filtrer par statut de transaction.
`Sens`	int	query	اختياري	1 = CREDIT, 2 = DEBIT
`From`	datetime	query	اختياري	Date/heure de début.
`To`	datetime	query	اختياري	Date/heure de fin.

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

Par C-Request-Id

Récupère une opération par son identifiant C-Request-Id. Disponible dans une prochaine version.

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

Remboursement

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

Aperçu

Vérifie la faisabilité d'un remboursement après paiement marchand.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	body	مطلوب	Numéro du client à rembourser.
`OperationId`	int	body	مطلوب	ID de l'opération à rembourser.
`RefundAmount`	decimal	body	مطلوب	Montant du remboursement.
`OrderId`	string	body	مطلوب	OrderId original du paymentGateway.
`TransactionTrackId`	string	body	مطلوب	TransactionTrackId original du paymentGateway.

POST{host}/api/operations/refund

Exécuter

Exécute le remboursement d'un client après paiement marchand.

Parameter	Type	In	مطلوب	Description
`phoneNumber`	string	body	مطلوب	Numéro du client.
`OperationId`	int	body	مطلوب	ID de l'opération à rembourser.
`RefundAmount`	decimal	body	مطلوب	Montant du remboursement.
`OrderId`	string	body	مطلوب	OrderId original.
`TransactionTrackId`	string	body	مطلوب	TransactionTrackId original.

B

Bénéficiaires

Gérez les bénéficiaires d'un client : consultation, ajout, modification et suppression. Les bénéficiaires peuvent être identifiés par numéro de téléphone et/ou RIB.

GET{host}/api/customer/beneficiaries

Liste des bénéficiaires

Récupère la liste paginée des bénéficiaires d'un client.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	Numéro de téléphone du client.
`PageSize`	int	query	اختياري	Résultats par page. Par défaut : 10
`PageNumber`	int	query	اختياري	Numéro de page. Par défaut : 1
`Search`	string	query	اختياري	Filtrer par mot-clé.
`From`	datetime	query	اختياري	Date de création — début.
`To`	datetime	query	اختياري	Date de création — fin.

POST{host}/api/customer/beneficiaries

Ajouter un bénéficiaire

Ajoute un nouveau bénéficiaire. Au moins le PhoneNumber ou le RIB doit être fourni.

Parameter	Type	In	مطلوب	Description
`PhoneNumber (query)`	string	query	مطلوب	Numéro de téléphone du client (propriétaire).
`Name`	string	body	مطلوب	Nom du bénéficiaire. Minimum 2 lettres.
`PhoneNumber`	string	body	اختياري	Numéro du bénéficiaire. Format : +212*********
`Rib`	string	body	اختياري	RIB du bénéficiaire. 24 chiffres.
`Email`	string	body	اختياري	Email du bénéficiaire.

ملاحظات

•PhoneNumber ou RIB : au moins l'un des deux doit être fourni.

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

Modifier un bénéficiaire

Met à jour un bénéficiaire existant.

Parameter	Type	In	مطلوب	Description
`PhoneNumber (query)`	string	query	مطلوب	Numéro de téléphone du client (propriétaire).
`Id`	int	route	مطلوب	ID du bénéficiaire à modifier.
`Name`	string	body	مطلوب	Nom du bénéficiaire. Minimum 2 lettres.
`PhoneNumber (body)`	string	body	اختياري	Numéro de téléphone du bénéficiaire.
`Rib`	string	body	اختياري	RIB du bénéficiaire. 24 chiffres.
`Email`	string	body	اختياري	Email du bénéficiaire.

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

Supprimer un bénéficiaire

Supprime un bénéficiaire existant.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	Numéro de téléphone du client.
`Id`	int	route	مطلوب	ID du bénéficiaire à supprimer.

C

Cartes tokenisées

Consultez et gérez les cartes bancaires sauvegardées (tokenisées) d'un client.

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

Liste des cartes

Récupère toutes les cartes tokenisées d'un client.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	Numéro de téléphone du client.
`PageSize`	int	query	اختياري	Résultats par page. Par défaut : 10
`PageNumber`	int	query	اختياري	Numéro de page. Par défaut : 1

ملاحظات

•customerBankCardId : identifiant unique de la carte sauvegardée.
•maskedPan : numéro de carte masqué (4 derniers chiffres).
•issuer : nom de la banque émettrice.
•scheme : réseau de la carte (Visa, Mastercard, etc.).
•cardName : libellé optionnel choisi par le client au moment de la tokenisation.

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

Carte par ID

Récupère les détails d'une carte tokenisée spécifique.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	Numéro de téléphone du client.
`Id`	int	route	مطلوب	ID de la carte.

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

Supprimer une carte

Supprime une carte tokenisée. Disponible dans une prochaine version.

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

A

Agents détaillants

Gérez les agents détaillants : consultation, ajout, et exécution d'opérations CashIn/CashOut par référence.

GET{host}/api/agents/retail

Liste des agents détaillants

Récupère la liste paginée des agents détaillants.

Parameter	Type	In	مطلوب	Description
`Code`	string	query	مطلوب	Code de l'agent.
`PageSize`	int	query	اختياري	Résultats par page. Par défaut : 10
`PageNumber`	int	query	اختياري	Numéro de page. Par défaut : 1
`From`	datetime	query	اختياري	Création de l'agent — date début.
`To`	datetime	query	اختياري	Création de l'agent — date fin.

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

Agent par code

Récupère les détails d'un agent détaillant par son code.

Parameter	Type	In	مطلوب	Description
`Code`	string	route	مطلوب	Code de l'agent.

POST{host}/api/agents/retail

Ajouter un agent

Ajoute un nouvel agent détaillant.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	body	مطلوب	Numéro de téléphone de l'agent. Format : +212*********
`Name`	string	body	مطلوب	Nom commercial de l'agent.
`FirstName`	string	body	مطلوب	Prénom. Minimum 2 lettres.
`LastName`	string	body	مطلوب	Nom de famille. Minimum 2 lettres.
`Cin`	string	body	مطلوب	Numéro de pièce d'identité.
`Address`	string	body	اختياري	Adresse de l'agent.
`Email`	string	body	اختياري	Email de l'agent.

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

Modifier un agent

Met à jour un agent détaillant existant. Disponible dans une prochaine version.

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

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

Consulter CashIn par référence

Récupère les détails d'une opération CashIn demandée via sa référence unique.

Parameter	Type	In	مطلوب	Description
`Reference`	string	query	مطلوب	Référence unique de l'opération.

ملاحظات

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

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

Exécuter CashIn par référence

L'agent exécute une opération CashIn en utilisant la référence générée par le client.

Parameter	Type	In	مطلوب	Description
`Code`	string	body	مطلوب	Code de l'agent effectuant l'opération.
`Reference`	string	body	مطلوب	Référence unique de l'opération à exécuter.

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

Consulter CashOut par référence

Récupère les détails d'une opération CashOut via sa référence unique.

Parameter	Type	In	مطلوب	Description
`Reference`	string	query	مطلوب	Référence unique de l'opération.

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

Exécuter CashOut par référence

L'agent exécute une opération CashOut en utilisant la référence générée par le client.

Parameter	Type	In	مطلوب	Description
`Code`	string	body	مطلوب	Code de l'agent effectuant l'opération.
`Reference`	string	body	مطلوب	Référence unique de l'opération à exécuter.

A

Agents principaux

Consultez les informations d'un agent principal.

GET{host}/api/agents/principal

Agent principal par code

Récupère les informations de compte d'un agent principal.

Parameter	Type	In	مطلوب	Description
`Code`	string	query	مطلوب	Code de l'agent principal.

ملاحظات

•Réponse : objet Agent + objet Account (solde, RIB, niveau, etc.).

G

Gestion des cartes

Émission et gestion de cartes : programmes de cartes, demandes (applications), cartes, contrôle d'usage et transactions.

⚠️ Section en bêta. La documentation des cartes bancaires est encore préliminaire : des endpoints manquants seront ajoutés et elle peut contenir des erreurs. En cas de problème, contactez Hedi ZaZ (VP of BaaS) sur WhatsApp : wa.me/212600000010

GET{host}/api/cards/programs

Lister les programmes

Récupère la liste des programmes de cartes disponibles pour le partenaire.

Parameter	Type	In	مطلوب	Description
`PageSize`	int	query	اختياري	Nombre de résultats par page. Valeur par défaut = 10.
`PageNumber`	int	query	اختياري	Page de résultats à récupérer. Commence à 1. Valeur par défaut = 1.

ملاحظات

•collection : liste des programmes.
•count : nombre de programmes.

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

Récupérer un programme par Id

Sera livré dans la prochaine version.

Parameter	Type	In	مطلوب	Description
`Id`	int	route	مطلوب	Identifiant du programme de carte.

POST{host}/api/cards/applications

Créer une demande

Crée une nouvelle demande de carte.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	Numéro de téléphone du client. Format : +212*********
`cardProgramId`	int	query	مطلوب	Identifiant du programme de carte.

ملاحظات

•Aucun corps de requête pour le moment.

GET{host}/api/cards/applications

Lister les demandes

Récupère une liste de demandes selon des filtres.

Parameter	Type	In	مطلوب	Description
`PageSize`	int	query	اختياري	Nombre de résultats par page. Valeur par défaut = 10.
`PageNumber`	int	query	اختياري	Page de résultats à récupérer. Commence à 1. Valeur par défaut = 1.
`Status`	int	query	اختياري	Filtre par statut : 1=Pending, 2=Validated, 3=Rejected.

ملاحظات

•collection : liste des demandes.
•count : nombre de demandes.
•CardApplicationStatus — 1 : PENDING, 2 : VALIDATED, 3 : REJECTED.

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

Demandes par client

Récupère une liste de demandes pour un client.

Parameter	Type	In	مطلوب	Description
`PageSize`	int	query	اختياري	Nombre de résultats par page. Valeur par défaut = 10.
`PageNumber`	int	query	اختياري	Page de résultats à récupérer. Commence à 1. Valeur par défaut = 1.

ملاحظات

•collection : liste des demandes.
•count : nombre de demandes.

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

Valider une demande

Valide une demande de carte en cours.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	Numéro de téléphone du client. Format : +212*********
`Id`	int	route	مطلوب	Id de la demande à valider.

ملاحظات

•Aucun corps de requête pour le moment.

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

Rejeter une demande

Rejette une demande de carte en cours.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	Numéro de téléphone du client. Format : +212*********
`Id`	int	route	مطلوب	Id de la demande à rejeter.

ملاحظات

•Aucun corps de requête pour le moment.

GET{host}/api/cards

Lister les cartes

Récupère la liste des cartes du partenaire.

Parameter	Type	In	مطلوب	Description
`PageSize`	int	query	اختياري	Nombre de résultats par page. Valeur par défaut = 10.
`PageNumber`	int	query	اختياري	Page de résultats à récupérer. Commence à 1. Valeur par défaut = 1.
`PhoneNumber`	string	query	اختياري	Numéro de téléphone du client. Format : +212*********
`CardProgramId`	int	query	اختياري	Identifiant du programme de carte.
`DeliveryStatusId`	int	query	اختياري	Statut de livraison (voir énumérations cartes).
`CardStatusId`	int	query	اختياري	Statut de carte (voir énumérations cartes).

ملاحظات

•collection : liste des cartes.
•count : nombre de cartes.
•CardType — 1 : PHYSICAL, 2 : VIRTUAL, 3 : DIGITAL.
•DeliveryStatus — 1 : PENDING, 2 : SENT_TO_PERSONALIZATION, 3 : READY_FOR_DELIVERY, 4 : DELIVERED.
•CardStatus — 1 : ISSUED, 2 : ACTIVATED, 3 : BLOCKED, 4 : SUSPENDED, 5 : EXPIRED, 6 : CANCELLED.

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

Récupérer une carte par Id

Récupère une carte spécifique par son Id.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	Numéro de téléphone du client. Format : +212*********
`Id`	int	route	مطلوب	Id de la carte.

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

Actions sur une carte

Exécute des actions sur une carte existante (activation, blocage, suspension, etc.).

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	Numéro de téléphone du client. Format : +212*********
`Id`	int	route	مطلوب	Id de la carte à mettre à jour.

ملاحظات

•Actions disponibles ({action}) :
•/activate — Activer la carte et la rendre prête à l'emploi.
•/block — Bloquer temporairement la carte (aucune transaction).
•/suspend — Suspendre l'usage de la carte jusqu'à nouvel ordre.
•/reactivate — Réactiver une carte précédemment suspendue.
•/cancel — Annuler et désactiver définitivement la carte.
•/unblock-pin — Débloquer le PIN après des tentatives échouées.
•/reset-pin — Réinitialiser et générer un nouveau PIN.
•Réponse : true / false.

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

Contrôle d'usage de la carte

Met à jour les services de la carte pour le contrôle d'usage.

Parameter	Type	In	مطلوب	Description
`PhoneNumber`	string	query	مطلوب	Numéro de téléphone du client. Format : +212*********
`Id`	int	route	مطلوب	Id de la carte à mettre à jour.
`allowAtm`	bool	body	مطلوب	Activer ou désactiver les retraits au GAB.
`allowOnline`	bool	body	مطلوب	Activer ou désactiver les transactions en ligne / e-commerce.
`allowPos`	bool	body	مطلوب	Activer ou désactiver les paiements TPE (point de vente).
`contactlessEnabled`	bool	body	مطلوب	Activer ou désactiver les paiements sans contact.

ملاحظات

•Réponse : true / false.

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

Transactions d'une carte

Récupère les transactions d'une carte.

Parameter	Type	In	مطلوب	Description
`PageSize`	int	query	اختياري	Nombre de résultats par page. Valeur par défaut = 10.
`PageNumber`	int	query	اختياري	Page de résultats à récupérer. Commence à 1. Valeur par défaut = 1.
`PhoneNumber`	string	query	اختياري	Numéro de téléphone du client. Format : +212*********
`From`	datetime	query	اختياري	Filtrer à partir de cette date.
`To`	datetime	query	اختياري	Filtrer jusqu'à cette date.
`Id`	int	route	مطلوب	Id de la carte.

ملاحظات

•collection : liste des transactions.
•count : nombre de transactions.

S

Simulation (Sandbox)

Endpoints de simulation disponibles uniquement en sandbox pour finaliser les opérations CashIn/CashOut par référence sans interaction avec un réseau d'agents réel. Associez-les à la carte de test ci-dessous pour dérouler un parcours bout-en-bout.

Carte de test

Utilisez ces données de carte pour tester les dépôts par carte en environnement sandbox.

PAN

4918914107195005

CVV

123

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

08/26 (ou toute date future)

رمز 3D Secure

555

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

Simuler un CashIn réseau

Simule l'exécution d'un CashIn par référence (étape agent réseau). Déclenche le webhook `cashin.network.executed`.

Parameter	Type	In	مطلوب	Description
`reference`	string	body	مطلوب	Référence numérique retournée lors de la création de la requête CashIn.

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

Simuler un CashOut réseau

Simule l'exécution d'un CashOut par référence (étape agent réseau). Déclenche le webhook `cashout.network.executed`.

Parameter	Type	In	مطلوب	Description
`reference`	string	body	مطلوب	Référence numérique retournée lors de la création de la requête CashOut.

W

Webhooks

Les webhooks permettent au BAAS Chari de notifier votre système des événements (opération complétée, mises à jour KYC, etc.) en quasi temps réel. Votre serveur expose un endpoint HTTPS ; nous envoyons des événements JSON signés par POST.

طلب HTTP

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

Vous pouvez fournir tout autre endpoint.

Headers

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

•C-Webhook-Id : identifiant unique de la requête webhook, généré par Chari.
•X-Api-Key : clé secrète pour l'authentification de votre système (vous devez nous fournir cette clé).

Réponse attendue : 200 OK sous 5 secondes (corps vide). En cas d'erreur métier ou de rupture de contrat de notre côté, veuillez retourner une erreur 400 avec une description du problème. Tout code non-2xx déclenche un retry.

خصائص body الحدث

Propriétés communes

Property	Type	مطلوب	Description
`WebhookId`	string	مطلوب	Identifiant du webhook.
`EventId`	string	مطلوب	Type d'événement. Ex : bank-transfer.initiated
`CRequestId`	string	مطلوب	Identifiant de traçage reçu du partenaire.
`OperationId`	int	مطلوب	ID de l'opération exécutée (peut être 0 si aucune opération créée).
`TransactionId`	int	اختياري	ID de la transaction principale.
`OperationType`	int	مطلوب	Code du type d'opération (voir Types).
`OperationStatus`	int	مطلوب	1 = Open, 2 = Completed, 3 = Failed, 4 = Canceled
`CreatedAt`	date	مطلوب	Date de début du processus.
`ExecutedAt`	date	مطلوب	Date d'exécution de l'opération.
`Amount`	decimal	مطلوب	Montant de l'opération.
`FeeAmount`	decimal	مطلوب	Montant des frais.
`PrimaryAccountNumber`	string	مطلوب	Numéro de téléphone de l'émetteur.
`SecondaryAccountNumber`	string	اختياري	Numéro de téléphone du destinataire.
`Method`	string	اختياري	Méthode : Card / Agent / Network

Spécifique Cash-in Card

Property	Type	مطلوب	Description
`CustomData`	string	اختياري	Données personnalisées fournies par le partenaire (max 128 caractères).
`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	اختياري	Nom du bénéficiaire pour les virements bancaires.

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

Property	Type	مطلوب	Description
`NetworkName`	string	اختياري	Nom du réseau pour les opérations réseau.
`Reference`	string	اختياري	Référence de l'opération par référence.

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

Backoff:1 min, 5 min, 30 min, 60 min, puis toutes les 6h jusqu'à 72h au total.

Stop:Arrêt au premier 200.

Dead letter:Après 72h sans réponse 200, l'événement est marqué comme non distribuable.

الأحداث

Event ID	Description
`customer.level.updated`	Niveau de compte client mis à jour
`cashin.card.authorized`	CashIn par carte accepté
`payment.card.authorized`	Paiement par carte accepté
`payment.received`	Paiement reçu par le marchand
`bank-transfer.initiated`	Virement bancaire envoyé
`bank-transfer.completed`	Virement bancaire finalisé (réglé, rejeté ou retourné — inspecter OperationStatus)
`bank-transfer.received`	Virement bancaire reçu
`transfer.received`	Transfert reçu
`cashin.network.executed`	CashIn par référence exécuté
`cashout.network.executed`	CashOut par référence exécuté

مثال body الحدث

Virement bancaire

json

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

CashIn par carte

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

F

Format de réponse

Toutes les réponses de l'API sont enveloppées dans un objet `data`. Le header C-Request-Id que vous envoyez est renvoyé dans la réponse pour faciliter le traçage.

Header C-Request-Id

L'API prend en charge le header C-Request-Id pour permettre le suivi des requêtes. Vous pouvez inclure un C-Request-Id unique dans les headers de requête, qui sera renvoyé dans la réponse. Cela facilite le logging, le debugging et le traçage des requêtes dans des systèmes distribués.

T

Types et références

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

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

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

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	Ouverte (cycle en cours)
2	COMPLETED	Terminée avec succès
3	FAILED	Échouée
4	CANCELED	Annulée

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

ID	Code	Description
1	OPEN	En cours
2	COMPLETED	Terminée
3	FAILED	Échouée
4	CANCELED	Annulée

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

ID	Code	Description
1	CREDIT	Crédit (entrée de fonds)
2	DEBIT	Débit (sortie de fonds)

حالات العميل

ID	Code	Description
0	NOT_EXISTS	Le numéro n'existe pas chez ChariMoney
1	NOT_CONFIRMED	Existe mais non confirmé (OTP non saisi)
2	CONFIRMED	Confirmé et inscrit au Switch
3	ACTIVE	Inscrit, actif et PIN créé
4	LOCKED_TEMPORARY	Temporairement bloqué (tentatives excessives)
5	LOCKED	Bloqué

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

ID	Code	Description
1	LEVEL_1	Niveau 1 — Nom + téléphone valide + numéro CIN. Plafond : 1 000 MAD.
2	LEVEL_2	Niveau 2 — KYC complet (CIN + selfie ou scan document). Plafond : 4 000 MAD.
3	LEVEL_3	Niveau 3 — Pièce vérifiée + entretien + dossier numérique. Plafond : 20 000 MAD.
4	LEVEL_4	Niveau 4 — KYC complet + entretien + justificatif de revenus + justificatif de domicile. Plafond : 100 000 MAD.
5	MERCHANT	Marchand — KYB complet + immatriculation IF/RC. Plafond : négocié.

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

ID	Code	Description
1	IdentityCard	Carte d'identité nationale
2	DrivingLicense	Permis de conduire
3	Passport	Passeport
4	ResidencePermit	Carte de séjour
5	ProofOfIncome	Justificatif de revenus
6	ProofOfResidence	Justificatif de domicile
7	Selfie	Selfie / Photo de visage
8	CommercialRegister	Registre de commerce

C

Codes d'erreur

رموز حالة HTTP

401 UnauthorizedIdentifiants d'authentification (API KEY) non autorisés.

422 UnprocessableLe serveur ne peut pas traiter la requête.

423 LockedL'accès est verrouillé pour le client donné.

400 Bad RequestErreur spécifique avec un code d'erreur Chari (voir ci-dessous).

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

json

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

رموز أخطاء Chari

10xxxGénéral

Code	Message	نقاط النهاية (endpoints) ذات الصلة
10001	Paramètres manquants.

20xxxClient

Code	Message	نقاط النهاية (endpoints) ذات الصلة
20000	Le format du numéro de téléphone est invalide.
20005	L'utilisateur spécifié est introuvable.
20006	Les paramètres initiaux fournis sont incorrects ou invalides.
20007	Le code de catégorie marchand (MCC) fourni est incorrect ou non reconnu.
20008	L'inscription est temporairement verrouillée pour des raisons de sécurité.
20009	La demande est en attente de confirmation. Veuillez patienter.
20017	Aucune demande en attente n'est associée au numéro de téléphone fourni.

26xxxPIN / Authentification

Code	Message	نقاط النهاية (endpoints) ذات الصلة
26001	Le PIN saisi est incorrect.
26004	Un PIN a déjà été défini pour ce wallet.
26005	Le PIN fourni ne respecte pas le format requis (doit être un nombre à 4 chiffres).

27xxxBénéficiaire

Code	Message	نقاط النهاية (endpoints) ذات الصلة
27000	Le bénéficiaire existe déjà avec le même numéro de téléphone.
27001	Le bénéficiaire n'existe pas.

32xxxKYC / Mise à niveau

Code	Message	نقاط النهاية (endpoints) ذات الصلة
32000	Une demande de mise à niveau est déjà en cours d'examen pour ce compte.

I

Infrastructure et sécurité

البيئات

Sandbox

https://sandbox.charimoney.com

Environnement de développement et de test. Les transactions sont simulées.

Production

Communiqué sur demande

Transactions réelles. Nécessite une approbation préalable et des tests réussis en sandbox.

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

Vous recevrez une clé API dédiée pour chaque environnement (sandbox et production). Les clés doivent être incluses dans le header Chari-Api-Key de chaque requête.

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

Vous devez partager les adresses IP et/ou domaines qui consommeront l'API. Seuls les IP/domaines autorisés (whitelistés) pourront accéder à l'API. En cas de changement d'infrastructure, mettez à jour votre liste auprès du support.

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

1Fournir une liste d'adresses IP publiques ou de domaines qui accéderont à l'API.
2Transmettre cette liste à l'équipe support avant toute intégration.
3Communiquer tout changement au moins 72 h à l'avance afin de mettre à jour les règles de sécurité.

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

•L'authentification API est gérée par clés API.
•Les requêtes provenant d'IP/domaines non autorisés seront rejetées.
•En cas de compromission d'une clé API, elle doit être immédiatement révoquée et rotée.
•Un rate limiting peut s'appliquer pour prévenir les abus (contactez le support pour les limites).
•L'environnement de production nécessite une approbation préalable et des tests réussis en sandbox.

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

1
Demander les clés API
Contactez le support pour recevoir vos clés dédiées sandbox et production.
2
Soumettre les IP/domaines
Fournissez la liste des IP publiques ou domaines pour le whitelisting.
3
Tester en sandbox
Effectuez tous vos tests d'intégration dans l'environnement sandbox.
4
Passer en production
Une fois approuvé, basculez vers la production avec votre clé API live.

Vous recevrez un formulaire à remplir avec les éléments nécessaires.

وثائق API

البدء

Headers المصادقة

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

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

Postman Collection

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

Présentation — M-Wallet au Maroc

ما هو M-Wallet؟

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

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

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

Glossaire

Inscription client

Flux d'inscription client

Vérifier le statut (Chari)

Vérifier le wallet par défaut

Inscription

Confirmation OTP

Renvoyer l'OTP

Connexion par PIN

Créer un PIN

Modifier le PIN

Réinitialiser le PIN

Consulter le solde

Informations client

Désinscription

KYC (Vérification d'identité)

Flux KYC (ShareID)

مسار التكامل

Authentification KYC

Confirmation KYC

Upload documents marchand

Opérations

Dépôt par carte (CashIn Card)

Flux CashIn par carte bancaire (3D Secure)

Carte de test

Aperçu (par téléphone)

Exécuter (par téléphone)

Exécuter avec carte sauvegardée

Aperçu (par agent)

Exécuter (par agent)

Transfert wallet-à-wallet

Flux de transfert wallet-à-wallet

Aperçu

Exécuter

Virement bancaire

Flux de virement bancaire

Aperçu

Exécuter

Paiement marchand

Flux de paiement marchand

Par téléphone — Aperçu

Par téléphone — Exécuter

Par QR Code — Aperçu

Par QR Code — Exécuter

Par carte — Aperçu

Par carte — Exécuter

Par carte tokenisée — Exécuter

Génération QR statique

Génération QR dynamique

Chargeback (Rétrofacturation)

Flux de chargeback (rétrofacturation)

Aperçu

Exécuter

Opérations par référence (Request)

Flux CashIn/CashOut par référence

Demander un CashIn

Demander un CashOut

Consulter les opérations

Par client

Par ID

Toutes (par partenaire)

Par C-Request-Id

Remboursement

Aperçu

Exécuter

Bénéficiaires

Flux de gestion des bénéficiaires

Liste des bénéficiaires