Aller au contenu principal

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.8 · Dernière mise à jour 5 novembre 2025

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 :

HeaderTypeRequisDescription
Chari-Api-KeystringRequisClé API pour l'authentification. Fournie par Chari pour chaque environnement.
C-Request-IdstringOptionnelIdentifiant 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/25 (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 des endpoints register-with-docs, merchant-kyc-upload, add-tokenized-card. 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.

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.

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

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

ParameterTypeInRequisDescription
PhoneNumberstringbodyRequisNuméro de téléphone du client. Format : +212*********
FirstNamestringbodyRequisPrénom. Minimum 2 lettres (caractères latins uniquement).
LastNamestringbodyRequisNom de famille. Minimum 2 lettres (caractères latins uniquement).
CinstringbodyRequisNuméro de carte d'identité. Minimum 5 caractères.
WalletTypestringbodyRequis"P" : Particulier / "C" : Commerçant
POST{host}/api/customers/register200

Inscription avec documents

Inscrit un commerçant avec ses documents KYC en une seule étape (multipart/form-data). Même route que l'inscription classique, mais avec des fichiers joints.

ParameterTypeInRequisDescription
phoneNumberstringbodyRequisNuméro de téléphone. Format : +212*********
firstNamestringbodyRequisPrénom (min. 2 lettres latines).
lastNamestringbodyRequisNom de famille (min. 2 lettres latines).
cinstringbodyRequisNuméro de carte d'identité (min. 5 caractères).
rcNumberstringbodyRequisNuméro du registre de commerce.
walletTypestringbodyRequis"C" (Commerçant).
kycDocuments[n].docTypeintbodyRequisType de document (voir la table "Types de documents").
kycDocuments[n].docFrontfilebodyRequisImage recto du document.
kycDocuments[n].docBackfilebodyOptionnelImage verso du document (si applicable).

Notes

  • •Content-Type doit être multipart/form-data (pas application/json).
  • •Les fichiers acceptés sont les images (JPEG, PNG) et PDF.
  • •Voir la table "Types de documents" pour les valeurs docType valides.
POST{host}/api/customers/register/confirm

Confirmation OTP

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

ParameterTypeInRequisDescription
PhoneNumberstringbodyRequisNuméro de téléphone du client. Format : +212*********
CodestringbodyRequisCode OTP reçu par SMS. Format : xxx-xxx
autoActivatebooleanbodyOptionnelSi true, active directement le client sans nécessiter l'étape de création de PIN. Utile si vous ne comptez pas utiliser le système de PIN de ChariMoney.
POST{host}/api/customers/confirm/resend-otp

Renvoyer l'OTP

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

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

ParameterTypeInRequisDescription
PhoneNumberstringbodyRequisNuméro de téléphone du client. Format : +212*********
PinstringbodyRequisCode 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é.

ParameterTypeInRequisDescription
PhoneNumberstringbodyRequisNuméro de téléphone du client. Format : +212*********
PinstringbodyRequisCode PIN du client (4 chiffres obligatoires).
PATCH{host}/api/customers/pin

Modifier le PIN

Modifie le code PIN existant d'un client.

ParameterTypeInRequisDescription
PhoneNumberstringbodyRequisNuméro de téléphone du client. Format : +212*********
OldPinstringbodyRequisPIN actuel du client.
NewPinstringbodyRequisNouveau 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.

ParameterTypeInRequisDescription
PhoneNumberstringqueryRequisNumé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).

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

ParameterTypeInRequisDescription
PhoneNumberstringbodyRequisNuméro de téléphone du client. Format : +212*********
ReasonintbodyRequisCode 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
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.

Flux d'intégration

  1. 1Votre app appelle "/kyc/shareid/auth" pour obtenir un token KYC temporaire.
  2. 2L'app ouvre le SDK ShareID avec ce token.
  3. 3L'utilisateur scanne sa pièce d'identité et effectue un selfie guidé.
  4. 4ShareID exécute les vérifications.
  5. 5Votre app appelle "/kyc/session/complete" pour signaler la fin du flux côté appareil.
  6. 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.

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

ParameterTypeInRequisDescription
PhoneNumberstringqueryRequisNuméro de téléphone du client. Format : +212*********
AccountLevelintqueryRequisNiveau de compte cible (2, 3 ou 4).
POST{host}/api/customers/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).

ParameterTypeInRequisDescription
PhoneNumberstringqueryRequisNuméro de téléphone du commerçant. Format : +212*********
kycDocuments[n].docTypeintbodyRequisType de document (voir la table "Types de documents").
kycDocuments[n].docFrontfilebodyRequisImage recto du document.
kycDocuments[n].docBackfilebodyOptionnelImage verso (si applicable).
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)

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.

ParameterTypeInRequisDescription
PhoneNumberstringqueryRequisNuméro de téléphone du client. Format : +212*********
AmountdecimalbodyRequisMontant à 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.

ParameterTypeInRequisDescription
PhoneNumberstringqueryRequisNuméro de téléphone du client.
FirstNamestringbodyRequisPrénom du titulaire de la carte.
LastNamestringbodyRequisNom du titulaire de la carte.
CvvstringbodyRequisCode de sécurité à 3 chiffres (CVV).
AmountdecimalbodyRequisMontant à déposer.
CurrencystringbodyOptionnelCode devise ISO 3 lettres (ex : MAD).
PanstringbodyRequisNuméro complet de la carte (PAN).
ExpiryDatestringbodyRequisDate d'expiration au format YYMM.
KeepAliveboolbodyRequistrue : sauvegarder la carte pour usage futur / false : usage unique.
CardNamestringbodyOptionnelNom 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.

ParameterTypeInRequisDescription
PhoneNumberstringqueryRequisNuméro de téléphone du client.
CardIdintrouteRequisIdentifiant de la carte sauvegardée.
CvvstringbodyRequisCode de sécurité à 3 chiffres.
AmountdecimalbodyRequisMontant à déposer.
POST{host}/api/operations/cashin/card/agent/preview

Aperçu (par agent)

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

ParameterTypeInRequisDescription
codestringqueryRequisCode de l'agent.
AmountdecimalbodyRequisMontant à 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.

ParameterTypeInRequisDescription
agentstringqueryRequisCode de l'agent.
FirstNamestringbodyRequisPrénom du titulaire de la carte.
LastNamestringbodyRequisNom du titulaire de la carte.
CvvstringbodyRequisCode de sécurité à 3 chiffres.
AmountdecimalbodyRequisMontant à déposer.
PanstringbodyRequisNuméro complet de la carte.
ExpiryDatestringbodyRequisDate d'expiration au format YYMM.
KeepAliveboolbodyRequisSauvegarder la carte pour usage futur.
CurrencystringbodyOptionnelCode devise ISO 3 lettres (ex : MAD).
CardNamestringbodyOptionnelNom choisi par l'utilisateur pour sauvegarder la carte.

Transfert wallet-à-wallet

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

Aperçu

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

ParameterTypeInRequisDescription
CustomerPhoneNumberstringbodyRequisNuméro de l'émetteur. Format : +212*********
AmountdecimalbodyRequisMontant à transférer.
ReasonstringbodyRequisMotif du transfert.
RecipientPhoneNumberstringbodyRequisNuméro du bénéficiaire. Format : +212*********
BeneficiaryIdintbodyOptionnelRéférence à un bénéficiaire existant (optionnel).
POST{host}/api/operations/transfer

Exécuter

Exécute un transfert de fonds entre wallets.

ParameterTypeInRequisDescription
CustomerPhoneNumberstringbodyRequisNuméro de l'émetteur.
AmountdecimalbodyRequisMontant à transférer.
ReasonstringbodyRequisMotif du transfert.
RecipientPhoneNumberstringbodyRequisNuméro du bénéficiaire.
BeneficiaryIdintbodyOptionnelRé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.

ParameterTypeInRequisDescription
CustomerPhoneNumberstringbodyRequisRequis si AgentCode est vide.
AgentCodestringbodyOptionnelRequis si CustomerPhoneNumber est vide. Code Agent (Principal ou Retail).
AmountdecimalbodyRequisMontant à virer.
ReasonstringbodyRequisMotif du virement (caractères latins uniquement).
BeneficiaryIdintbodyOptionnelOptionnel si rib + beneficiaryName sont fournis.
BeneficiaryNamestringbodyOptionnelOptionnel si beneficiaryId est fourni.
RibstringbodyOptionnelRIB : 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.

ParameterTypeInRequisDescription
CustomerPhoneNumberstringbodyRequisRequis si agentCode est vide.
AgentCodestringbodyOptionnelRequis si CustomerPhoneNumber est vide.
AmountdecimalbodyRequisMontant à virer.
ReasonstringbodyOptionnelMotif du virement.
BeneficiaryIdintbodyOptionnelOptionnel si rib + beneficiaryName sont fournis.
BeneficiaryNamestringbodyOptionnelOptionnel si beneficiaryId est fourni.
RibstringbodyOptionnelRIB : 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.

ParameterTypeInRequisDescription
CustomerPhoneNumberstringbodyRequisNuméro du client payeur.
AmountdecimalbodyRequisMontant du paiement.
ReasonstringbodyRequisMotif du paiement.
RecipientPhoneNumberstringbodyRequisNuméro du marchand.
BeneficiaryIdintbodyOptionnelRé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.

ParameterTypeInRequisDescription
CustomerPhoneNumberstringbodyRequisNuméro du client payeur.
AmountdecimalbodyRequisMontant du paiement.
ReasonstringbodyRequisMotif du paiement.
RecipientPhoneNumberstringbodyRequisNuméro du marchand.
BeneficiaryIdintbodyOptionnelRé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.

ParameterTypeInRequisDescription
CustomerPhoneNumberstringbodyRequisNuméro du client payeur.
QrCodeContentstringbodyRequisContenu du QR Code scanné.
AmountdecimalbodyRequisMontant du paiement.
POST{host}/api/operations/merchant/payment/push/qrcode

Par QR Code — Exécuter

Effectue un paiement marchand par QR Code.

ParameterTypeInRequisDescription
CustomerPhoneNumberstringbodyRequisNuméro du client payeur.
QrCodeContentstringbodyRequisContenu du QR Code.
AmountdecimalbodyRequisMontant 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).

ParameterTypeInRequisDescription
PhoneNumberstringqueryRequisNuméro du marchand.
AmountdecimalbodyRequisMontant du paiement.
POST{host}/api/operations/merchant/payment/push/card

Par carte — Exécuter

Effectue un paiement marchand par carte (Card to Wallet).

ParameterTypeInRequisDescription
PhoneNumberstringqueryRequisNuméro du marchand.
AmountdecimalbodyRequisMontant du paiement.
POST{host}/api/operations/merchant/qrcode/static

Génération QR statique

Génère un QR Code statique avec un montant fixe pour un marchand.

ParameterTypeInRequisDescription
PhoneNumberstringqueryRequisNuméro du marchand.
MaskedNumberboolqueryOptionnelMasquer le numéro du marchand dans le contenu QR. Ex : +2126######74
AmountdecimalbodyRequisMontant fixe du QR Code.
GET{host}/api/operations/merchant/qrcode

Génération QR dynamique

Génère un QR Code dynamique (sans montant fixe) pour un marchand.

ParameterTypeInRequisDescription
PhoneNumberstringqueryRequisNuméro du marchand.
MaskedNumberboolqueryOptionnelMasquer le numéro du marchand.

Notes

  • •QR statique : le montant est fixe et intégré dans le QR.
  • •QR dynamique : le client saisit le montant lors du paiement.
  • •qrCodeReference : référence unique attribuée aux QR dynamiques.

Chargeback (Rétrofacturation)

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

Aperçu

Vérifie la faisabilité d'un chargeback.

ParameterTypeInRequisDescription
SourcePhoneNumberstringbodyRequisNuméro du client à l'origine. Format : +212*********
AmountdecimalbodyRequisMontant du chargeback.
DescriptionstringbodyRequisMotif du chargeback.
DestinationPhoneNumberstringbodyRequisNuméro du destinataire. Format : +212*********
OriginalOperationIdintbodyRequisID de l'opération d'origine qui a déclenché le chargeback.
POST{host}/api/operations/chargeback

Exécuter

Exécute un chargeback.

ParameterTypeInRequisDescription
SourcePhoneNumberstringbodyRequisNuméro du client à l'origine.
AmountdecimalbodyRequisMontant du chargeback.
DescriptionstringbodyRequisMotif du chargeback.
DestinationPhoneNumberstringbodyRequisNuméro du destinataire.
OriginalOperationIdintbodyRequisID 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.

ParameterTypeInRequisDescription
PhoneNumberstringbodyRequisNuméro de téléphone du client.
AmountdecimalbodyRequisMontant du CashIn.

Notes

  • •operationType : 1 = CashIn, 2 = CashOut
  • •operationStatus : 1 = open (en attente), 2 = completed (exécutée), 3 = failed (échouée)
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.

ParameterTypeInRequisDescription
PhoneNumberstringbodyRequisNuméro de téléphone du client.
AmountdecimalbodyRequisMontant 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.

ParameterTypeInRequisDescription
PhoneNumberstringqueryRequisNuméro de téléphone du client.
PageSizeintqueryOptionnelRésultats par page. Par défaut : 10
PageNumberintqueryOptionnelNuméro de page. Par défaut : 1
OperationTypelist intqueryOptionnel1=CASHIN, 2=CASHOUT, 3=TRANSFER, 5=PAYMENT_PUSH, 7=PAYMENT_REFUND, 9=BANK_TRANSFER, 12=CHARGEBACK, 24=PAYMENT_CARD
TransactionStatusintqueryOptionnel1=PENDING, 2=COMPLETED, 3=FAILED, 4=CANCELLED
SensintqueryOptionnel1=CREDIT, 2=DEBIT
FromdatetimequeryOptionnelDate/heure de début du filtre.
TodatetimequeryOptionnelDate/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.

ParameterTypeInRequisDescription
PhoneNumberstringqueryRequisNuméro de téléphone du client.
IdintrouteRequisID 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.

ParameterTypeInRequisDescription
PageSizeintqueryOptionnelRésultats par page. Par défaut : 10
PageNumberintqueryOptionnelNuméro de page. Par défaut : 1
OperationTypelist intqueryOptionnelFiltrer par type d'opération.
TransactionStatusintqueryOptionnelFiltrer par statut.
SensintqueryOptionnel1=CREDIT, 2=DEBIT
FromdatetimequeryOptionnelDate/heure de début.
TodatetimequeryOptionnelDate/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.

ParameterTypeInRequisDescription
PhoneNumberstringbodyRequisNuméro du client à rembourser.
OperationIdintbodyRequisID de l'opération à rembourser.
RefundAmountdecimalbodyRequisMontant du remboursement.
OrderIdstringbodyRequisOrderId original du paymentGateway.
TransactionTrackIdstringbodyRequisTransactionTrackId original du paymentGateway.
POST{host}/api/operations/refund

Exécuter

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

ParameterTypeInRequisDescription
PhoneNumberstringbodyRequisNuméro du client.
OperationIdintbodyRequisID de l'opération à rembourser.
RefundAmountdecimalbodyRequisMontant du remboursement.
OrderIdstringbodyRequisOrderId original.
TransactionTrackIdstringbodyRequisTransactionTrackId 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.

ParameterTypeInRequisDescription
PhoneNumberstringqueryRequisNuméro de téléphone du client.
PageSizeintqueryOptionnelRésultats par page. Par défaut : 10
PageNumberintqueryOptionnelNuméro de page. Par défaut : 1
SearchstringqueryOptionnelFiltrer par mot-clé.
FromdatetimequeryOptionnelDate de création — début.
TodatetimequeryOptionnelDate 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.

ParameterTypeInRequisDescription
PhoneNumber (query)stringqueryRequisNuméro de téléphone du client (propriétaire).
NamestringbodyRequisNom du bénéficiaire. Minimum 2 lettres.
PhoneNumberstringbodyOptionnelNuméro du bénéficiaire. Format : +212*********
RibstringbodyOptionnelRIB du bénéficiaire. 24 chiffres.
EmailstringbodyOptionnelEmail 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.

ParameterTypeInRequisDescription
PhoneNumberstringqueryRequisNuméro de téléphone du client (propriétaire).
IdintrouteRequisID du bénéficiaire à modifier.
NamestringbodyRequisNom. Minimum 2 lettres.
PhoneNumberstringbodyOptionnelNuméro du bénéficiaire.
RibstringbodyOptionnelRIB. 24 chiffres.
EmailstringbodyOptionnelEmail du bénéficiaire.
DELETE{host}/api/customer/beneficiaries/{Id}

Supprimer un bénéficiaire

Supprime un bénéficiaire existant.

ParameterTypeInRequisDescription
PhoneNumberstringqueryRequisNuméro de téléphone du client.
IdintrouteRequisID 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.

ParameterTypeInRequisDescription
PhoneNumberstringqueryRequisNuméro de téléphone du client.
PageSizeintqueryOptionnelRésultats par page. Par défaut : 10
PageNumberintqueryOptionnelNumé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.).
GET{host}/api/customers/tokenized/cards/{id}

Carte par ID

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

ParameterTypeInRequisDescription
PhoneNumberstringqueryRequisNuméro de téléphone du client.
IdintrouteRequisID de la carte.
POST{host}/api/customers/tokenized/cards

Ajouter une carte

Enregistre (tokenise) une nouvelle carte bancaire pour un client.

ParameterTypeInRequisDescription
PhoneNumberstringqueryRequisNuméro de téléphone du client.
FirstNamestringbodyRequisPrénom du titulaire de la carte.
LastNamestringbodyRequisNom du titulaire de la carte.
PanstringbodyRequisNuméro complet de la carte (PAN).
ExpiryDatestringbodyRequisDate d'expiration au format YYMM (ex: 3005).
CvvstringbodyRequisCode de vérification (CVV/CVC).
CardNamestringbodyOptionnelNom personnalisé de la carte (alias).

Notes

  • •Le PAN (numéro de carte) sera stocké de manière sécurisée et tokenisé.
  • •Utilisez la carte de test sandbox pour les tests (voir la section Carte de test).
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.

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.

ParameterTypeInRequisDescription
CodestringqueryRequisCode de l'agent.
PageSizeintqueryOptionnelRésultats par page. Par défaut : 10
PageNumberintqueryOptionnelNuméro de page. Par défaut : 1
FromdatetimequeryOptionnelCréation de l'agent — date début.
TodatetimequeryOptionnelCré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.

ParameterTypeInRequisDescription
CodestringrouteRequisCode de l'agent.
POST{host}/api/agents/retail

Ajouter un agent

Ajoute un nouvel agent détaillant.

ParameterTypeInRequisDescription
PhoneNumberstringbodyRequisNuméro de téléphone de l'agent. Format : +212*********
NamestringbodyRequisNom commercial de l'agent.
FirstNamestringbodyRequisPrénom. Minimum 2 lettres.
LastNamestringbodyRequisNom de famille. Minimum 2 lettres.
CinstringbodyRequisNuméro de pièce d'identité.
AddressstringbodyOptionnelAdresse de l'agent.
EmailstringbodyOptionnelEmail 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.

ParameterTypeInRequisDescription
ReferencestringqueryRequisRéférence unique de l'opération.

Notes

  • •type : 1 = CashIn, 2 = CashOut
  • •status : 1 = open, 2 = completed, 3 = failed
POST{host}/api/agents/operations/cashin

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.

ParameterTypeInRequisDescription
CodestringbodyRequisCode de l'agent.
ReferencestringbodyRequisRéférence de l'opération.
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.

ParameterTypeInRequisDescription
ReferencestringqueryRequisRéférence unique de l'opération.
POST{host}/api/agents/operations/cashout

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.

ParameterTypeInRequisDescription
CodestringbodyRequisCode de l'agent.
ReferencestringbodyRequisRéférence de l'opération.
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.

ParameterTypeInRequisDescription
CodestringqueryRequisCode de l'agent principal.
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.

Requête HTTP

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

En-têtes

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

Réponse attendue : 200 OK sous 5 secondes (corps vide). Tout code non-2xx déclenche un retry.

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

PropertyTypeRequisDescription
WebhookIdstringRequisIdentifiant du webhook.
EventIdstringRequisType d'événement. Ex : bank-transfer.initiated
CRequestIdstringRequisIdentifiant de traçage reçu du partenaire.
OperationIdintRequisID de l'opération exécutée (peut être 0 si aucune opération créée).
TransactionIdintOptionnelID de la transaction principale.
OperationTypeintRequisCode du type d'opération (voir Types).
OperationStatusintRequis1 = Open, 2 = Completed, 3 = Failed
CreatedAtdateRequisDate de début du processus.
AmountdecimalRequisMontant de l'opération.
FeeAmountdecimalRequisMontant des frais.
PrimaryAccountNumberstringRequisNuméro de téléphone de l'émetteur.
SecondaryAccountNumberstringOptionnelNuméro de téléphone du destinataire.
MethodstringOptionnelMéthode : Card / Agent / Network
CustomDatastringOptionnelDonnées personnalisées du partenaire (max 128 caractères).
GatewayTrackIdstringOptionnelGateway Transaction Track Id.
GatewayOrderIdstringOptionnelGateway Transaction Order Id.
GatewayReferenceIdstringOptionnelGateway Transaction Reference Id.
BankTransferBeneficiaryNamestringOptionnelNom du bénéficiaire pour les virements bancaires.
NetworkNamestringOptionnelNom du réseau pour les opérations réseau.
ReferencestringOptionnelRé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 IDDescription
customer.kycProcessus KYC démarré
customer.level.updatedNiveau de compte client mis à jour
operation.createdOpération créée (en attente)
operation.updatedChangement de statut d'opération
cashin.card.authorizedCashIn par carte accepté
payment.card.authorizedPaiement par carte accepté
bank-transfer.initiatedVirement bancaire envoyé
bank-transfer.completedVirement bancaire réglé
bank-transfer.failedVirement bancaire rejeté/retourné
bank-transfer.receivedVirement bancaire reçu
transfer.receivedTransfert reçu
cashin.network.executedCashIn par référence exécuté
cashout.network.executedCashOut par référence exécuté

Exemple de body d'événement

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

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.

T

Types et références

Types d'opérations

IDCode
1CASHIN
2CASHOUT
3TRANSFER
4DEPOSIT
5PAYMENT_PUSH
6PAYMENT_PULL
7PAYMENT_REFUND
8ALIMENTATION_AGENT
9BANK_TRANSFER
10MOBILE_TOP_UP
12CHARGEBACK
24PAYMENT_CARD

Types de transactions

IDCode
1CASHIN
2CASHOUT
3TRANSFER
5PAYMENT_PUSH
6TRANSACTION_FEES
7PAYMENT_REFUND
9CHARGEBACK
10CHARGEBACK_CANCELLATION
16BANK_TRANSFER
18CASHBACK

Statuts de transaction

IDCodeDescription
1PENDINGEn attente
2COMPLETEDTerminée
3FAILEDÉchouée
4CANCELLEDAnnulée

Direction de transaction (Sens)

IDCodeDescription
1CREDITCrédit (entrée de fonds)
2DEBITDébit (sortie de fonds)

Statuts client

IDCodeDescription
0NOT_EXISTSLe numéro n'existe pas chez ChariMoney
1NOT_CONFIRMEDExiste mais non confirmé (OTP non saisi)
2CONFIRMEDConfirmé et inscrit au Switch
3ACTIVEInscrit, actif et PIN créé
4LOCKED_TEMPORARYTemporairement bloqué (tentatives excessives)
5LOCKEDBloqué

Niveaux de compte

IDCodeDescription
1BASICNiveau de base — inscription sans KYC
2KYC_LEVEL_2Niveau 2 — vérification ShareID (document + selfie)
3KYC_LEVEL_3Niveau 3 — vérification avancée
4KYC_LEVEL_4Niveau 4 — vérification complète

Types de documents

IDCodeDescription
1IdentityCardCarte d'identité nationale
2DrivingLicensePermis de conduire
3PassportPasseport
4ResidencePermitCarte de séjour
5ProofOfIncomeJustificatif de revenus
6ProofOfResidenceJustificatif de domicile
7SelfieSelfie / Photo de visage
8CommercialRegisterRegistre de commerce
C

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

CodeMessageEndpoints associés
10001Paramètres manquants.

20xxxClient

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

26xxxPIN / Authentification

CodeMessageEndpoints associés
26001Le PIN saisi est incorrect.
26004Un PIN a déjà été défini pour ce wallet.
26005Le PIN fourni ne respecte pas le format requis (doit être un nombre à 4 chiffres).

27xxxBénéficiaire

CodeMessageEndpoints associés
27000Le bénéficiaire existe déjà avec le même numéro de téléphone.
27001Le bénéficiaire n'existe pas.

32xxxKYC / Mise à niveau

CodeMessageEndpoints associés
32000Une demande de mise à niveau est déjà en cours d'examen pour ce compte.
I

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.

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. 1
    Demander les clés API

    Contactez le support pour recevoir vos clés dédiées sandbox et production.

  2. 2
    Soumettre les IP/domaines

    Fournissez la liste des IP publiques ou domaines pour le whitelisting.

  3. 3
    Tester en sandbox

    Effectuez tous vos tests d'intégration dans l'environnement sandbox.

  4. 4
    Passer en production

    Une fois approuvé, basculez vers la production avec votre clé API live.