Documentation API

Référence complète de l'API Banking-as-a-Service de Chari Money. Intégrez des services financiers dans vos applications grâce à nos endpoints robustes et sécurisés.

Démarrage rapide

Version 1.9 · Dernière mise à jour 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.

En-têtes d'authentification

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

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

Carte de test (Sandbox)

PAN

4918914107195005

CVV

123

Expiration

08/26 (ou toute date future)

Code 3DS

555

Nouveau

Pack LLM & IA

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

Télécharger .zip

Postman Collection

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

Télécharger

Journal des modifications

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

Présentation — M-Wallet au Maroc

Qu'est-ce qu'un 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.

Principes fondamentaux

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.

Types de compte

Type	Propriétaire	Description	Opérations
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.

Niveaux de compte

Niveau	Exigence KYC	Plafond de solde
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é

Glossaire

Terme	Définition
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.

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	Requis	Description
`PhoneNumber`	string	query	Requis	Numéro de téléphone du client. Format : +212*********

Notes

•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	Requis	Description
`phoneNumber`	string	query	Requis	Numéro de téléphone du client. Format : +212*********

Notes

•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	Requis	Description
`phoneNumber`	string	body	Requis	Numéro de téléphone du client. Format : +212*********
`firstName`	string	body	Requis	Prénom. Minimum 2 lettres (caractères latins uniquement).
`lastName`	string	body	Requis	Nom de famille. Minimum 2 lettres (caractères latins uniquement).
`cin`	string	body	Requis	Numéro de carte d'identité. Minimum 5 caractères.
`walletType`	string	body	Requis	"P" : Particulier / "C" : Commerçant
`closeLoopOnly`	boolean	body	Optionnel	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	Requis	Description
`phoneNumber`	string	body	Requis	Numéro de téléphone du client. Format : +212*********
`code`	string	body	Requis	Code OTP reçu par SMS. Format : xxx-xxx
`walletType`	string	body	Requis	2 types acceptés : "P" : Particulier, "C" : Commerçant (Merchant).
`autoActivate`	boolean	body	Optionnel	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	Requis	Description
`phoneNumber`	string	query	Requis	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	Requis	Description
`phoneNumber`	string	body	Requis	Numéro de téléphone du client. Format : +212*********
`pin`	string	body	Requis	Code PIN du client.

Notes

•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	Requis	Description
`phoneNumber`	string	body	Requis	Numéro de téléphone du client. Format : +212*********
`pin`	string	body	Requis	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	Requis	Description
`phoneNumber`	string	body	Requis	Numéro de téléphone du client. Format : +212*********
`oldPin`	string	body	Requis	PIN actuel du client.
`newPin`	string	body	Requis	Nouveau PIN du client.

POST{host}/api/customers/pin/resetBientôt disponible

Réinitialiser le PIN

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

Aucun paramètre requis.

GET{host}/api/customers/balance

Consulter le solde

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

Parameter	Type	In	Requis	Description
`phoneNumber`	string	query	Requis	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	Requis	Description
`phoneNumber`	string	query	Requis	Numéro de téléphone du client. Format : +212*********

Notes

•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	Requis	Description
`PhoneNumber`	string	body	Requis	Numéro de téléphone du client. Format : +212*********
`Reason`	int	body	Requis	Code de la raison de clôture (voir notes).

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

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.

Flux d'intégration

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	Requis	Description
`PhoneNumber`	string	query	Requis	Numéro de téléphone du client. Format : +212*********

Notes

•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	Requis	Description
`PhoneNumber`	string	query	Requis	Numéro de téléphone du client. Format : +212*********
`AccountLevel`	int	query	Requis	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	Requis	Description
`PhoneNumber`	string	query	Requis	Numéro de téléphone du commerçant. Format : +212*********
`KycDocuments`	multipart form	body	Requis	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	Requis	Type de document (voir la table "Types de documents").
`KycDocuments[n].DocFront`	file	body	Requis	Image recto du document. Formats acceptés : PNG, JPG/JPEG, PDF.
`KycDocuments[n].DocBack`	file	body	Optionnel	Image verso (requis pour IdentityCard, DrivingLicense, ResidencePermit).

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

Expiration

08/26 (ou toute date future)

Code 3DS

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	Requis	Description
`PhoneNumber`	string	query	Requis	Numéro de téléphone du client. Format : +212*********
`Amount`	decimal	body	Requis	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	Requis	Description
`PhoneNumber`	string	query	Requis	Numéro de téléphone du client.
`FirstName`	string	body	Requis	Prénom du titulaire de la carte.
`LastName`	string	body	Requis	Nom du titulaire de la carte.
`Cvv`	string	body	Requis	Code de sécurité à 3 chiffres (CVV).
`Amount`	decimal	body	Requis	Montant à déposer.
`Currency`	string	body	Optionnel	Code devise ISO 3 lettres (ex : MAD).
`Pan`	string	body	Requis	Numéro complet de la carte (PAN).
`ExpiryDate`	string	body	Requis	Date d'expiration au format YYMM.
`KeepAlive`	bool	body	Requis	true : sauvegarder la carte pour usage futur / false : usage unique.
`CardName`	string	body	Optionnel	Nom choisi par l'utilisateur pour sauvegarder la carte.

Notes

•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	Requis	Description
`PhoneNumber`	string	query	Requis	Numéro de téléphone du client.
`CardId`	int	route	Requis	Identifiant de la carte sauvegardée.
`Cvv`	string	body	Requis	Code de sécurité à 3 chiffres.
`Amount`	decimal	body	Requis	Montant à déposer.

Notes

•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	Requis	Description
`code`	string	query	Requis	Code de l'agent.
`Amount`	decimal	body	Requis	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	Requis	Description
`agent`	string	query	Requis	Code de l'agent.
`FirstName`	string	body	Requis	Prénom du titulaire de la carte.
`LastName`	string	body	Requis	Nom du titulaire de la carte.
`Cvv`	string	body	Requis	Code de sécurité à 3 chiffres.
`Amount`	decimal	body	Requis	Montant à déposer.
`Pan`	string	body	Requis	Numéro complet de la carte.
`ExpiryDate`	string	body	Requis	Date d'expiration au format YYMM.
`KeepAlive`	bool	body	Requis	Sauvegarder la carte pour usage futur.
`Currency`	string	body	Optionnel	Code devise ISO 3 lettres (ex : MAD).
`CardName`	string	body	Optionnel	Nom choisi par l'utilisateur pour sauvegarder la carte.

Notes

•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	Requis	Description
`CustomerPhoneNumber`	string	body	Requis	Numéro de l'émetteur. Format : +212*********
`Amount`	decimal	body	Requis	Montant à transférer.
`Reason`	string	body	Requis	Motif du transfert.
`RecipientPhoneNumber`	string	body	Requis	Numéro du bénéficiaire. Format : +212*********
`BeneficiaryId`	int	body	Optionnel	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	Requis	Description
`CustomerPhoneNumber`	string	body	Requis	Numéro de l'émetteur.
`Amount`	decimal	body	Requis	Montant à transférer.
`Reason`	string	body	Requis	Motif du transfert.
`RecipientPhoneNumber`	string	body	Requis	Numéro du bénéficiaire.
`BeneficiaryId`	int	body	Optionnel	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	Requis	Description
`CustomerPhoneNumber`	string	body	Optionnel	Requis si AgentCode est vide. Exclusif avec AgentCode (l'un OU l'autre).
`AgentCode`	string	body	Optionnel	Requis si CustomerPhoneNumber est vide. Code Agent (Principal ou Retail). Exclusif avec CustomerPhoneNumber.
`Amount`	decimal	body	Requis	Montant à virer.
`Reason`	string	body	Requis	Motif du virement (caractères latins uniquement, 35 caractères max).
`BeneficiaryId`	int	body	Optionnel	Optionnel si rib + beneficiaryName sont fournis.
`BeneficiaryName`	string	body	Optionnel	Optionnel si beneficiaryId est fourni.
`Rib`	string	body	Optionnel	RIB : chaîne numérique de 24 chiffres. Optionnel si beneficiaryId est fourni.

Notes

•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	Requis	Description
`CustomerPhoneNumber`	string	body	Optionnel	Requis si AgentCode est vide. Exclusif avec AgentCode (l'un OU l'autre).
`AgentCode`	string	body	Optionnel	Requis si CustomerPhoneNumber est vide. Exclusif avec CustomerPhoneNumber.
`Amount`	decimal	body	Requis	Montant à virer.
`Reason`	string	body	Optionnel	Motif du virement (optionnel à l'exécution).
`BeneficiaryId`	int	body	Optionnel	Optionnel si rib + beneficiaryName sont fournis.
`BeneficiaryName`	string	body	Optionnel	Optionnel si beneficiaryId est fourni.
`Rib`	string	body	Optionnel	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	Requis	Description
`CustomerPhoneNumber`	string	body	Requis	Numéro du client payeur.
`Amount`	decimal	body	Requis	Montant du paiement.
`Reason`	string	body	Requis	Motif du paiement.
`RecipientPhoneNumber`	string	body	Requis	Numéro du marchand.
`BeneficiaryId`	int	body	Optionnel	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	Requis	Description
`CustomerPhoneNumber`	string	body	Requis	Numéro du client payeur.
`Amount`	decimal	body	Requis	Montant du paiement.
`Reason`	string	body	Requis	Motif du paiement.
`RecipientPhoneNumber`	string	body	Requis	Numéro du marchand.
`BeneficiaryId`	int	body	Optionnel	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	Requis	Description
`CustomerPhoneNumber`	string	body	Requis	Numéro du client payeur.
`QrCodeContent`	string	body	Requis	Contenu du QR Code scanné.
`Amount`	decimal	body	Requis	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	Requis	Description
`CustomerPhoneNumber`	string	body	Requis	Numéro du client payeur.
`QrCodeContent`	string	body	Requis	Contenu du QR Code.
`Amount`	decimal	body	Requis	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	Requis	Description
`PhoneNumber`	string	query	Requis	Numéro du marchand.
`Amount`	decimal	body	Requis	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	Requis	Description
`PhoneNumber`	string	query	Requis	Numéro du marchand. Format : +212*********
`FirstName`	string	body	Requis	Prénom du titulaire.
`LastName`	string	body	Requis	Nom du titulaire.
`Cvv`	string	body	Requis	CVV (3 chiffres).
`Amount`	decimal	body	Requis	Montant du paiement.
`Pan`	string	body	Requis	Numéro de carte (PAN).
`ExpiryDate`	string	body	Requis	Date d'expiration au format `YYMM`. Ex : `2608`.
`KeepAlive`	bool	body	Requis	Tokenizer la carte pour réutilisation via l'endpoint Tokenized Card.
`Currency`	string	body	Optionnel	Devise. Par défaut : MAD.
`3dSecure`	bool	body	Optionnel	Activer 3D Secure. Par défaut : true.
`FeesPercent`	decimal	body	Optionnel	Pourcentage de frais appliqués au payeur.
`AllowInternationalCards`	bool	body	Optionnel	Accepter les cartes internationales.
`InternationalFeesPercent`	decimal	body	Optionnel	Frais % spécifiques aux cartes internationales.
`AutoCapture`	bool	body	Optionnel	Capture automatique du paiement.
`NotificationUrl`	string	body	Optionnel	URL notifiée après fin de transaction (succès/échec).
`AcceptUrl`	string	body	Optionnel	URL de redirection en cas de succès 3DS.
`CardName`	string	body	Optionnel	Libellé de la carte (pour tokenisation).
`ExternalReference`	string	body	Optionnel	Référence externe du marchand.

Notes

•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	Requis	Description
`cardId`	int	path	Requis	ID de la carte tokenisée.
`PhoneNumber`	string	query	Requis	Numéro du marchand. Format : +212*********
`Cvv`	string	body	Requis	CVV (3 chiffres).
`Amount`	decimal	body	Requis	Montant du paiement.

Notes

•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	Requis	Description
`PhoneNumber`	string	query	Requis	Numéro du marchand.
`MaskedNumber`	bool	query	Optionnel	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	Requis	Description
`PhoneNumber`	string	query	Requis	Numéro du marchand.
`MaskedNumber`	bool	query	Optionnel	Masquer le numéro du marchand.
`Amount`	decimal	body	Requis	Montant fixe du QR Code.

Notes

•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	Requis	Description
`SourcePhoneNumber`	string	body	Requis	Numéro du client à l'origine. Format : +212*********
`Amount`	decimal	body	Requis	Montant du chargeback.
`Description`	string	body	Requis	Motif du chargeback.
`DestinationPhoneNumber`	string	body	Requis	Numéro du destinataire. Format : +212*********
`OriginalOperationId`	int	body	Requis	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	Requis	Description
`SourcePhoneNumber`	string	body	Requis	Numéro du client à l'origine.
`Amount`	decimal	body	Requis	Montant du chargeback.
`Description`	string	body	Requis	Motif du chargeback.
`DestinationPhoneNumber`	string	body	Requis	Numéro du destinataire.
`OriginalOperationId`	int	body	Requis	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	Requis	Description
`PhoneNumber`	string	body	Requis	Numéro de téléphone du client.
`Amount`	decimal	body	Requis	Montant du CashIn.

Notes

•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	Requis	Description
`PhoneNumber`	string	body	Requis	Numéro de téléphone du client.
`Amount`	decimal	body	Requis	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	Requis	Description
`PhoneNumber`	string	query	Requis	Numéro de téléphone du client.
`PageSize`	int	query	Optionnel	Résultats par page. Par défaut : 10
`PageNumber`	int	query	Optionnel	Numéro de page. Par défaut : 1
`OperationType`	list int	query	Optionnel	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	Optionnel	1=OPEN, 2=COMPLETED, 3=FAILED, 4=CANCELED
`Sens`	int	query	Optionnel	1=CREDIT, 2=DEBIT
`From`	datetime	query	Optionnel	Date/heure de début du filtre.
`To`	datetime	query	Optionnel	Date/heure de fin du filtre.

Notes

•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	Requis	Description
`PhoneNumber`	string	query	Requis	Numéro de téléphone du client.
`Id`	int	route	Requis	ID de l'opération.

Notes

•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	Requis	Description
`PhoneNumber`	string	query	Requis	Numéro de téléphone du client. Format : +212*********
`PageSize`	int	query	Optionnel	Résultats par page. Par défaut : 10
`PageNumber`	int	query	Optionnel	Numéro de page (commence à 1). Par défaut : 1
`OperationType`	list int	query	Optionnel	Filtrer par type d'opération.
`TransactionStatus`	int	query	Optionnel	Filtrer par statut de transaction.
`Sens`	int	query	Optionnel	1 = CREDIT, 2 = DEBIT
`From`	datetime	query	Optionnel	Date/heure de début.
`To`	datetime	query	Optionnel	Date/heure de fin.

GET{host}/api/operations/c-request-idBientôt disponible

Par C-Request-Id

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

Aucun paramètre requis.

Remboursement

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

Aperçu

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

Parameter	Type	In	Requis	Description
`PhoneNumber`	string	body	Requis	Numéro du client à rembourser.
`OperationId`	int	body	Requis	ID de l'opération à rembourser.
`RefundAmount`	decimal	body	Requis	Montant du remboursement.
`OrderId`	string	body	Requis	OrderId original du paymentGateway.
`TransactionTrackId`	string	body	Requis	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	Requis	Description
`phoneNumber`	string	body	Requis	Numéro du client.
`OperationId`	int	body	Requis	ID de l'opération à rembourser.
`RefundAmount`	decimal	body	Requis	Montant du remboursement.
`OrderId`	string	body	Requis	OrderId original.
`TransactionTrackId`	string	body	Requis	TransactionTrackId original.

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	Requis	Description
`PhoneNumber`	string	query	Requis	Numéro de téléphone du client.
`PageSize`	int	query	Optionnel	Résultats par page. Par défaut : 10
`PageNumber`	int	query	Optionnel	Numéro de page. Par défaut : 1
`Search`	string	query	Optionnel	Filtrer par mot-clé.
`From`	datetime	query	Optionnel	Date de création — début.
`To`	datetime	query	Optionnel	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	Requis	Description
`PhoneNumber (query)`	string	query	Requis	Numéro de téléphone du client (propriétaire).
`Name`	string	body	Requis	Nom du bénéficiaire. Minimum 2 lettres.
`PhoneNumber`	string	body	Optionnel	Numéro du bénéficiaire. Format : +212*********
`Rib`	string	body	Optionnel	RIB du bénéficiaire. 24 chiffres.
`Email`	string	body	Optionnel	Email du bénéficiaire.

Notes

•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	Requis	Description
`PhoneNumber (query)`	string	query	Requis	Numéro de téléphone du client (propriétaire).
`Id`	int	route	Requis	ID du bénéficiaire à modifier.
`Name`	string	body	Requis	Nom du bénéficiaire. Minimum 2 lettres.
`PhoneNumber (body)`	string	body	Optionnel	Numéro de téléphone du bénéficiaire.
`Rib`	string	body	Optionnel	RIB du bénéficiaire. 24 chiffres.
`Email`	string	body	Optionnel	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	Requis	Description
`PhoneNumber`	string	query	Requis	Numéro de téléphone du client.
`Id`	int	route	Requis	ID du bénéficiaire à supprimer.

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	Requis	Description
`PhoneNumber`	string	query	Requis	Numéro de téléphone du client.
`PageSize`	int	query	Optionnel	Résultats par page. Par défaut : 10
`PageNumber`	int	query	Optionnel	Numéro de page. Par défaut : 1

Notes

•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	Requis	Description
`PhoneNumber`	string	query	Requis	Numéro de téléphone du client.
`Id`	int	route	Requis	ID de la carte.

DELETE{host}/api/customers/tokenized/cards/{id}Bientôt disponible

Supprimer une carte

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

Aucun paramètre requis.

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	Requis	Description
`Code`	string	query	Requis	Code de l'agent.
`PageSize`	int	query	Optionnel	Résultats par page. Par défaut : 10
`PageNumber`	int	query	Optionnel	Numéro de page. Par défaut : 1
`From`	datetime	query	Optionnel	Création de l'agent — date début.
`To`	datetime	query	Optionnel	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	Requis	Description
`Code`	string	route	Requis	Code de l'agent.

POST{host}/api/agents/retail

Ajouter un agent

Ajoute un nouvel agent détaillant.

Parameter	Type	In	Requis	Description
`PhoneNumber`	string	body	Requis	Numéro de téléphone de l'agent. Format : +212*********
`Name`	string	body	Requis	Nom commercial de l'agent.
`FirstName`	string	body	Requis	Prénom. Minimum 2 lettres.
`LastName`	string	body	Requis	Nom de famille. Minimum 2 lettres.
`Cin`	string	body	Requis	Numéro de pièce d'identité.
`Address`	string	body	Optionnel	Adresse de l'agent.
`Email`	string	body	Optionnel	Email de l'agent.

PUT{host}/api/agents/retail/{code}Bientôt disponible

Modifier un agent

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

Aucun paramètre requis.

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	Requis	Description
`Reference`	string	query	Requis	Référence unique de l'opération.

Notes

•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	Requis	Description
`Code`	string	body	Requis	Code de l'agent effectuant l'opération.
`Reference`	string	body	Requis	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	Requis	Description
`Reference`	string	query	Requis	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	Requis	Description
`Code`	string	body	Requis	Code de l'agent effectuant l'opération.
`Reference`	string	body	Requis	Référence unique de l'opération à exécuter.

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	Requis	Description
`Code`	string	query	Requis	Code de l'agent principal.

Notes

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

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

Expiration

08/26 (ou toute date future)

Code 3DS

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	Requis	Description
`reference`	string	body	Requis	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	Requis	Description
`reference`	string	body	Requis	Référence numérique retournée lors de la création de la requête CashOut.

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.

Requête HTTP

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

Vous pouvez fournir tout autre endpoint.

En-têtes

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.

Propriétés du body d'événement

Propriétés communes

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

Spécifique Cash-in Card

Property	Type	Requis	Description
`CustomData`	string	Optionnel	Données personnalisées fournies par le partenaire (max 128 caractères).
`GatewayTrackId`	string	Optionnel	Gateway Transaction Track Id.
`GatewayOrderId`	string	Optionnel	Gateway Transaction Order Id.
`GatewayReferenceId`	string	Optionnel	Gateway Transaction Reference Id.

Spécifique virement bancaire

Property	Type	Requis	Description
`BankTransferBeneficiaryName`	string	Optionnel	Nom du bénéficiaire pour les virements bancaires.

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

Property	Type	Requis	Description
`NetworkName`	string	Optionnel	Nom du réseau pour les opérations réseau.
`Reference`	string	Optionnel	Référence de l'opération par référence.

Politique de retry

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.

Événements

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é

Exemple de body d'événement

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

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.

En-tête 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.

Types et références

Types d'opérations

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

Types de transactions

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

Statuts d'opération

ID	Code	Description
1	OPEN	Ouverte (cycle en cours)
2	COMPLETED	Terminée avec succès
3	FAILED	Échouée
4	CANCELED	Annulée

Statuts de transaction

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

Direction de transaction (Sens)

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

Statuts client

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é

Niveaux de compte

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

Types de documents

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

Codes d'erreur

Codes de statut 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).

Format de réponse d'erreur

json

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

Codes d'erreur Chari

10xxxGénéral

Code	Message	Endpoints associés
10001	Paramètres manquants.

20xxxClient

Code	Message	Endpoints associés
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 associés
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 associés
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 associés
32000	Une demande de mise à niveau est déjà en cours d'examen pour ce compte.

Infrastructure et sécurité

Environnements

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.

Gestion des clés 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.

Whitelisting d'IP et de domaines

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.

Comment soumettre vos IP / domaines

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

Sécurité et conformité

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

Prochaines étapes d'intégration

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.

Documentation API

Démarrage rapide

En-têtes d'authentification

Carte de test (Sandbox)

Pack LLM & IA

Postman Collection

Journal des modifications

Présentation — M-Wallet au Maroc

Qu'est-ce qu'un M-Wallet ?

Principes fondamentaux

Types de compte

Niveaux de compte

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)

Flux d'intégration

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