Documentation API

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

Démarrage rapide

Version 2.3 · Dernière mise à jour 29 juillet 2026

Bienvenue dans la documentation officielle de l'API d'infrastructure fintech ChariBaaS 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

Cliquer pour copier

CVV

Cliquer pour copier

Expiration

Cliquer pour copier — API: 2608 (ou toute date future)

Code 3DS

Cliquer pour copier

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

Référence interactive (Swagger UI)

Explorez les 114 opérations et leurs schémas dans Swagger UI, hébergé sur ce site et généré depuis l'API de production.

Ouvrir la référence

Spécification OpenAPI (Swagger)

Spécification OpenAPI 3.0 de l'API partenaire, générée depuis l'API de production : 114 opérations partenaires, schémas complets, prête pour Swagger UI, Postman ou la génération de clients.

Télécharger l'OpenAPI

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

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.

v2.1

2026-06-19

Ajout de trois nouveaux modules : Recharge Telco (catalogue + recharge), Vouchers (catalogue, marques, achat prévisualisation/confirmation) et Paiement de factures (réseau Fatourati : créanciers, créances, formulaire dynamique, impayés, confirmation, + webhooks). Ajout de l'endpoint CashIn dédié Fatourati et du type d'opération 23 = VOUCHER.

v2.2

2026-06-24

Documentation des pièces KYB requises pour la création d'un wallet marchand, par type de client professionnel (personne morale, professionnel individuel, fondation / association) — ajoutées en notes sur l'endpoint « Upload documents marchand ».

v2.3

2026-07-29

Alignement sur l'API de production, à périmètre partenaire constant. Nouveautés : cycle de vie du paiement marchand par carte (capture, annulation d'autorisation, remboursement), statut de paiement QR par référence, cartes tokenisées côté agent, et extensions factures (favoris, historique, reçus, prévisualisation, statut de référence), telco (recharge client, historique, catalogue, export) et vouchers (catalogue local, produits). Routes réalignées : /api/fatourati/* → /api/bills/*, recharge B2B déplacée, transactions cartes via /api/card-transactions, aperçu paiement carte, agent principal par code (path), upgrade de compte en PUT. Actions de carte éclatées en 5 endpoints dédiés. Endpoints disparus retirés (recherche par C-Request-Id, programme de carte par Id). Paramètres de 19 fiches réalignés sur la production. Spécification OpenAPI et collection Postman téléchargeables, régénérées depuis l'API de production ; pack LLM v2.3.

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 ChariBaaS.
Webhook	Callback HTTP automatisé envoyé par le système pour notifier les partenaires des mises à jour d'opération ou de transaction.

Guides d'intégration

Parcours pas-à-pas par cas d'usage, composés des endpoints documentés ci-dessous : de l'onboarding sandbox jusqu'au cycle de paiement marchand complet.

Démarrer en sandbox : accès, activations, premiers appels

Tout ce qu'il faut obtenir et vérifier AVANT d'intégrer : clé API, modules activés pour votre compte, float de test. Suivre ce guide évite les faux blocages les plus fréquents (404 sur module non activé, catalogues vides, wallets introuvables).

Prérequis

•Un contact avec l'équipe Chari (le formulaire d'intégration technique vous est remis à l'ouverture du dossier).

1
Obtenir l'accès sandbox
Remplissez le formulaire « Obtenir un accès sandbox » tout en bas de cette page (lien direct : #sandbox-access). Vous recevez en retour : votre clé API sandbox (transmise via un lien sécurisé à usage unique) et une invitation au Partner Back Office. La base URL sandbox est https://sandbox.charimoney.com ; l'URL de production est communiquée après validation de vos tests.
2
Valider la clé : premier appel
Toutes les requêtes portent l'en-tête Chari-Api-Key (obligatoire) et idéalement un C-Request-Id unique (UUID v4) pour le traçage. Testez votre clé avec un appel sans précondition :
bash
```
curl -X 'GET' \
  'https://sandbox.charimoney.com/api/customers/status?phoneNumber=+2126xxxxxxxx' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID'
```
Réponse
json
```
{
  "data": {
    "status": 0,
    "message": "Not exists"
  }
}
```
check-status-chari
3
Faire activer les modules nécessaires
Certains modules sont activés par l'équipe Chari pour votre compte partenaire, sur demande : recharge telco, paiement de factures, vouchers (catalogue provisionné en sandbox), passerelle carte, et la clé webhook (X-Api-Key) pour recevoir les notifications. Les scopes de votre clé API délimitent aussi les endpoints accessibles. Demandez les activations correspondant à vos cas d'usage dès l'ouverture du compte — les symptômes d'un module non activé sont listés ci-dessous.
Erreur métier — Recharge telco : service non activé pour votre compte — demandez l'activation des opérateurs.
200/204 vide — Catalogue vouchers vide : les marques doivent être provisionnées en sandbox par Chari.
403 — missing scopes — l'endpoint exige un scope que votre clé n'a pas (ex. operations:admin-read sur GET /api/operations/all).
4
Demander du float de test
Pour exécuter des opérations débitrices (transferts, paiements de factures, recharges, vouchers), votre agent principal doit être approvisionné. Communiquez à votre contact Chari le code de votre agent principal (et l'identifiant partenaire) pour créditer un float de test en sandbox.
get-principal-agent
5
Utiliser la carte de test (3D Secure)
Les dépôts et paiements par carte en sandbox utilisent la carte de test documentée en tête de cette page : PAN 4918914107195005, CVV 123, expiration 08/26 (ou toute date future), code 3DS 555.
6
Outiller votre intégration
Téléchargez depuis cette page la spécification OpenAPI (générée depuis la production), la collection Postman (114 requêtes prêtes, variables {{host}} et {{apiKey}}) et le pack LLM si vous travaillez avec des assistants IA. Ils sont strictement alignés sur cette documentation.
7
Préparer le passage en production
Une fois vos tests sandbox validés : fournissez la liste de vos IP publiques ou domaines pour le whitelisting, puis recevez votre clé API de production et la base URL live. Les clés sont propres à chaque environnement — ne réutilisez jamais la clé sandbox en production.

Créer et activer un wallet client de bout en bout

Le parcours complet d'un M-Wallet client : vérifier le statut du numéro, inscrire le client (walletType), confirmer l'OTP (avec ou sans autoActivate), créer le PIN, contrôler le login, puis consulter le solde et le profil. Chaque étape liste les codes d'erreur typiques documentés (ex. 20005 utilisateur introuvable, 26005 format de PIN invalide).

Prérequis

•Une clé API sandbox valide et les en-têtes Chari-Api-Key + C-Request-Id sur chaque requête (voir le guide « Démarrer en sandbox »).
•Un numéro de test marocain au format +212********* pas encore inscrit (statut 0 attendu à l'étape 1).

1
Vérifier le statut du numéro
Avant toute inscription, interrogez le statut du numéro auprès de Chari. La réponse renvoie un statut de 0 à 5 : 0 Not exists (le numéro n'existe pas chez ChariMoney), 1 Not confirmed (OTP non saisi), 2 Confirmed (enregistré auprès de Switch), 3 Active (PIN créé), 4 Locked temporary (tentatives dépassées), 5 Locked. Pour un nouveau client, attendez-vous à 0 :
bash
```
curl -X 'GET' \
  'https://sandbox.charimoney.com/api/customers/status?phoneNumber=+2126xxxxxxxx' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID'
```
Réponse
json
```
{
  "data": {
    "status": 0,
    "message": "Not exists"
  }
}
```
check-status-chari
20005 — L'utilisateur spécifié est introuvable.
2
Inscrire le client (walletType)
Lancez l'inscription avec le numéro, le prénom et le nom (minimum 2 lettres, caractères latins uniquement), le cin (minimum 5 caractères) et le walletType : "P" pour un particulier, "C" pour un commerçant. Un OTP est envoyé par SMS au client et l'API répond 202. Optionnel : closeLoopOnly à true inscrit le client uniquement en mode CloseLoop — dans ce cas l'OTP est envoyé directement par CHARI.
bash
```
curl --location 'https://sandbox.charimoney.com/api/customers/register' \
  --header 'Chari-Api-Key: YOUR_API_KEY' \
  --header 'C-Request-Id: YOUR_REQUEST_ID' \
  --header 'Content-Type: application/json' \
  --data '{
    "phoneNumber": "+2126xxxxxxxx",
    "firstName": "Mohammed",
    "lastName": "Chairi",
    "cin": "K000000",
    "walletType": "P"
  }'
```
Réponse
json
```
{
  "data": true
}
```
register
20000 — Le format du numéro de téléphone est invalide (attendu : +212*********).
20006 — Les paramètres initiaux fournis sont incorrects ou invalides.
20008 — L'inscription est temporairement verrouillée pour des raisons de sécurité.
20009 — La demande est en attente de confirmation. Veuillez patienter.
3
Confirmer l'OTP (autoActivate)
Confirmez l'inscription en soumettant le code OTP reçu par SMS (format xxx-xxx). Le champ optionnel autoActivate (défaut : false) décide de la suite : si false, l'utilisateur doit terminer l'activation en définissant un PIN (étape suivante) ; si true, le wallet est activé automatiquement, sans PIN. Ne renvoyez pas walletType ici : le type de wallet se définit à l'inscription. Si le client n'a pas reçu le code, renvoyez-le via POST /api/customers/confirm/resend-otp.
bash
```
curl --location 'https://sandbox.charimoney.com/api/customers/confirm' \
  --header 'Chari-Api-Key: YOUR_API_KEY' \
  --header 'C-Request-Id: YOUR_REQUEST_ID' \
  --header 'Content-Type: application/json' \
  --data '{
    "phoneNumber": "+2126xxxxxxxx",
    "code": "365-768"
  }'
```
Réponse
json
```
{
  "data": true
}
```
confirm resend-otp
20000 — Le format du numéro de téléphone est invalide.
20017 — Aucune demande en attente n'est associée au numéro fourni — refaites l'étape Register.
4
Créer le PIN pour activer le wallet
Si vous n'avez pas utilisé autoActivate, définissez le PIN du client (4 chiffres obligatoires) pour finaliser l'activation. Une fois le PIN créé, le statut du numéro (étape 1) passe à 3 : Active — enregistré auprès de Switch et actif chez ChariMoney.
bash
```
curl -X 'POST' \
  'https://sandbox.charimoney.com/api/customers/pin' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID' \
  -H 'Content-Type: application/json' \
  -d '{
    "phoneNumber": "+2126xxxxxxxx",
    "pin": "0000"
  }'
```
Réponse
json
```
{
  "data": true
}
```
create-pin
26004 — Un PIN a déjà été défini pour ce wallet — utilisez Update PIN ou Reset PIN.
26005 — Le PIN fourni ne respecte pas le format requis (doit être un nombre à 4 chiffres).
5
Contrôler le login par PIN
Authentifiez le client avec son PIN pour valider l'activation. La réponse indique logged (true si l'authentification a réussi) et remainingAttempts (nombre de tentatives restantes avant le verrouillage du compte).
bash
```
curl -X 'POST' \
  'https://sandbox.charimoney.com/api/customers/login' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID' \
  -H 'Content-Type: application/json' \
  -d '{
    "phoneNumber": "+2126xxxxxxxx",
    "pin": "0000"
  }'
```
Réponse
json
```
{
  "data": {
    "logged": true,
    "remainingAttempts": 5
  }
}
```
login-pin
20005 — L'utilisateur spécifié est introuvable — vérifiez le numéro et le statut (étape 1).
26001 — Le PIN saisi est incorrect — surveillez remainingAttempts pour éviter le verrouillage.
6
Consulter le solde du wallet
Le wallet activé se consulte par numéro de téléphone : la réponse renvoie le solde actuel (balance) du wallet du client inscrit.
bash
```
curl -X 'GET' \
  'https://sandbox.charimoney.com/api/customers/balance?phoneNumber=+2126xxxxxxxx' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID'
```
Réponse
json
```
{
  "data": {
    "balance": 174.0
  }
}
```
get-balance
20005 — L'utilisateur spécifié est introuvable.

Récupérer le profil complet du client

Pour aller plus loin, récupérez le profil détaillé du client : identité, solde, rib associé au wallet, accountLevel (niveau KYC de 1 à 4 — voir la table « Niveaux de compte »), customerStatus (mêmes valeurs que le statut de l'étape 1) et informations du partenaire associé.

bash

curl -X 'GET' \
  'https://sandbox.charimoney.com/api/customers/info?phoneNumber=+2126xxxxxxxx' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID'

Réponse

json

{
  "data": {
    "id": 72,
    "fullName": "Mohammed Chairi",
    "firstName": "Mohammed",
    "lastName": "Chairi",
    "phoneNumber": "+2126xxxxxxxx",
    "balance": 78,
    "accountType": 2,
    "rib": "82764000001000000000xxxx",
    "accountLevel": 1,
    "customerStatus": 3,
    "partnerId": 1
  }
}

get-customer-info

20005 — L'utilisateur spécifié est introuvable.

Dépôt par carte avec 3D Secure : du preview au webhook

Créditez le wallet d'un client depuis une carte bancaire : aperçu des frais, exécution avec la carte de test sandbox, authentification 3D Secure, notification webhook cashin.card.authorized — puis les variantes agent et carte tokenisée.

Prérequis

•Une clé API sandbox active (voir le guide « Démarrer en sandbox »).
•Un client enregistré en sandbox : le dépôt crédite le wallet associé à son numéro de téléphone.
•Pour recevoir les notifications : un endpoint HTTPS et la clé webhook X-Api-Key que vous fournissez à Chari.

Prévisualiser le dépôt

Avant tout débit, vérifiez la faisabilité du dépôt et obtenez les frais (feesAmount) avec l'endpoint preview. Le numéro de téléphone du client passe en query (format +212*********), le montant dans le corps :

bash

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

Réponse

json

{
  "data": {
    "type": 1,
    "operation": {
      "phoneNumber": "+2126xxxxxxxx",
      "amount": 100,
      "method": 2,
      "acceptedBy": 0,
      "description": ""
    },
    "feesAmount": 0,
    "checkedAt": "2025-04-12T12:55:39.213Z",
    "openLoop": false
  }
}

cashin-card-preview

401 — Identifiants d'authentification (API KEY) non autorisés — vérifiez l'en-tête Chari-Api-Key.

10001 — Missing Parameters — un paramètre requis manque (ex. phoneNumber en query ou amount dans le corps).

Exécuter avec la carte de test sandbox

Exécutez le dépôt avec la carte de test sandbox : PAN 4918914107195005, CVV 123, expiration 08/26 (ou toute date future) — soit "2608" au format YYMM attendu par expiryDate. keepAlive: true sauvegarde (tokenise) la carte pour la dernière étape ; 3D Secure est activé par défaut. La réponse indique si une redirection 3DS est nécessaire (redirect) et fournit redirectionURL :

bash

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

Réponse

json

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

cashin-card-execute

3
Compléter l'authentification 3D Secure
Si redirect = true, ouvrez redirectionURL dans un navigateur et saisissez le code 3DS de la carte de test : 555. Après l'authentification, l'utilisateur est redirigé vers acceptURL ou declineURL ; l'URL de redirection contient RESPONSE_CODE (0 = succès, toute autre valeur = échec) et REASON_CODE (raison lisible du résultat, ex. SUCCESS, DECLINED). Validez RESPONSE_CODE et REASON_CODE pour déterminer la suite dans votre application.
cashin-card-execute
4
Recevoir le webhook cashin.card.authorized
Quand le CashIn par carte est accepté, Chari notifie votre endpoint avec l'événement cashin.card.authorized (POST JSON, en-têtes C-Webhook-Id et X-Api-Key). Le champ CRequestId reprend l'identifiant de traçage reçu du partenaire, OperationType 1 = CASHIN, OperationStatus 2 = Completed, Method = Card, et les champs GatewayTrackId / GatewayOrderId / GatewayReferenceId identifient la transaction côté passerelle. Répondez 200 OK sous 5 secondes (corps vide) — tout code non-2xx déclenche un retry (1 min, 5 min, 30 min, 60 min, puis toutes les 6h jusqu'à 72h au total).
Réponse
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"
  }
}
```

Vérifier l'opération

Avec l'OperationId du webhook, récupérez le détail de l'opération : operationType 1 = CASHIN et transactionStatus 2 = COMPLETED (voir la table « Types et références »). totalAmount est le montant après application des frais et commissions.

bash

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

Réponse

json

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

get-operation-by-id

Variante agent : créditer le wallet d'un agent

Le même flux existe côté agent : les endpoints /api/operations/cashin/card/agent/preview et /api/operations/cashin/card/agent prennent en query le paramètre code (code de l'agent dont le wallet est crédité) au lieu de phoneNumber. Le corps d'exécution est identique (même carte de test) et le flux 3D Secure est le même :

bash

curl -X 'POST' \
  'https://sandbox.charimoney.com/api/operations/cashin/card/agent/preview?code=21011' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID' \
  -H 'Content-Type: application/json' \
  -d '{ "amount": 100 }'

Réponse

json

{
  "data": {
    "type": 1,
    "operation": {
      "code": "21011",
      "phoneNumber": "+2126xxxxxxxx",
      "amount": 100,
      "method": 2
    },
    "feesAmount": 0,
    "checkedAt": "2025-04-12T12:55:39.213Z",
    "openLoop": false
  }
}

cashin-card-agent-preview cashin-card-agent-execute

Rejouer le dépôt avec la carte tokenisée

Si keepAlive était true à l'exécution, la carte est sauvegardée (tokenisée). Récupérez son customerBankCardId via GET /api/customers/tokenized/cards?phoneNumber=…, puis rejouez un dépôt avec seulement le CVV et le montant — le PAN n'est plus transmis :

bash

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

Réponse

json

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

cashin-card-saved get-tokenized-cards

Paiement marchand par carte : du preview au remboursement

Le cycle de vie complet du paiement carte (Card to Wallet) : vérifier la faisabilité, encaisser avec 3D Secure, choisir entre capture automatique et flux autorisation → capture/annulation, rembourser, puis réutiliser une carte tokenisée. Chaque étape s'appuie sur les identifiants orderId et transactionTrackId retournés par le paiement.

Prérequis

•Une clé API sandbox valide et la passerelle carte activée pour votre compte (voir le guide « Démarrer en sandbox »).
•Le numéro de téléphone du wallet marchand encaisseur, au format +212*********.
•La carte de test sandbox : PAN 4918914107195005, CVV 123, expiration 08/26, code 3DS 555.

1
Prévisualiser le paiement (frais, faisabilité)
Avant d'encaisser, vérifiez la faisabilité du paiement carte vers le marchand. Le numéro du marchand passe en query string, le montant dans le corps. La réponse retourne le type d'opération, les frais (feesAmount) et l'horodatage de vérification.
bash
```
curl -X 'POST' \
  'https://sandbox.charimoney.com/api/operations/merchant/payment/card/preview?phoneNumber=+2126xxxxxxxx' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID' \
  -H 'Content-Type: application/json' \
  -d '{ "amount": 250 }'
```
Réponse
json
```
{
  "data": {
    "type": 5,
    "operation": {
      "phoneNumber": "+2126xxxxxxxx",
      "amount": 250,
      "method": 2
    },
    "feesAmount": 0,
    "checkedAt": "2025-04-12T12:55:39.213Z",
    "openLoop": false
  }
}
```
merchant-card-preview
401 — Clé API non autorisée — vérifiez l'en-tête Chari-Api-Key.
10001 — Missing Parameters — un paramètre requis manque (ex. amount dans le corps).
20005 — L'utilisateur spécifié est introuvable — vérifiez le numéro du marchand (format +212*********).

Premier encaissement : exécuter avec autoCapture

Exécutez le paiement avec la carte de test (expiryDate au format YYMM : 2608). Avec autoCapture = true, le paiement est capturé automatiquement. keepAlive = true tokenise la carte pour la réutiliser plus tard (étape 7). Flux 3DS : la réponse fournit redirectionURL à ouvrir (redirect = true) ; saisissez-y le code 3DS 555. Conservez orderId et transactionTrackId — toute la suite du cycle de vie en dépend.

bash

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

Réponse

json

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

merchant-card-execute

3
Valider le retour 3D Secure
Après l'authentification 3D Secure, l'utilisateur est redirigé vers acceptUrl ou declineUrl selon le résultat. L'URL de retour inclut RESPONSE_CODE (0 = succès, autre = échec), REASON_CODE (raison lisible : SUCCESS, DECLINED…) et OPERATION (ex. PAYMENT) : validez-les à la réception. L'URL notificationUrl est par ailleurs notifiée en fin de transaction (succès/échec), et l'événement webhook payment.card.authorized signale un paiement par carte accepté.
merchant-card-execute

Paiement en deux temps : autoriser puis capturer

Pour dissocier autorisation et débit, exécutez le paiement (étape 2) avec autoCapture = false : les fonds sont autorisés sans être débités. Finalisez ensuite avec la capture, en ciblant la transaction via orderId et transactionTrackId retournés par le paiement. Flux type : paiement carte avec AutoCapture = false → autorisation → capture (cet endpoint) ou annulation (reverse). Scope requis : operations:merchant-payment.

bash

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

Réponse

json

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

merchant-card-capture

Annuler une autorisation non capturée (reverse)

Si la commande est abandonnée avant capture, annulez l'autorisation : les fonds autorisés sont libérés sans être débités. Le corps de requête est identique à celui de la capture — ciblez la transaction via orderId et transactionTrackId. Le reversal s'applique à une autorisation non capturée ; pour un paiement déjà capturé, utilisez l'endpoint Refund (étape suivante).

bash

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

Réponse

json

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

merchant-card-reverse

Rembourser un paiement capturé (total ou partiel)

Un paiement déjà capturé se rembourse via l'endpoint Refund, identifié par operationId. Un RefundAmount inférieur au montant capturé effectue un remboursement partiel. Attention au scope : operations:refund, différent du scope operations:merchant-payment des autres endpoints carte.

bash

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

Réponse

json

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

merchant-card-refund

Réencaisser avec la carte tokenisée

La carte tokenisée à l'étape 2 (keepAlive = true) se réutilise via son cardId en path : seul le CVV est requis dans le corps, avec le montant. La réponse a la même structure que le paiement carte classique — même gestion du flux 3DS (redirectionURL, retour RESPONSE_CODE / REASON_CODE / OPERATION), mêmes orderId et transactionTrackId pour la suite du cycle de vie.

bash

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

Réponse

json

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

merchant-card-tokenized-execute

8
Aller plus loin : statut d'un QR Code marchand
Si vos marchands encaissent aussi par QR Code, vérifiez le statut d'un QR Code marchand à partir de sa référence : la réponse retourne le contenu du QR (qrContent, payload encodé à afficher/scanner) et sa référence (qrCodeReference). Pour les transactions carte, le suivi par orderId reste l'endpoint Statut ChariPay de l'étape 3.
bash
```
curl -X 'GET' \
  'https://sandbox.charimoney.com/api/operations/merchant/qrcode/status?reference=1122334455' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID'
```
Réponse
json
```
{
  "data": {
    "qrContent": "00020101021126xxxxxx",
    "qrCodeReference": "1122334455"
  }
}
```
merchant-qrcode-status

Cash-in / cash-out par référence : de la demande à l'exécution

Le flux par référence en trois temps : votre application crée une demande de CashIn ou de CashOut qui génère une référence unique à durée de validité limitée ; le client la communique à un agent ; l'agent consulte puis exécute l'opération. Ce guide déroule le parcours complet en sandbox, y compris l'exécution réseau simulée et la variante Fatourati.

Prérequis

•Une clé API sandbox valide (voir le guide « Démarrer en sandbox »).
•Pour l'étape d'exécution : le code d'un agent effectuant l'opération.
•Pour recevoir les notifications : votre endpoint webhook et la clé X-Api-Key fournie à Chari.

1
Créer la demande de CashIn
La demande de CashIn génère une référence unique avec une durée de validité limitée ; cette référence sera ensuite utilisée par un agent pour exécuter l'opération. Le corps porte deux champs obligatoires : PhoneNumber (numéro du client) et Amount (montant du CashIn). La réponse revient avec operationStatus 1 (open) — les valeurs possibles sont 1 = open, 2 = completed, 3 = failed, 4 = canceled, et operationType vaut 1 pour un CashIn, 2 pour un CashOut.
bash
```
curl -X 'POST' \
  'https://sandbox.charimoney.com/api/operations/cashin/request' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID' \
  -H 'Content-Type: application/json' \
  -d '{
    "PhoneNumber": "+2126xxxxxxxx",
    "amount": 10
  }'
```
Réponse
json
```
{
  "data": {
    "createdAt": "2025-05-15T23:55:55.082Z",
    "closedAt": null,
    "reference": "1122334455",
    "phoneNumber": "+2126xxxxxxxx",
    "operationType": 1,
    "operationStatus": 1,
    "amount": 10
  }
}
```
request-cashin
10001 — Missing Parameters — un champ obligatoire (PhoneNumber, Amount) manque dans le corps.
401 — Identifiants d'authentification (API KEY) non autorisés — vérifiez l'en-tête Chari-Api-Key.
2
Consulter la demande par sa référence
Le client communique la référence à l'agent. Avant d'exécuter, l'agent (ou votre back-office) peut récupérer les détails de la demande — montant, statut — via la même route en GET, avec la référence en paramètre de requête. Tant que l'opération n'est pas exécutée, executedAt reste null et status vaut 1 (open).
bash
```
curl -X 'GET' \
  'https://sandbox.charimoney.com/api/operations/cashin/request?reference=1122334455' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID'
```
Réponse
json
```
{
  "data": {
    "reference": "1122334455",
    "createdAt": "2025-05-15T23:55:55.082Z",
    "executedAt": null,
    "phoneNumber": "+2126xxxxxxxx",
    "amount": 10,
    "partner": "ChariMoney",
    "status": 1,
    "type": 1
  }
}
```
get-cashin-reference

Exécuter le CashIn côté agent

L'agent exécute l'opération en utilisant la référence générée pour le client : le corps porte code (code de l'agent effectuant l'opération) et reference. C'est l'étape qui matérialise le dépôt d'espèces.

bash

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

Réponse

json

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

execute-cashin-reference

Dérouler le CashOut symétrique

Le retrait d'espèces suit exactement le même schéma en trois temps sur les routes cashout : POST /api/operations/cashout/request (PhoneNumber + Amount) génère la référence, GET /api/operations/cashout/request?reference=... la consulte, et POST /api/operations/cashout/agent (code + reference) l'exécute. Dans les réponses, operationType vaut 2 (CashOut).

bash

curl -X 'POST' \
  'https://sandbox.charimoney.com/api/operations/cashout/request' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID' \
  -H 'Content-Type: application/json' \
  -d '{
    "PhoneNumber": "+2126xxxxxxxx",
    "amount": 100
  }'

Réponse

json

{
  "data": {
    "createdAt": "2025-05-15T23:56:55.082Z",
    "closedAt": null,
    "reference": "1122334456",
    "phoneNumber": "+2126xxxxxxxx",
    "operationType": 2,
    "operationStatus": 1,
    "amount": 100
  }
}

request-cashout get-cashout-reference execute-cashout-reference

5
Simuler l'exécution réseau en sandbox
Les endpoints réseau exécutent un CashIn ou un CashOut par référence depuis une entité réseau (étape agent réseau). En sandbox, appelez-les vous-même pour finaliser vos parcours de test sans réseau d'agents réel : le corps porte reference (obligatoire) et entity (optionnel), et le paramètre de requête optionnel withContext retourne le résultat avec son contexte s'il existe (false par défaut). La route symétrique POST /api/network/operations/cashout exécute le CashOut.
bash
```
curl -X 'POST' \
  'https://sandbox.charimoney.com/api/network/operations/cashin' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID' \
  -H 'Content-Type: application/json' \
  -d '{
    "reference": "1122334455",
    "entity": "AGENCY"
  }'
```
Réponse
json
```
{
  "data": {
    "reference": "1122334455",
    "entity": "AGENCY",
    "createdAt": "2025-05-15T23:55:55.082Z",
    "executedAt": "2025-05-15T23:57:07.000Z",
    "phoneNumber": "+2126xxxxxxxx",
    "amount": 10,
    "description": "CashIn by reference",
    "partner": "PARTNER_NAME"
  }
}
```
simulate-cashin simulate-cashout
6
Recevoir la confirmation par webhook
L'exécution déclenche l'événement webhook cashin.network.executed (CashIn par référence exécuté) ou cashout.network.executed (CashOut par référence exécuté) vers votre endpoint HTTPS. Le corps JSON porte les champs communs (OperationId, OperationType, OperationStatus, Amount, CreatedAt, ExecutedAt...) plus, pour ces opérations réseau, Reference et NetworkName. Répondez 200 OK sous 5 secondes ; tout code non-2xx déclenche un retry (1 min, 5 min, 30 min, 60 min, puis toutes les 6h jusqu'à 72h au total).

Variante Fatourati : la demande de CashIn dédiée

Fatourati est un fournisseur spécial avec son propre flux de génération de référence (préfixe FATREF-) : utilisez la route dédiée POST /api/operations/fatourati/cashin/request au lieu de la route cashin standard — le comportement de génération et les règles d'expiration peuvent différer. Pour un agent principal, remplacez phoneNumber par le Code agent (PhoneNumber => Code) ; Description et FeesPercent sont optionnels.

bash

curl -X 'POST' \
  'https://sandbox.charimoney.com/api/operations/fatourati/cashin/request' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID' \
  -H 'Content-Type: application/json' \
  -d '{
    "code": "1880375",
    "Amount": 100,
    "FeesPercent": 1,
    "Description": "Test it"
  }'

Réponse

json

{
  "data": {
    "reference": "FATREF-E6C8ECC690AC",
    "createdAt": "2026-06-11T00:42:09.654Z",
    "executedAt": null,
    "phoneNumber": null,
    "code": "1880375",
    "amount": 100,
    "description": "Test it",
    "status": 1,
    "type": 1
  }
}

request-cashin-fatourati

Paiement de factures Fatourati : du créancier au reçu

Encaissez une facture Fatourati (RADEEMA, LYDEC, IAM, TGR…) de bout en bout : lister les créanciers, lister les créances, construire le formulaire d'identification dynamique, consulter les impayés, confirmer le paiement, puis suivre la transaction (statut, reçu, webhooks). Modèle mono-créancier ; paiement partiel supporté.

Prérequis

•Une clé API sandbox valide (en-têtes Chari-Api-Key + C-Request-Id) — voir le guide « Démarrer en sandbox ».
•Le module Paiement de factures activé pour votre compte partenaire par l'équipe Chari.
•Un utilisateur final Chari Money existant (phoneNumber au format international) et du float de test pour les opérations débitrices.

Lister les créanciers Fatourati

Récupérez la liste des créanciers actifs accessibles à votre compte (filtrée selon votre contrat et votre configuration Fatourati). Conservez le codeCreancier (4 chiffres, ≥ 1000) de chaque facturier. codeRetour : 000 = ACCEPTE (succès), 908 = problème technique Fatourati. La réponse étant relativement stable, un cache de quelques heures côté partenaire est acceptable.

bash

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

Réponse

json

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

billpay-creanciers

401 — Identifiants d'authentification (API KEY) non autorisés — vérifiez l'en-tête Chari-Api-Key.

2
Lister les créances du créancier choisi
Un créancier peut exposer plusieurs créances (une créance correspond à un type de service : facture, recharge, taxe…). Listez-les avec le creancierId obtenu à l'étape 1. Le codeCreance est toujours sur 2 positions (ex. 01). codeRetour : 000 = ACCEPTE, 104 = créancier inexistant ou inactif, 908 = problème technique.
bash
```
curl -X 'GET' \
  'https://sandbox.charimoney.com/api/bills/creances?creancierId=1002' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID'
```
Réponse
json
```
{
  "codeRetour": "000",
  "msg": "ACCEPTE",
  "nbreCreance": 2,
  "listeCreance": [
    { "codeCreance": "01", "nomCreance": "Factures Eau et Electricité" },
    { "codeCreance": "02", "nomCreance": "Frais de raccordement" }
  ]
}
```
billpay-creances

Construire le formulaire d'identification dynamique

Pour le couple (créancier, créance), récupérez le schéma des champs à afficher : libellé, type, format, taille, contraintes. Vous DEVEZ construire votre écran de saisie à partir de cette réponse (pas de formulaire codé en dur) afin de rester compatible avec les nouveaux créanciers ajoutés au réseau Fatourati. typeChamp : text, select, password, libelle — un champ libelle est un texte statique (non saisissable) qui ne doit JAMAIS être renvoyé dans creancierVals. contrainte : 0 = optionnel, 1 = obligatoire. Si refTxFatourati vaut 1 (défaut), l'étape suivante est /impayes.

bash

curl -X 'GET' \
  'https://sandbox.charimoney.com/api/bills/form?creancierId=1008&creanceId=01' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID'

Réponse

json

{
  "codeRetour": "000",
  "msg": "ACCEPTE",
  "nbreParams": 2,
  "creancierParams": [
    {
      "libelle": "Contract number",
      "nomChamp": "numeroProduit",
      "typeChamp": "text",
      "formatChamp": "2",
      "tailleMin": 8,
      "tailleMax": 12,
      "contrainte": "1"
    },
    {
      "libelle": "To find your number, check your latest bill in the top right.",
      "nomChamp": "",
      "typeChamp": "libelle",
      "formatChamp": "1",
      "tailleMin": 0,
      "tailleMax": 0,
      "contrainte": "0"
    }
  ],
  "refTxFatourati": "1"
}

billpay-form

Consulter les impayés du client

Soumettez l'identification saisie : le corps porte creancierVals, un tableau d'objets { nomChamp, valChamp } — attention, la propriété s'appelle valChamp (et non valeurChamp comme dans les réponses /form et /impayes), et les champs typeChamp=libelle ne doivent pas y figurer. Cet appel ouvre la transaction (état EN_ATTENTE) et renvoie un refTxFatourati (12 chiffres) à conserver pour /confirm ; l'association reste valide 7 jours calendaires (délai Fatourati). impayesParams liste les articles (typeArticle : 0 = créance, 1 = frais, 2 = obligatoire, 3 = timbre) ; les paramètres techniques de globalParams à libellé vide (contrPaiement, isConfTO, isAnnul, rejoue) ne doivent jamais être affichés au client. Codes clés : 107 = aucune créance à payer, 109 = champ requis manquant.

bash

curl -X 'POST' \
  'https://sandbox.charimoney.com/api/bills/impayes?phoneNumber=%2B212670770743&creancierId=1008&creanceId=01' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID' \
  -H 'Content-Type: application/json' \
  -d '{
  "creancierVals": [
    { "nomChamp": "numeroProduit", "valChamp": "16422270229" }
  ]
}'

Réponse

json

{
  "codeRetour": "000",
  "msg": "ACCEPTE",
  "refTxFatourati": "100003141347",
  "codeDevise": "504",
  "nbreCreances": 2,
  "montantTotalTTC": "150.50",
  "globalParams": [
    { "libelle": "Customer name", "nomChamp": "nomClient", "valeurChamp": "ALERGE DE LAREDO" },
    { "libelle": "", "nomChamp": "contrPaiement", "valeurChamp": "1" }
  ],
  "impayesParams": [
    {
      "idArticle": "1005533319",
      "description": "Water bill July 2026",
      "dateFacture": "26/07/2026",
      "prixTTC": "120.16",
      "typeArticle": 0
    },
    {
      "idArticle": "1005533320",
      "description": "Water bill August 2026",
      "dateFacture": "26/08/2026",
      "prixTTC": "30.34",
      "typeArticle": 0
    }
  ]
}

billpay-impayes

10001 — Missing Parameters — un paramètre requis manque (phoneNumber, creancierId, creanceId ou le tableau creancierVals).

Confirmer le paiement (après prévisualisation)

Laissez l'utilisateur sélectionner ses articles (totalPayment : true = totalité des impayés, false = sélection partielle), puis confirmez. Le corps reprend creancierId, creanceId, le refTxFatourati de l'étape 4, listeArticleSelectionnes (objets { idArticle, prixTTC, typeArticle, dateFacture, description } issus de impayesParams), creancierVals ({ nomChamp, valChamp }) et globalParams. Vous pouvez d'abord valider ce même corps sans exécuter le paiement via POST /api/bills/preview (corps identique à /confirm). codeRetour 000 = CONFIRME (règlement effectif côté créancier) ; 301 = transaction déjà traitée (à traiter comme un succès, afficher le reçu). refReglement doit figurer sur le reçu ; numCRC / texteCRC (params) sont à afficher sur le reçu si présents.

bash

curl -X 'POST' \
  'https://sandbox.charimoney.com/api/bills/confirm?phoneNumber=%2B212670770743' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID' \
  -H 'Content-Type: application/json' \
  -d '{
  "creancierId": "1008",
  "creanceId": "01",
  "refTxFatourati": "100003141347",
  "totalPayment": false,
  "listeArticleSelectionnes": [
    { "idArticle": "1005533320", "prixTTC": "30.34", "typeArticle": 0, "dateFacture": "26/08/2026", "description": "Water bill August 2026" }
  ],
  "creancierVals": [
    { "nomChamp": "numeroProduit", "valChamp": "16422270229" }
  ],
  "globalParams": [
    { "libelle": "", "nomChamp": "contrPaiement", "valeurChamp": "1" }
  ]
}'

Réponse

json

{
  "codeRetour": "000",
  "msg": "ACCEPTE",
  "refTxFatourati": "100003141347",
  "codeAutorisation": "A1B2C3",
  "refReglement": "REGL20260512000183",
  "montantTotalTTC": "30.34",
  "codeDevise": "504",
  "params": [
    { "nomChamp": "numCRC", "valeurChamp": "0801007777" },
    { "nomChamp": "texteCRC", "valeurChamp": "For any complaint, contact LYDEC customer service." }
  ]
}

billpay-preview billpay-confirm

20005 — The specified user could not be found — phoneNumber doit correspondre à un utilisateur Chari Money existant, sinon la transaction est rejetée avant tout appel à Fatourati.

6
Suivre la transaction et délivrer le reçu
GET /api/bills/reference/status renvoie le statut d'un cash-in Fatourati à partir de sa référence : exécution, statut, montant, horodatages et chariOperationId (204 No Content si aucune transaction ne correspond ; réponse à la racine, sans enveloppe { "data": … }). Cet identifiant d'opération Chari est utilisable avec GET /api/bills/bill-receipt/{operationId}?phoneNumber=… pour télécharger le reçu — la réponse 200 contient le fichier du reçu (contenu binaire), pas un corps JSON, et le reçu doit mentionner le refReglement renvoyé par /confirm. L'historique paginé des paiements du client est disponible via GET /api/bills/history.
bash
```
curl -X 'GET' \
  'https://sandbox.charimoney.com/api/bills/reference/status?reference=1000031413470' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID'
```
Réponse
json
```
{
  "fatouratiReference": "1000031413470",
  "executed": true,
  "status": "CONFIRME",
  "created_at": "2026-07-12T10:15:23Z",
  "amount": 150.50,
  "executed_at": "2026-07-12T10:16:05Z",
  "chariOperationId": 2181
}
```
billpay-reference-status billpay-receipt billpay-history
7
Écouter les webhooks payment.*
Comportement asynchrone (canal digital) : sur /confirm, les codes 908/909/910 ne sont PAS des échecs définitifs — la transaction reste à l'état AUTORISE et sa résolution finale est notifiée par webhook. Les événements du module sont : payment.confirmed (état CONFIRME), payment.cancelled (ANNULE), payment.refunded (REMBOURSE) et payment.failed (FAILED). Les notifications arrivent en POST signé avec l'en-tête X-Api-Key (la clé secrète que vous fournissez à Chari) ; répondez 200 OK sous 5 secondes — tout code non-2xx déclenche un retry (1 min, 5 min, 30 min, 60 min, puis toutes les 6 h jusqu'à 72 h au total).
billpay-confirm

Recharge téléphonique B2B : catalogue, recharge, variante client

Rechargez un numéro mobile marocain depuis votre compte agent principal en deux appels : catalogue des offres puis exécution de la recharge. Le guide couvre ensuite la variante « client » (wallet du client débité, avec aperçu préalable) et l'historique des recharges. Opérateurs supportés : Maroc Telecom (IAM), Orange et Inwi.

Prérequis

•Une clé API sandbox valide (voir le guide « Démarrer en sandbox »).
•Le service telco activé pour votre compte partenaire par l'équipe Chari.
•Votre code agent principal (compte débité pour la recharge B2B), approvisionné en float de test.

1
Vérifier l'activation du service telco
La recharge telco est un module activé par l'équipe Chari pour votre compte partenaire, sur demande. Vous aurez aussi besoin de votre code agent principal : c'est le compte qui sera débité par la recharge B2B, communiqué par Chari après activation de votre compte partenaire. Si le service n'est pas activé, vos appels telco échouent avec une erreur métier indiquant que le service n'est pas activé pour votre compte — demandez alors l'activation des opérateurs (voir le guide « Démarrer en sandbox »).
guide-sandbox-onboarding get-principal-agent

Récupérer le catalogue des offres (B2B)

Le catalogue B2B renvoie la liste des produits de recharge disponibles pour un numéro, un montant et un opérateur donnés (1 = Maroc Telecom, 2 = Orange, 3 = Inwi). Chaque produit porte un productCode unique à utiliser lors de la recharge, et un indicateur enabled de disponibilité.

bash

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

Réponse

json

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

telco-catalog

Exécuter la recharge B2B

Initiez la recharge avec le productCode choisi dans le catalogue. Le champ code est votre code agent principal — le compte qui sera débité. rechargeType vaut 0 pour une recharge Classic (Dirhams) et 1 pour une recharge Product (pass du catalogue). La réponse porte operationType = 10 (RECHARGE, voir la table « Types et références »).

bash

curl -X 'POST' \
  'https://sandbox.charimoney.com/api/operations/service/telco/recharge/b2b' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID' \
  -H 'Content-Type: application/json' \
  -d '{
  "recipientPhoneNumber": "+21266123123",
  "amount": 10,
  "operator": 2,
  "rechargeType": 1,
  "productCode": 3,
  "code": "12003"
}'

Réponse

json

{
  "data": {
    "operationType": 10,
    "Amount": 10,
    "feesAmount": 0,
    "checkedAt": "2025-04-12T12:31:59.31347Z",
    "openLoop": false
  }
}

telco-recharge

Variante client : prévisualiser la recharge

Si la recharge est payée depuis le wallet d'un client (et non depuis votre compte agent principal), utilisez la variante « client ». Appelez d'abord l'aperçu pour vérifier la faisabilité, le montant et les frais avant exécution : customerPhoneNumber est le wallet débité, recipientPhoneNumber le numéro rechargé. La réponse renvoie feesAmount et totalAmount (amount + fees).

bash

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

Réponse

json

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

telco-recharge-preview

Variante client : exécuter la recharge

Une fois l'aperçu validé, exécutez la recharge avec le même corps : le wallet du client (customerPhoneNumber) est débité — à distinguer de la variante /b2b qui débite le compte agent principal. Pour une recharge de type Product, ajoutez le productCode fourni par le catalogue.

bash

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

Réponse

json

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

telco-recharge-client

Consulter l'historique des recharges d'un client

Récupérez la liste des opérations de recharge d'un client avec pagination (pageSize/pageNumber) et filtre par statut. Le paramètre status (enum swagger : 0 à 4) est répétable pour filtrer sur plusieurs statuts, ex. status=2&status=3. La réponse est une liste d'opérations, sans enveloppe de pagination.

bash

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

Réponse

json

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

telco-recharge-history

7
Gérer les erreurs
Les erreurs suivent les codes HTTP standards ; une 400 Bad Request porte un code d'erreur Chari spécifique dans le corps ({ "errorCode": ..., "errorDescription": "..." }). Incluez un C-Request-Id unique (UUID v4) dans chaque requête : il est renvoyé dans la réponse et facilite le traçage avec le support.
401 Unauthorized — Identifiants d'authentification (API KEY) non autorisés — vérifiez l'en-tête Chari-Api-Key et l'environnement (les clés sont propres à chaque environnement).
10001 — Missing Parameters — un champ obligatoire du corps manque (ex. code, productCode ou rechargeType sur la recharge B2B).

Vendre des vouchers : marques, articles, prévisualisation, code

Le parcours complet de vente d'un voucher numérique (carte cadeau, recharge de jeu…) : parcourir les marques, choisir un article, prévisualiser le montant et les frais, puis confirmer l'achat pour obtenir le code à remettre au bénéficiaire. Le flux d'achat suit un modèle prévisualisation/confirmation ; le type d'opération est 23 (VOUCHER).

Prérequis

•Une clé API sandbox valide (voir le guide « Démarrer en sandbox »).
•Le module vouchers activé pour votre compte, avec un catalogue provisionné en sandbox par Chari — sinon les listes de marques et d'articles reviennent vides.
•Un agent principal approvisionné en float de test pour exécuter les opérations débitrices.

1
Vérifier le provisioning du catalogue
Les marques de vouchers doivent être provisionnées en sandbox par Chari pour votre compte : un catalogue vide n'est pas un bug d'intégration mais un module non provisionné — demandez l'activation à votre contact Chari. De même, la confirmation d'achat est une opération débitrice : votre agent principal doit être approvisionné en float de test. Les deux points sont détaillés dans le guide d'onboarding sandbox.
guide-sandbox-onboarding

Lister les marques disponibles

Récupérez la liste paginée des marques de vouchers (page commence à 1, take vaut 10 par défaut). Le phoneNumber du client est obligatoire, au format +212*********. Notez l'id de la marque choisie. Il n'y a pas de filtre brandId sur cet endpoint : pour une marque précise, utilisez GET /api/vouchers/brands/{id}.

bash

curl -X 'GET' \
  'https://sandbox.charimoney.com/api/vouchers/brands?phoneNumber=%2B2126xxxxxxxx&page=1&take=10' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID'

Réponse

json

{
  "data": {
    "collection": [
      {
        "id": 14,
        "name": "Razer",
        "description": "Step 1: From the payment ....",
        "image": "string",
        "expirationDelay": "none"
      }
    ],
    "count": 3
  }
}

voucher-brands voucher-brand-by-id

Récupérer les articles d'une marque

Récupérez le catalogue d'articles de la marque choisie via son brandId. Chaque article expose son prix (price) et surtout les deux identifiants exigés par la suite du flux : providerSkuId (l'identifiant de l'article chez le fournisseur) et providerId (l'identifiant du fournisseur). Conservez-les pour la prévisualisation et la confirmation.

bash

curl -X 'GET' \
  'https://sandbox.charimoney.com/api/vouchers/articles?phoneNumber=%2B2126xxxxxxxx&brandId=14&page=1&take=10' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID'

Réponse

json

{
  "data": {
    "collection": [
      {
        "providerSkuId": "string",
        "productName": "string",
        "imageUrl": "string",
        "price": 0,
        "description": "string",
        "providerId": 0,
        "brandId": 0
      }
    ],
    "count": 3
  }
}

voucher-catalog voucher-articles-by-brand

Prévisualiser l'achat

Vérifiez la faisabilité de l'achat avant toute exécution. Le corps porte cinq champs obligatoires : customerPhoneNumber, destinationPhoneNumber, beneficiaryName (champ libre), providerSkuId et providerId. La réponse renvoie type 23 (VOUCHER, voir la table « Types et références »), feesAmount (les frais) et totalAmount (le montant total TTC) — affichez-les au client avant de confirmer.

bash

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

Réponse

json

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

voucher-preview

Confirmer et remettre le code du voucher

Exécutez l'achat avec le même corps que la prévisualisation. C'est cette réponse qui porte le livrable : operation.code contient le code du voucher à communiquer au bénéficiaire, accompagné de voucherName (nom du voucher acheté), description et cashBack (montant de cashback éventuel). Stockez le code de façon sécurisée et remettez-le au bénéficiaire.

bash

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

Réponse

json

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

voucher-confirm

6
Aller plus loin : le catalogue local (SKU)
À côté du flux marques/articles ci-dessus, l'API expose un catalogue de vouchers locaux, filtrable par brandId et par mot-clé. Le skuId des vouchers retournés alimente un second flux d'achat, distinct : POST /api/operations/service/voucher/preview (qui renvoie l'objet voucher complété, notamment amount) puis POST /api/operations/service/voucher (scope operation:voucher). Attention : le swagger ne documente pas le schéma de la réponse 200 de la liste, et ce flux « service » ne doit pas être confondu avec /api/operations/voucher/preview utilisé aux étapes précédentes.
bash
```
curl -X 'GET' \
  'https://sandbox.charimoney.com/api/vouchers?phoneNumber=%2B2126xxxxxxxx&page=1&take=20&brandId=14' \
  -H 'Chari-Api-Key: YOUR_API_KEY' \
  -H 'C-Request-Id: YOUR_REQUEST_ID'
```
vouchers-local-list voucher-service-preview voucher-service-purchase
7
Gérer les erreurs
Les erreurs de l'API suivent les codes HTTP standards, complétés par des codes d'erreur Chari spécifiques pour les erreurs métier, renvoyés en 400 au format { "errorCode": …, "errorDescription": "…" }. Les cas les plus fréquents sur ce flux sont listés ci-dessous ; la table complète figure dans la section « Codes d'erreur ».
401 — Identifiants d'authentification (API KEY) non autorisés — vérifiez l'en-tête Chari-Api-Key.
10001 — Missing Parameters — un des cinq champs obligatoires du corps (customerPhoneNumber, destinationPhoneNumber, beneficiaryName, providerSkuId, providerId) manque.
422 — Le serveur ne peut pas traiter la requête.

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

Notes

•Le type de wallet ("P" particulier / "C" commerçant) se définit à l'inscription (Register) : walletType n'est pas envoyé à la confirmation.

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/reset

Réinitialiser le PIN

Réinitialise le code PIN d'un client après validation d'un code OTP.

Parameter	Type	In	Requis	Description
`phoneNumber`	string	body	Requis	Numéro de téléphone du client. Format : +212*********
`otp`	string	body	Requis	Code OTP reçu par SMS.
`pin`	string	body	Requis	Nouveau PIN du client (4 chiffres).

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 /api/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.
5Une fois la vérification ShareID terminée, votre app demande la montée de niveau via PUT /api/customers/upgrade/request (voir « Confirmation KYC »).
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.

PUT{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/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).

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

Notes

•KYB — les documents requis pour la création d'un wallet marchand (client professionnel) dépendent du statut juridique du client. Dans les trois cas, la CIN ou le passeport du signataire du contrat (DocType 1 ou 3) et une preuve de compte bancaire — RIB / attestation de compte, ou chèque annulé / spécimen de chèque — sont requis. Téléversez chaque document avec le DocType correspondant de la table « Types de documents ».
•Personne morale (société / organisation) : CIN / passeport du signataire ; statuts de la société ; procès-verbal de la dernière Assemblée Générale confirmant le pouvoir de signature (requis uniquement si le gérant / représentant légal n'est pas désigné comme signataire unique dans les statuts) ; certificat du Registre de Commerce (DocType 8) de moins de 90 jours ; certificat d'inscription à la Taxe Professionnelle (Patente) ; preuve de compte bancaire (RIB ou chèque annulé).
•Professionnel individuel (auto-entrepreneur / freelance / entreprise individuelle) : CIN / passeport du signataire ; carte d'auto-entrepreneur / document d'immatriculation professionnelle ; certificat d'inscription à la Taxe Professionnelle (Patente) ; preuve de compte bancaire (RIB ou chèque annulé) ; certificat du Registre de Commerce (DocType 8) de moins de 90 jours et statuts de la société, le cas échéant.
•Fondation / association : CIN / passeport du signataire ; procès-verbal de la dernière Assemblée Générale confirmant le pouvoir de signature (requis uniquement si le représentant autorisé n'est pas clairement mentionné dans les statuts) ; liste des représentants autorisés / membres du bureau ; statut de l'association / fondation ; preuve de compte bancaire (RIB ou chèque annulé).

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.
`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.
`3dSecure`	bool	body	Optionnel	Activer 3D Secure. Par défaut : true.
`autoCapture`	bool	body	Optionnel	Capture automatique du paiement.
`allowInternationalCards`	bool	body	Optionnel	Accepter les cartes internationales.
`feesPercent`	decimal	body	Optionnel	Pourcentage de frais appliqués au payeur.
`internationalFeesPercent`	decimal	body	Optionnel	Frais % spécifiques aux cartes internationales.
`acceptUrl`	string	body	Optionnel	URL de redirection en cas de succès 3DS.
`declineUrl`	string	body	Optionnel	URL de redirection en cas d'échec 3DS.
`notificationUrl`	string	body	Optionnel	URL notifiée après fin de transaction (succès/échec).
`externalReference`	string	body	Optionnel	Référence externe du partenaire.

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
`code`	string	query	Optionnel	Code de l'agent dont le wallet est crédité.
`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.
`cardName`	string	body	Optionnel	Nom choisi par l'utilisateur pour sauvegarder la carte.
`3dSecure`	bool	body	Optionnel	Activer 3D Secure. Par défaut : true.
`autoCapture`	bool	body	Optionnel	Capture automatique du paiement.
`allowInternationalCards`	bool	body	Optionnel	Accepter les cartes internationales.
`feesPercent`	decimal	body	Optionnel	Pourcentage de frais appliqués au payeur.
`internationalFeesPercent`	decimal	body	Optionnel	Frais % spécifiques aux cartes internationales.
`acceptUrl`	string	body	Optionnel	URL de redirection en cas de succès 3DS.
`declineUrl`	string	body	Optionnel	URL de redirection en cas d'échec 3DS.
`notificationUrl`	string	body	Optionnel	URL notifiée après fin de transaction (succès/échec).
`externalReference`	string	body	Optionnel	Référence externe du partenaire.

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/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	Optionnel	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.
`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.
`declineUrl`	string	body	Optionnel	URL de redirection en cas d'échec 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
`customerPhoneNumber`	string	query	Optionnel	Numéro du marchand (client) pour lequel générer le QR. Format : +212*********
`maskedNumber`	bool	query	Optionnel	Masquer le numéro du marchand dans le contenu QR. Ex : +2126######74
`billNumber`	string	body	Optionnel	Numéro de facture à intégrer dans le contenu QR (optionnel).
`additionalData`	string	body	Optionnel	Données additionnelles libres à intégrer dans le contenu QR (optionnel).

Notes

•Le paramètre query s'appelle customerPhoneNumber (et non phoneNumber).
•billNumber et additionalData s'envoient dans le corps de la requête (optionnels).

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
`customerPhoneNumber`	string	query	Optionnel	Numéro du marchand (client) pour lequel générer le QR. Format : +212*********
`maskedNumber`	bool	query	Optionnel	Masquer le numéro du marchand.
`amount`	decimal	body	Requis	Montant fixe du QR Code.
`billNumber`	string	body	Optionnel	Numéro de facture à intégrer dans le contenu QR (optionnel).
`additionalData`	string	body	Optionnel	Données additionnelles libres à intégrer dans le contenu QR (optionnel).

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`.
•Le paramètre query s'appelle customerPhoneNumber (et non phoneNumber).

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

Par carte — Capturer

Capture une autorisation de paiement carte marchand. À utiliser pour finaliser un paiement initié avec `AutoCapture = false` : les fonds autorisés sont alors effectivement débités.

Parameter	Type	In	Requis	Description
`PhoneNumber`	string	body	Requis	Numéro du marchand. Format : +212*********
`Amount`	decimal	body	Requis	Montant à capturer.
`OrderId`	string	body	Requis	Identifiant de commande retourné par le paiement carte (`orderId`).
`TransactionTrackId`	string	body	Requis	Identifiant de suivi retourné par le paiement carte (`transactionTrackId`).
`SkipGatewayCall`	bool	body	Optionnel	Si true, ne pas appeler la passerelle de paiement lors de la capture.

Notes

•Scope requis : operations:merchant-payment.
•orderId et transactionTrackId proviennent de la réponse du paiement carte (endpoint « Par carte — Exécuter »).
•Flux type : paiement carte avec AutoCapture = false → autorisation → capture (cet endpoint) ou annulation (reverse).

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

Par carte — Annuler (Reverse)

Annule (reversal) une autorisation de paiement carte marchand non encore capturée : les fonds autorisés sont libérés sans être débités.

Parameter	Type	In	Requis	Description
`PhoneNumber`	string	body	Requis	Numéro du marchand. Format : +212*********
`Amount`	decimal	body	Requis	Montant de l'autorisation à annuler.
`OrderId`	string	body	Requis	Identifiant de commande retourné par le paiement carte (`orderId`).
`TransactionTrackId`	string	body	Requis	Identifiant de suivi retourné par le paiement carte (`transactionTrackId`).
`SkipGatewayCall`	bool	body	Optionnel	Si true, ne pas appeler la passerelle de paiement lors de l'annulation.

Notes

•Scope requis : operations:merchant-payment.
•Corps de requête identique à l'endpoint Capture : ciblez la transaction via orderId et transactionTrackId.
•Le reversal s'applique à une autorisation non capturée ; pour un paiement déjà capturé, utilisez l'endpoint Refund.

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

Par carte — Rembourser

Rembourse un paiement carte marchand déjà capturé, en totalité ou partiellement via `RefundAmount`.

Parameter	Type	In	Requis	Description
`PhoneNumber`	string	body	Requis	Numéro du marchand. Format : +212*********
`OperationId`	int	body	Requis	Identifiant de l'opération à rembourser.
`RefundAmount`	decimal	body	Requis	Montant à rembourser.
`OrderId`	string	body	Optionnel	Identifiant de commande de la transaction d'origine (`orderId`).
`TransactionTrackId`	string	body	Optionnel	Identifiant de suivi de la transaction d'origine (`transactionTrackId`).

Notes

•Scope requis : operations:refund (différent du scope operations:merchant-payment des autres endpoints carte).
•Un RefundAmount inférieur au montant capturé effectue un remboursement partiel.

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

Statut d'un QR Code

Vérifie le statut d'un QR Code marchand à partir de sa référence.

Parameter	Type	In	Requis	Description
`reference`	string	query	Requis	Référence du QR Code à vérifier.

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/fatourati/cashin/request

Demander un CashIn (Fatourati)

Initie une opération de CashIn via le fournisseur Fatourati. Endpoint dédié : Fatourati est un fournisseur spécial avec son propre flux de génération de référence (préfixe FATREF-). Utilisez cette route dédiée au lieu de la route cashin standard ; le comportement de génération et les règles d'expiration peuvent différer.

Parameter	Type	In	Requis	Description
`PhoneNumber`	string	body	Requis	Numéro de téléphone du client. Pour un agent principal, remplacez phoneNumber par le Code agent (PhoneNumber => Code).
`Amount`	decimal	body	Requis	Montant à créditer. Valeur numérique positive.
`Description`	string	body	Optionnel	Champ libre décrivant l'objet de l'opération.
`FeesPercent`	decimal	body	Optionnel	Pourcentage de frais appliqué (présent dans l'exemple de la documentation).

Notes

•Endpoint dédié : Fatourati possède son propre flux de génération de référence (préfixe FATREF-), distinct du flux CashIn standard.
•type (operationType) : 1 = CashIn, 2 = CashOut
•status (operationStatus) : 1 = open, 2 = completed, 3 = failed

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	Filtre par type d'opération (répétable) : 1=CASHIN, 2=CASHOUT, 3=TRANSFER, 5=MOBILE_PAYMENT, 7=PAYMENT_REFUND, 9=BANK_TRANSFER, 10=RECHARGE, 12=CHARGEBACK, 23=VOUCHER, 24=CARD_PAYMENT, 25=BILL_PAYMENT.
`TransactionStatus`	int	query	Optionnel	Filtre par statut : 1=OPEN, 2=COMPLETED, 3=FAILED, 4=CANCELED.
`Sens`	int	query	Optionnel	Sens de l'opération : 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.
`Keyword`	string	query	Optionnel	Mot-clé de recherche.

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
`pageNumber`	int	query	Optionnel	Numéro de page (commence à 1). Par défaut : 1
`pageSize`	int	query	Optionnel	Résultats par page. Par défaut : 10
`operationType`	list int	query	Optionnel	Filtrer par type(s) d'opération. Paramètre répétable.
`operationStatus`	list int	query	Optionnel	Filtrer par statut(s) d'opération. Paramètre répétable.
`from`	datetime	query	Optionnel	Date/heure de début.
`to`	datetime	query	Optionnel	Date/heure de fin.
`search`	string	query	Optionnel	Mot-clé de recherche.
`openLoop`	boolean	query	Optionnel	Filtrer les opérations open loop (hors wallets Chari).
`method`	string	query	Optionnel	Filtrer par méthode de paiement.
`includeDetails`	boolean	query	Optionnel	Inclure le détail de chaque opération dans la réponse.

Notes

•Endpoint à l'échelle du partenaire : aucun phoneNumber n'est requis. Pour les opérations d'un client précis, utilisez GET /api/operations.
•operationType et operationStatus acceptent plusieurs valeurs en répétant le paramètre (ex. ?operationType=1&operationType=2).

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
`SortBy`	string	query	Optionnel	Champ de tri.
`SortOrder`	string	query	Optionnel	Ordre de tri (asc ou desc).
`Name`	string	query	Optionnel	Filtrer par nom du bénéficiaire.
`BeneficiaryNumber`	string	query	Optionnel	Filtrer par numéro de téléphone du bénéficiaire.
`Rib`	string	query	Optionnel	Filtrer par RIB du bénéficiaire.
`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`	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/{beneficiaryId}

Modifier un bénéficiaire

Met à jour un bénéficiaire existant.

Parameter	Type	In	Requis	Description
`phoneNumber`	string	query	Requis	Numéro de téléphone du client (propriétaire).
`beneficiaryId`	int	path	Requis	ID du bénéficiaire à modifier.
`name`	string	body	Requis	Nom du bénéficiaire. Minimum 2 lettres.
`phoneNumber`	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/{cardId}

Supprimer une carte

Supprime une carte tokenisée par son Id.

Parameter	Type	In	Requis	Description
`cardId`	int	path	Requis	ID de la carte tokenisée à supprimer.
`phoneNumber`	string	query	Requis	Numéro de téléphone du client. Format : +212*********

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

Cartes d'un agent

Récupère la liste paginée des cartes tokenisées d'un agent.

Parameter	Type	In	Requis	Description
`code`	string	query	Requis	Code de l'agent.
`pageSize`	int	query	Optionnel	Nombre de résultats par page. Valeur par défaut = 10.
`pageNumber`	int	query	Optionnel	Page de résultats à récupérer. Commence à 1. Valeur par défaut = 1.

Notes

•customerTokenizedCardId : identifiant unique de la carte tokenisée, à utiliser comme {cardId} dans les endpoints de détail, renommage et suppression.
•maskedPan : numéro de carte masqué (4 derniers chiffres).
•requiredCvv : true si le CVV doit être re-saisi à chaque cash-in avec cette carte.
•Ces cartes servent aux dépôts par carte côté agent (cash-in carte agent).

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

Carte d'agent par ID

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

Parameter	Type	In	Requis	Description
`code`	string	query	Requis	Code de l'agent.
`cardId`	int	route	Requis	Identifiant de la carte tokenisée.

Notes

•La carte doit appartenir à l'agent identifié par code, sinon elle n'est pas retournée.

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

Renommer une carte d'agent

Met à jour le nom (cardName) d'une carte tokenisée d'un agent.

Parameter	Type	In	Requis	Description
`code`	string	query	Requis	Code de l'agent.
`cardId`	int	route	Requis	Identifiant de la carte tokenisée à renommer.
`cardName`	string	body	Requis	Nouveau nom de la carte.

Notes

•Un code HTTP 200 confirme la mise à jour (pas de corps de réponse détaillé).
•Seul le libellé cardName est modifiable : les autres attributs de la carte tokenisée sont immuables.

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

Supprimer une carte d'agent

Supprime une carte tokenisée d'un agent.

Parameter	Type	In	Requis	Description
`cardId`	int	route	Requis	Identifiant de la carte tokenisée à supprimer.
`code`	string	query	Requis	Code de l'agent.

Notes

•Un code HTTP 200 confirme la suppression (pas de corps de réponse détaillé).
•La suppression est définitive : pour réutiliser la carte, il faudra la tokeniser à nouveau.

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}

Modifier un agent

Met à jour les informations d'un agent détaillant existant, identifié par son code.

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

Notes

•Tous les champs du corps sont optionnels (nullable) dans le schéma du swagger.
•Une réponse 204 No Content confirme la mise à jour ; le swagger de production ne publie pas de corps de réponse.
•400 / 401 : réponse au format ProblemDetails (Bad Request / Unauthorized).

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

Agent principal par code

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

Parameter	Type	In	Requis	Description
`code`	string	path	Requis	Code de l'agent principal.

Notes

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

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	Requis	Description
`page`	int	query	Optionnel	Page de résultats à récupérer. Commence à 1. Valeur par défaut = 1.
`take`	int	query	Optionnel	Nombre de résultats par page. Valeur par défaut = 10.

Notes

•collection : liste des programmes.
•count : nombre de programmes.
•La pagination utilise page et take (et non PageNumber/PageSize).

POST{host}/api/cards/applications

Créer une demande

Crée une nouvelle demande de carte.

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

Notes

•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	Requis	Description
`status`	int	query	Optionnel	Filtre par statut : 1=Pending, 2=Validated, 3=Rejected.
`page`	int	query	Optionnel	Page de résultats à récupérer. Commence à 1. Valeur par défaut = 1.
`take`	int	query	Optionnel	Nombre de résultats par page. Valeur par défaut = 10.

Notes

•collection : liste des demandes.
•count : nombre de demandes.
•CardApplicationStatus — 1 : PENDING, 2 : VALIDATED, 3 : REJECTED.
•La pagination utilise page et take (et non PageNumber/PageSize).

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

Demandes par client

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

Parameter	Type	In	Requis	Description
`phoneNumber`	string	query	Requis	Numéro de téléphone du client. Format : +212*********
`page`	int	query	Optionnel	Page de résultats à récupérer. Commence à 1. Valeur par défaut = 1.
`take`	int	query	Optionnel	Nombre de résultats par page. Valeur par défaut = 10.

Notes

•collection : liste des demandes.
•count : nombre de demandes.
•La pagination utilise page et take (et non PageNumber/PageSize).

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

Valider une demande

Valide une demande de carte en cours.

Parameter	Type	In	Requis	Description
`id`	int	path	Requis	Id de la demande à valider.

Notes

•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	Requis	Description
`id`	int	path	Requis	Id de la demande à rejeter.
`reason`	string	body	Optionnel	Motif du rejet (optionnel), renvoyé ensuite dans rejectionReason.

Notes

•Le corps accepte un champ optionnel reason : le motif est renvoyé dans rejectionReason de la demande.

GET{host}/api/cards

Lister les cartes

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

Parameter	Type	In	Requis	Description
`pageNumber`	int	query	Optionnel	Page de résultats à récupérer. Commence à 1. Valeur par défaut = 1.
`pageSize`	int	query	Optionnel	Nombre de résultats par page. Valeur par défaut = 10.
`customerId`	int	query	Optionnel	Filtrer par identifiant du client.
`accountId`	int	query	Optionnel	Filtrer par identifiant de compte.
`cardProgramId`	int	query	Optionnel	Identifiant du programme de carte.
`status`	int	query	Optionnel	Statut de carte : 1=ISSUED, 2=ACTIVATED, 3=BLOCKED, 4=SUSPENDED, 5=EXPIRED, 6=CANCELLED.
`isVirtual`	boolean	query	Optionnel	Filtrer les cartes virtuelles (true) ou physiques (false).
`schemaId`	int	query	Optionnel	Identifiant du schéma de carte (ex. VISA).
`deliveryStatusId`	int	query	Optionnel	Statut de livraison (voir énumérations cartes).

Notes

•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.
•Le filtre de statut s'appelle status (et non CardStatusId) ; le filtre par client se fait via customerId (pas de PhoneNumber).

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	Requis	Description
`id`	int	path	Requis	Id de la carte.

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

Activer une carte

Active la carte et la rend prête à l'emploi.

Parameter	Type	In	Requis	Description
`PhoneNumber`	string	query	Requis	Numéro de téléphone du client. Format : +212*********
`Id`	int	route	Requis	Id de la carte à activer.

Notes

•Réponse : l'objet carte mis à jour. cardStatus 2 = ACTIVATED.

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

Bloquer une carte

Bloque temporairement la carte : aucune transaction n'est possible.

Parameter	Type	In	Requis	Description
`PhoneNumber`	string	query	Requis	Numéro de téléphone du client. Format : +212*********
`Id`	int	route	Requis	Id de la carte à bloquer.
`Reason`	string	body	Optionnel	Motif du blocage.

Notes

•Réponse : l'objet carte mis à jour. cardStatus 3 = BLOCKED.

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

Suspendre une carte

Suspend l'usage de la carte jusqu'à nouvel ordre.

Parameter	Type	In	Requis	Description
`PhoneNumber`	string	query	Requis	Numéro de téléphone du client. Format : +212*********
`Id`	int	route	Requis	Id de la carte à suspendre.
`Reason`	string	body	Optionnel	Motif de la suspension.

Notes

•Réponse : l'objet carte mis à jour. cardStatus 4 = SUSPENDED.

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

Réactiver une carte

Réactive une carte précédemment suspendue.

Parameter	Type	In	Requis	Description
`PhoneNumber`	string	query	Requis	Numéro de téléphone du client. Format : +212*********
`Id`	int	route	Requis	Id de la carte à réactiver.

Notes

•Réponse : l'objet carte mis à jour. cardStatus 2 = ACTIVATED.

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

Annuler une carte

Annule et désactive définitivement la carte.

Parameter	Type	In	Requis	Description
`PhoneNumber`	string	query	Requis	Numéro de téléphone du client. Format : +212*********
`Id`	int	route	Requis	Id de la carte à annuler.
`Reason`	string	body	Optionnel	Motif de l'annulation.

Notes

•Réponse : l'objet carte mis à jour. cardStatus 6 = CANCELLED. Action définitive : la carte ne peut plus être réactivée.

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	Requis	Description
`PhoneNumber`	string	query	Requis	Numéro de téléphone du client. Format : +212*********
`Id`	int	route	Requis	Id de la carte à mettre à jour.
`allowAtm`	bool	body	Requis	Activer ou désactiver les retraits au GAB.
`allowOnline`	bool	body	Requis	Activer ou désactiver les transactions en ligne / e-commerce.
`allowPos`	bool	body	Requis	Activer ou désactiver les paiements TPE (point de vente).
`contactlessEnabled`	bool	body	Requis	Activer ou désactiver les paiements sans contact.

Notes

•Réponse : true / false.

GET{host}/api/card-transactions/card/{cardId}

Transactions d'une carte

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

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

Notes

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

Opérations réseau (Sandbox)

Endpoints réseau pour exécuter et consulter les opérations CashIn/CashOut par référence (étape agent réseau). Ils s'utilisent aussi bien en sandbox qu'en production : en sandbox, appelez-les vous-même pour finaliser vos parcours de test sans réseau d'agents réel, avec 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

Cliquer pour copier

CVV

Cliquer pour copier

Expiration

Cliquer pour copier — API: 2608 (ou toute date future)

Code 3DS

Cliquer pour copier

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

Exécuter un CashIn réseau

Exécute un CashIn par référence depuis une entité réseau (étape agent réseau). Déclenche le webhook `cashin.network.executed`. En sandbox, appelez cet endpoint vous-même pour finaliser vos tests.

Parameter	Type	In	Requis	Description
`withContext`	bool	query	Optionnel	Retourner le résultat avec son contexte s'il existe. Par défaut : false.
`reference`	string	body	Requis	Référence numérique retournée lors de la création de la requête CashIn.
`entity`	string	body	Optionnel	Entité réseau qui exécute l'opération.

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

Exécuter un CashOut réseau

Exécute un CashOut par référence depuis une entité réseau (étape agent réseau). Déclenche le webhook `cashout.network.executed`. En sandbox, appelez cet endpoint vous-même pour finaliser vos tests.

Parameter	Type	In	Requis	Description
`withContext`	bool	query	Optionnel	Retourner le résultat avec son contexte s'il existe. Par défaut : false.
`reference`	string	body	Requis	Référence numérique retournée lors de la création de la requête CashOut.
`entity`	string	body	Optionnel	Entité réseau qui exécute l'opération.

Webhooks

Les webhooks permettent à la plateforme ChariBaaS 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
`payment.confirmed`	Paiement de facture confirmé (état CONFIRME)
`payment.cancelled`	Paiement de facture annulé (état ANNULE)
`payment.refunded`	Paiement de facture remboursé (état REMBOURSE)
`payment.failed`	Paiement de facture échoué (état FAILED)
`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

customer.level.updated — Niveau de compte client mis à jour

json

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

cashin.card.authorized — CashIn par carte accepté

json

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

payment.card.authorized — Paiement par carte accepté

json

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

payment.received — Paiement reçu par le marchand

json

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

payment.confirmed — Paiement de facture confirmé (CONFIRME)

json

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

payment.cancelled — Paiement de facture annulé (ANNULE)

json

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

payment.refunded — Paiement de facture remboursé (REMBOURSE)

json

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

payment.failed — Paiement de facture échoué (FAILED)

json

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

bank-transfer.initiated — Virement bancaire envoyé

json

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

bank-transfer.completed — Virement bancaire finalisé

json

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

bank-transfer.received — Virement bancaire reçu

json

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

transfer.received — Transfert reçu

json

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

cashin.network.executed — CashIn par référence exécuté

json

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

cashout.network.executed — CashOut par référence exécuté

json

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

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.

Recharge Telco

L'API Telco fournit une interface unifiée et sécurisée pour les services de recharge mobile prépayée. Elle expose deux services : récupérer le catalogue des produits de recharge disponibles, et déclencher une recharge pour un numéro et une offre donnés, avec validation en temps réel. Opérateurs supportés au Maroc : Maroc Telecom (IAM), Orange et Inwi.

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

Récupérer le catalogue

Récupère la liste des produits et offres de recharge disponibles pour un numéro et un opérateur donnés.

Parameter	Type	In	Requis	Description
`RecipientPhoneNumber`	string	body	Requis	Numéro de téléphone du client, au format requis : +212*********.
`Amount`	int	body	Requis	Montant à transiger. Valeur numérique positive.
`Operator`	int	body	Requis	Opérateur : 1 = Maroc Telecom, 2 = Orange, 3 = Inwi.

Notes

•Le tableau data contient la liste des produits disponibles pour l'opérateur demandé.
•Utilisez productCode dans l'endpoint de recharge pour sélectionner l'offre.

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

Demander une recharge

Initie une recharge mobile pour un numéro et une offre sélectionnée, avec validation en temps réel et suivi de transaction.

Parameter	Type	In	Requis	Description
`RecipientPhoneNumber`	string	body	Requis	Numéro de téléphone du client, au format requis : +212*********.
`Amount`	int	body	Requis	Montant à transiger. Valeur numérique positive.
`Operator`	int	body	Requis	Opérateur : 1 = Maroc Telecom, 2 = Orange, 3 = Inwi.
`ProductCode`	int	body	Requis	Code produit disponible, fourni par l'endpoint catalogue.
`Code`	string	body	Requis	Code de l'agent principal — le compte qui sera débité. Communiqué par Chari après activation de votre compte partenaire.
`RechargeType`	int	body	Requis	Type de recharge : 0 = Classic, 1 = Product.

Notes

•Les trois opérateurs sont supportés : 1 = Maroc Telecom, 2 = Orange, 3 = Inwi.
•Code correspond au code agent principal (compte débité), communiqué par Chari après activation du compte partenaire.
•operationType : valeur 10 (voir la table « Types et références »).

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

Recharge client — Aperçu

Vérifie la faisabilité d'une recharge téléphonique payée depuis le wallet du client (montant, frais) avant exécution.

Parameter	Type	In	Requis	Description
`customerPhoneNumber`	string	body	Requis	Numéro de téléphone du client dont le wallet sera débité. Format : +212*********
`recipientPhoneNumber`	string	body	Requis	Numéro de téléphone à recharger. Format : +212*********
`amount`	decimal	body	Requis	Montant de la recharge.
`operator`	int	body	Requis	Opérateur : 1 = Maroc Telecom, 2 = Orange, 3 = Inwi.
`rechargeType`	int	body	Requis	Type de recharge : 0 = Classic, 1 = Product (enum swagger : 0 à 3).
`productCode`	int	body	Optionnel	Code produit issu de l'endpoint catalogue (utilisé pour une recharge de type Product).
`rechargeStatus`	int	body	Optionnel	Statut de la recharge (enum swagger : 0 à 4). Champ du DTO partagé avec les réponses.
`beneficiaryId`	int	body	Optionnel	Référence à un bénéficiaire existant (optionnel).

Notes

•Variante « client » : le wallet du client (customerPhoneNumber) est débité — à distinguer de /api/operations/service/telco/recharge/b2b qui débite le compte agent principal.
•operator : 1 = Maroc Telecom, 2 = Orange, 3 = Inwi.
•rechargeType : 0 = Classic, 1 = Product ; pour une recharge Product, utilisez le productCode fourni par le catalogue.

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

Recharge client — Exécuter

Exécute une recharge téléphonique payée depuis le wallet du client, pour le numéro et l'offre sélectionnés.

Parameter	Type	In	Requis	Description
`customerPhoneNumber`	string	body	Requis	Numéro de téléphone du client dont le wallet sera débité. Format : +212*********
`recipientPhoneNumber`	string	body	Requis	Numéro de téléphone à recharger. Format : +212*********
`amount`	decimal	body	Requis	Montant de la recharge.
`operator`	int	body	Requis	Opérateur : 1 = Maroc Telecom, 2 = Orange, 3 = Inwi.
`rechargeType`	int	body	Requis	Type de recharge : 0 = Classic, 1 = Product (enum swagger : 0 à 3).
`productCode`	int	body	Optionnel	Code produit issu de l'endpoint catalogue (utilisé pour une recharge de type Product).
`rechargeStatus`	int	body	Optionnel	Statut de la recharge (enum swagger : 0 à 4). Champ du DTO partagé avec les réponses.
`beneficiaryId`	int	body	Optionnel	Référence à un bénéficiaire existant (optionnel).

Notes

•Appelez d'abord /api/operations/service/telco/recharge/preview pour vérifier montant et frais.
•Variante « client » : le wallet du client est débité — la variante /b2b débite le compte agent principal.

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

Historique des recharges d'un client

Récupère la liste des opérations de recharge téléphonique d'un client, avec pagination et filtre par statut.

Parameter	Type	In	Requis	Description
`phoneNumber`	string	query	Requis	Numéro de téléphone du client. Format : +212*********
`pageSize`	int	query	Optionnel	Nombre d'éléments par page.
`pageNumber`	int	query	Optionnel	Numéro de la page à récupérer.
`status`	list int	query	Optionnel	Statut(s) de recharge à filtrer (enum swagger : 0 à 4). Paramètre répétable.

Notes

•La réponse est une liste d'opérations de recharge (pas d'enveloppe de pagination : utilisez pageSize/pageNumber pour parcourir).
•status est répétable pour filtrer sur plusieurs statuts, ex. status=2&status=3.

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

Catalogue telco (variante générique)

Variante générique de l'endpoint catalogue : prend un numéro, un montant et un opérateur, et renvoie une liste de chaînes de caractères.

Parameter	Type	In	Requis	Description
`phoneNumber`	string	body	Optionnel	Numéro de téléphone concerné. Format : +212*********
`amount`	int	body	Requis	Montant de la recharge envisagée.
`operator`	int	body	Requis	Opérateur : 1 = Maroc Telecom, 2 = Orange, 3 = Inwi.

Notes

•Le swagger ne fournit pas de summary pour cet endpoint ; cette fiche s'en tient strictement aux schémas déclarés.
•La réponse 200 est déclarée comme un simple tableau de chaînes de caractères, sans structure supplémentaire documentée.
•Pour un catalogue structuré (productCode, libellés, disponibilité), utilisez /api/services/telco/catalog/b2b.

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

Export des données telco

Déclenche l'export des données telco sur une période donnée. Renvoie un booléen indiquant le succès de la demande.

Parameter	Type	In	Requis	Description
`from`	datetime	query	Requis	Date/heure de début de la période à exporter (ISO 8601).
`to`	datetime	query	Requis	Date/heure de fin de la période à exporter (ISO 8601).

Notes

•Les deux paramètres from et to sont obligatoires.
•La réponse 200 est un booléen : true si la demande d'export a été prise en compte.

Vouchers

L'API Voucher fournit une interface standardisée et sécurisée pour émettre, gérer et utiliser des bons (vouchers) numériques au sein de l'écosystème ChariBaaS : distribution de valeur et services prépayés (cartes cadeaux, recharges de jeux, etc.). Le flux d'achat suit un modèle prévisualisation/confirmation.

GET{host}/api/vouchers/articles

Récupérer le catalogue (articles)

Récupère le catalogue courant : la liste des articles de vouchers d'une marque donnée.

Parameter	Type	In	Requis	Description
`phoneNumber`	string	query	Requis	Numéro de téléphone du client, au format +212*********.
`brandId`	int	query	Requis	Identifiant de la marque. Valeur numérique positive.
`page`	int	query	Optionnel	Page de résultats à récupérer. Commence à 1. Valeur par défaut : 1.
`take`	int	query	Optionnel	Nombre de résultats par page. Valeur par défaut : 10.

GET{host}/api/vouchers/brands

Récupérer les marques

Récupère la liste des marques de vouchers disponibles.

Parameter	Type	In	Requis	Description
`phoneNumber`	string	query	Requis	Numéro de téléphone du client, au format +212*********.
`page`	int	query	Optionnel	Page de résultats à récupérer. Commence à 1. Valeur par défaut : 1.
`take`	int	query	Optionnel	Nombre de résultats par page. Valeur par défaut : 10.

Notes

•Aucun filtre brandId sur cet endpoint : pour une marque précise, utilisez GET /api/vouchers/brands/{id}.

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

Récupérer une marque par identifiant

Récupère une marque spécifique par son identifiant.

Parameter	Type	In	Requis	Description
`id`	int	path	Requis	Identifiant de la marque.
`phoneNumber`	string	query	Requis	Numéro de téléphone du client, au format +212*********.

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

Récupérer les vouchers d'une marque

Récupère la liste des vouchers associés à une marque, par identifiant de marque.

Parameter	Type	In	Requis	Description
`id`	int	path	Requis	Identifiant de la marque.
`phoneNumber`	string	query	Requis	Numéro de téléphone du client, au format +212*********.

Notes

•La réponse reprend la structure d'un objet Brand, telle que définie dans la documentation source.

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

Acheter un voucher — Prévisualisation

Vérifie la faisabilité de l'opération d'achat du voucher (montant, frais) avant confirmation.

Parameter	Type	In	Requis	Description
`CustomerPhoneNumber`	string	body	Requis	Numéro de téléphone du client, au format +212*********.
`DestinationPhoneNumber`	string	body	Requis	Numéro de téléphone du bénéficiaire, au format +212*********.
`BeneficiaryName`	string	body	Requis	Champ libre décrivant le nom du bénéficiaire.
`ProviderSkuId`	string	body	Requis	Identifiant de l'article.
`ProviderId`	string	body	Requis	Identifiant du fournisseur qui fournit le voucher.

Notes

•type : valeur 23 (voir la table « Types et références »).
•feesAmount correspond aux frais ; totalAmount au montant total TTC.

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

Acheter un voucher — Confirmation

Exécute l'opération d'achat du voucher. Renvoie le code du voucher et ses détails.

Parameter	Type	In	Requis	Description
`customerPhoneNumber`	string	body	Requis	Numéro de téléphone du client, au format +212*********.
`destinationPhoneNumber`	string	body	Requis	Numéro de téléphone du bénéficiaire, au format +212*********.
`beneficiaryName`	string	body	Requis	Champ libre décrivant le nom du bénéficiaire.
`providerSkuId`	string	body	Requis	Identifiant de l'article.
`providerId`	string	body	Requis	Identifiant du fournisseur qui fournit le voucher.

Notes

•type / operation.operationType : valeur 23 (voir la table « Types et références »).
•operation.code contient le code du voucher à communiquer au bénéficiaire.
•cashBack : montant de cashback éventuel.

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

Voucher (service) — Aperçu

Vérifie la faisabilité de l'achat d'un voucher local identifié par son SKU, avant exécution. Renvoie l'objet voucher complété (montant inclus).

Parameter	Type	In	Requis	Description
`customerPhoneNumber`	string	body	Requis	Numéro de téléphone du client, au format +212*********.
`skuId`	int	body	Requis	Identifiant SKU du voucher local (voir la liste des vouchers locaux).
`providerSkuId`	string	body	Optionnel	Identifiant SKU côté fournisseur (le cas échéant).
`destinationPhoneNumber`	string	body	Optionnel	Numéro de téléphone du bénéficiaire, au format +212*********.
`beneficiaryName`	string	body	Optionnel	Champ libre décrivant le nom du bénéficiaire.
`amount`	decimal	body	Optionnel	Montant du voucher (renseigné par le serveur dans la réponse).
`providerId`	int	body	Optionnel	Identifiant du fournisseur qui fournit le voucher.

Notes

•Scope requis : operations:voucher (indiqué dans le swagger).
•La réponse reprend le même objet voucher que la requête, complété (notamment amount).
•À distinguer de /api/operations/voucher/preview (fiche « Acheter un voucher — Prévisualisation ») qui utilise un corps différent et renvoie une enveloppe d'aperçu d'opération.

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

Voucher (service) — Achat

Exécute l'achat d'un voucher local identifié par son SKU. Le wallet du client est débité et les informations de l'opération sont renvoyées.

Parameter	Type	In	Requis	Description
`customerPhoneNumber`	string	body	Requis	Numéro de téléphone du client, au format +212*********.
`skuId`	int	body	Requis	Identifiant SKU du voucher local (voir la liste des vouchers locaux).
`providerSkuId`	string	body	Optionnel	Identifiant SKU côté fournisseur (le cas échéant).
`destinationPhoneNumber`	string	body	Optionnel	Numéro de téléphone du bénéficiaire, au format +212*********.
`beneficiaryName`	string	body	Optionnel	Champ libre décrivant le nom du bénéficiaire.
`amount`	decimal	body	Optionnel	Montant du voucher (le cas échéant).
`providerId`	int	body	Optionnel	Identifiant du fournisseur qui fournit le voucher.

Notes

•Scope requis : operation:voucher (indiqué dans le swagger).
•Appelez d'abord /api/operations/service/voucher/preview pour valider le voucher et son montant.

GET{host}/api/vouchers

Lister les vouchers locaux

Récupère la liste des vouchers locaux disponibles pour un client, avec pagination et filtres par marque et mot-clé.

Parameter	Type	In	Requis	Description
`phoneNumber`	string	query	Requis	Numéro de téléphone du client, au format +212*********.
`page`	int	query	Optionnel	Numéro de la page à récupérer.
`take`	int	query	Optionnel	Nombre d'éléments par page.
`brandId`	int	query	Optionnel	Filtre par identifiant de marque (voir l'endpoint des marques).
`keyword`	string	query	Optionnel	Recherche par mot-clé sur les vouchers.

Notes

•Le swagger ne documente pas le schéma de la réponse 200 pour cet endpoint (seules les erreurs 400/500 sont décrites).
•Le skuId des vouchers retournés est utilisé par les endpoints d'aperçu et d'achat (/api/operations/service/voucher).

GET{host}/api/vouchers/product

Produits Click & Collect

Récupère la liste paginée des produits « click & collect » disponibles.

Parameter	Type	In	Requis	Description
`page`	int	query	Optionnel	Numéro de la page à récupérer.
`take`	int	query	Optionnel	Nombre d'éléments par page.

Notes

•Le swagger ne documente pas le schéma de la réponse 200 pour cet endpoint (seules les erreurs 400/500 sont décrites).
•Utilisez le configId d'un produit avec l'endpoint de détail /api/vouchers/products/{configId}.

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

Détail d'un produit

Récupère les informations détaillées d'un produit à partir de son identifiant de configuration.

Parameter	Type	In	Requis	Description
`configId`	string	path	Requis	Identifiant de configuration du produit (retourné par la liste des produits).

Notes

•Le swagger ne documente pas le schéma de la réponse 200 pour cet endpoint (seules les erreurs 400/500 sont décrites).
•Le configId provient de la liste des produits « click & collect » (/api/vouchers/product).

Paiement de factures

Le module Paiement de factures permet aux utilisateurs finaux de régler des factures auprès des créanciers connectés au réseau Fatourati au Maroc (RADEEMA, LYDEC, IAM, TGR, AMENDIS, REDAL, et autres facturiers Fatourati). Le flux suit 5 étapes : lister les créanciers, lister les créances d'un créancier, récupérer le formulaire d'identification dynamique, consulter les impayés, puis confirmer le paiement. Modèle mono-créancier (pas de panier multi-facturiers) ; paiement partiel supporté. Base sandbox : https://sandbox.charimoney.com.

GET{host}/api/bills/creanciers

Lister les créanciers

Renvoie la liste des créanciers actifs accessibles au partenaire via ChariBaaS (filtrée selon le contrat et la configuration Fatourati du partenaire). La réponse étant relativement stable, un cache de quelques heures côté partenaire est acceptable.

Aucun paramètre requis.

Notes

•codeRetour : 000 = ACCEPTE (succès), 908 = problème technique Fatourati.
•Réponse relativement stable : un cache de quelques heures côté partenaire est acceptable.

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

Lister les créances d'un créancier

Renvoie la liste des créances actives exposées par un créancier donné (une créance correspond à un type de service : facture, recharge, taxe…). Un créancier peut exposer plusieurs créances.

Parameter	Type	In	Requis	Description
`creancierId`	string	query	Requis	Identifiant du créancier obtenu via GET /creanciers (4 chiffres).

Notes

•codeRetour : 000 = ACCEPTE, 104 = créancier inexistant ou inactif, 908 = problème technique.

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

Récupérer le formulaire d'identification

Renvoie le schéma du formulaire dynamique d'identification client pour le couple (créancier, créance) : champs à afficher (libellé, type, format, taille, contraintes). Le partenaire DOIT construire son écran de saisie à partir de cette réponse (pas de formulaire codé en dur) afin de rester compatible avec les nouveaux créanciers ajoutés au réseau Fatourati.

Parameter	Type	In	Requis	Description
`creancierId`	string	query	Requis	Identifiant du créancier (4 chiffres).
`creanceId`	string	query	Requis	Identifiant de la créance, toujours sur 2 positions (ex. 01).

Notes

•typeChamp : text, select, password, libelle. Un champ libelle est un texte statique (non saisissable) qui ne doit JAMAIS être renvoyé dans creancierVals.
•formatChamp : 1 = string, 2 = integer, 3 = real. contrainte : 0 = optionnel, 1 = obligatoire.
•refTxFatourati : 1 = appeler /impayes (valeur par défaut), 2 = sendRecharge (potentiellement obsolète).
•Codes de retour : 000 = ACCEPTE (succès), 103 = service/créance inactif pour le créancier choisi, 104 = créancier inexistant, 908 = problème technique Fatourati.

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

Consulter les impayés

Soumet l'identification client (saisie via /form) et récupère les impayés du client chez le créancier. Cet appel ouvre la transaction (état EN_ATTENTE) et renvoie un refTxFatourati à utiliser pour /confirm. L'association reste valide 7 jours calendaires (délai Fatourati).

Parameter	Type	In	Requis	Description
`phoneNumber`	string	query	Requis	Numéro Chari Money de l'utilisateur final, format international (ex. +212670770743).
`creancierId`	string	query	Requis	Identifiant du créancier (4 chiffres).
`creanceId`	string	query	Requis	Identifiant de la créance (2 positions).
`creancierVals`	array	body	Requis	Tableau des valeurs saisies par l'utilisateur : objets { nomChamp, valChamp } (hors champs typeChamp=libelle). Attention : la propriété s'appelle valChamp (et non valeurChamp) dans ce corps.
`alias`	string	body	Optionnel	Alias à enregistrer si la facture est ajoutée aux favoris.
`addToFavorites`	boolean	body	Optionnel	true pour ajouter la facture aux favoris du client.
`qrCodeContent`	string	body	Optionnel	Contenu d'un QR code scanné, en alternative à la saisie des champs d'identification.

Notes

•La transaction passe à l'état EN_ATTENTE ; conservez refTxFatourati pour /confirm. Validité : 7 jours calendaires.
•creancierVals : la propriété de valeur s'appelle valChamp dans ce corps (et non valeurChamp comme dans les réponses /form et /impayes) ; ne renvoyez pas les champs typeChamp=libelle.
•codeDevise : 504 = MAD.
•typeFrais : forfait, commission, forfait_facture. valeurFrais = pourcentage × 100 (ex. 1 % → 100).
•typeArticle : 0 = créance, 1 = frais, 2 = obligatoire, 3 = timbre.
•globalParams : les paramètres techniques à libellé vide (contrPaiement, isConfTO, isAnnul, rejoue, colAffiche) ne doivent jamais être affichés au client.
•Codes de retour clés : 000 = succès (EN_ATTENTE), 103 = créance inactive, 104 = créancier inexistant, 107 = aucune créance à payer, 109 = champ requis manquant, 902/908/909/910/911 = erreurs technique/connexion.
•Mode hors-ligne : un paiement peut aussi être initié via une référence Fatourati statique de 13 chiffres (4 créancier + 2 créance + 6 facture + 1 clé de contrôle), transmise dans creancierVals.

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

Confirmer le paiement

Confirme le paiement de la sélection d'articles effectuée par l'utilisateur. Un codeRetour 000 indique un règlement effectif côté créancier. L'utilisateur final est identifié par son numéro Chari Money (paramètre phoneNumber).

Parameter	Type	In	Requis	Description
`phoneNumber`	string	query	Requis	Numéro Chari Money de l'utilisateur final, format international (ex. +212670770743). Doit correspondre à un utilisateur Chari Money existant, sinon la transaction est rejetée avant tout appel à Fatourati.
`creancierId`	string	body	Requis	Identifiant du créancier (mêmes valeurs que /impayes).
`creanceId`	string	body	Requis	Identifiant de la créance.
`refTxFatourati`	string	body	Requis	Référence renvoyée par /impayes. Lie l'appel à la transaction ouverte.
`totalPayment`	boolean	body	Optionnel	true pour régler la totalité des impayés, false pour une sélection partielle.
`listeArticleSelectionnes`	array	body	Requis	Sous-ensemble des impayesParams sélectionnés par l'utilisateur : objets { idArticle, prixTTC, typeArticle, dateFacture, description }.
`creancierVals`	array	body	Requis	Champs d'identification saisis : objets { nomChamp, valChamp }. Attention : la propriété s'appelle valChamp (et non valeurChamp) dans ce corps, et libelle n'y est pas accepté.
`globalParams`	array	body	Optionnel	Paramètres globaux renvoyés par /impayes : objets { libelle, nomChamp, valeurChamp }.

Notes

•Corps identique à /preview : creancierVals utilise { nomChamp, valChamp } (pas de libelle), et les articles de listeArticleSelectionnes n'acceptent que { idArticle, prixTTC, typeArticle, dateFacture, description } (pas d'extraArticleParams).
•codeRetour 000 = CONFIRME (règlement effectif). 301 = transaction déjà traitée (à traiter comme un succès, afficher le reçu).
•Comportement asynchrone (canal digital) : les codes 908/909/910 ne sont PAS des échecs définitifs — la transaction reste à l'état AUTORISE et sa résolution finale (CONFIRME/ANNULE) est notifiée par webhook.
•refReglement doit figurer sur le reçu. numCRC / texteCRC (params) : à afficher sur le reçu si présents.
•Webhooks du module : payment.confirmed, payment.cancelled, payment.refunded, payment.failed — émis pour notifier la résolution finale (états CONFIRME / ANNULE / REMBOURSE / FAILED).

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

Prévisualiser le paiement

Prévisualise le règlement de la sélection d'articles avant confirmation. Le corps est identique à celui de /confirm : l'appel valide la sélection (créancier, créance, articles) pour l'utilisateur identifié par phoneNumber, sans exécuter le paiement.

Parameter	Type	In	Requis	Description
`phoneNumber`	string	query	Requis	Numéro Chari Money de l'utilisateur final, format international (+212*********).
`creancierId`	string	body	Requis	Identifiant du créancier (4 chiffres, mêmes valeurs que /impayes).
`creanceId`	string	body	Requis	Identifiant de la créance (2 positions).
`refTxFatourati`	string	body	Requis	Référence renvoyée par /impayes (12 chiffres). Lie l'appel à la transaction ouverte.
`totalPayment`	boolean	body	Optionnel	true pour régler la totalité des impayés, false pour une sélection partielle.
`listeArticleSelectionnes`	array	body	Requis	Articles sélectionnés par l'utilisateur : objets { idArticle, prixTTC, typeArticle, dateFacture, description } issus de impayesParams.
`creancierVals`	array	body	Requis	Champs d'identification saisis : objets { nomChamp, valChamp }. Attention : la propriété s'appelle valChamp (et non valeurChamp) dans ce corps.
`globalParams`	array	body	Optionnel	Paramètres globaux renvoyés par /impayes : objets { libelle, nomChamp, valeurChamp }.

Notes

•Corps identique à /confirm : construisez-le à partir des réponses de /form et /impayes, puis rejouez-le tel quel sur /confirm après validation par l'utilisateur.
•creancierVals : la propriété de valeur s'appelle valChamp dans ce corps (et non valeurChamp comme dans les réponses /form et /impayes).
•totalPayment : true = règlement de la totalité des impayés, false = sélection partielle (le paiement partiel est supporté par le module).
•Le swagger de production ne publie pas de schéma de réponse détaillé pour cet endpoint (200 Success) ; l'exemple ci-dessus est indicatif.

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

Historique des factures du client

Renvoie les factures payables et l'historique de paiement de factures du client identifié par son numéro Chari Money. Résultats paginés via pageNumber et pageSize.

Parameter	Type	In	Requis	Description
`phoneNumber`	string	query	Requis	Numéro Chari Money du client, format international (+212*********).
`pageNumber`	int	query	Optionnel	Numéro de la page à renvoyer.
`pageSize`	int	query	Optionnel	Nombre d'éléments par page.

Notes

•Pagination : pageNumber et pageSize sont optionnels ; en leur absence, la pagination par défaut du serveur s'applique.
•Le swagger de production ne publie pas le schéma détaillé de la réponse (200 Success) ; l'exemple ci-dessus est indicatif et reprend le vocabulaire du module (refTxFatourati, montantTotalTTC, états CONFIRME/ANNULE…).

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

Statut d'un cash-in par référence

Renvoie le statut d'un cash-in Fatourati à partir de sa référence : exécution, statut, montant, horodatages et identifiant de l'opération Chari associée.

Parameter	Type	In	Requis	Description
`reference`	string	query	Optionnel	Référence Fatourati du cash-in à interroger.

Notes

•La réponse est renvoyée à la racine, sans enveloppe { "data": … }.
•204 No Content : aucune transaction ne correspond à la référence fournie.
•400 / 401 : réponse au format ProblemDetails (Bad Request / Unauthorized).

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

Télécharger le reçu de paiement

Télécharge le reçu d'un paiement de facture à partir de l'identifiant de l'opération Chari. Le client est identifié par son numéro Chari Money.

Parameter	Type	In	Requis	Description
`operationId`	int	path	Requis	Identifiant de l'opération Chari du paiement de facture (voir chariOperationId de /reference/status ou l'historique).
`phoneNumber`	string	query	Requis	Numéro Chari Money du client, format international (+212*********). Doit correspondre au client ayant effectué l'opération.

Notes

•La réponse 200 contient le fichier du reçu de paiement (contenu binaire à télécharger), pas un corps JSON.
•Le reçu doit mentionner la référence de règlement (refReglement) renvoyée par /confirm.

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

Lister les favoris

Renvoie la liste des factures favorites du client, groupées par catégorie de créancier. Les favoris permettent de relancer rapidement le paiement d'une facture récurrente sans ressaisir l'identification.

Parameter	Type	In	Requis	Description
`phoneNumber`	string	query	Requis	Numéro Chari Money du client, format international (+212*********).

Notes

•Les favoris sont groupés par catégorie de créancier.
•favoriteId est l'identifiant à utiliser avec PUT et DELETE /api/bills/favorite/{favoriteId}.
•Le swagger de production ne publie pas le schéma détaillé de la réponse (200 Success) ; l'exemple ci-dessus est indicatif.

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

Renommer un favori

Met à jour l'alias d'une facture favorite du client. L'alias est le libellé affiché à l'utilisateur (ex. « Maison Marrakech »).

Parameter	Type	In	Requis	Description
`favoriteId`	int	path	Requis	Identifiant du favori (obtenu via GET /api/bills/favorite).
`phoneNumber`	string	query	Requis	Numéro Chari Money du client propriétaire du favori, format international (+212*********).
`alias`	string	body	Requis	Nouvel alias du favori.

Notes

•alias est le seul champ modifiable via cet endpoint.
•Une réponse 200 confirme la mise à jour ; le swagger de production ne publie pas de corps de réponse.

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

Supprimer un favori

Supprime une facture favorite du client. La suppression n'affecte pas les paiements déjà effectués.

Parameter	Type	In	Requis	Description
`favoriteId`	int	path	Requis	Identifiant du favori à supprimer (obtenu via GET /api/bills/favorite).
`phoneNumber`	string	query	Requis	Numéro Chari Money du client propriétaire du favori, format international (+212*********).

Notes

•Une réponse 200 confirme la suppression ; le swagger de production ne publie pas de corps de réponse.

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
23	VOUCHER
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

Scopes API

Scopes déclarés par la spécification de l'API de production. Les endpoints absents de cette table n'ont aucun scope déclaré dans la spécification ; votre clé API délimite dans tous les cas l'accès global.

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

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.

Obtenir un accès sandbox

Remplissez ce formulaire pour lancer votre onboarding technique : clé API sandbox, whitelisting de vos IPs, activation des modules et invitation au Partner Back Office. L'équipe ChariBaaS revient vers vous rapidement. L'accès sandbox est une étape technique : toute exploitation en production des services reste soumise à l'approbation de Bank Al-Maghrib (accord de non-objection).

Documentation API

Démarrage rapide

En-têtes d'authentification

Carte de test (Sandbox)

Pack LLM & IA

Référence interactive (Swagger UI)

Spécification OpenAPI (Swagger)

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

Guides d'intégration

Démarrer en sandbox : accès, activations, premiers appels

Obtenir l'accès sandbox

Valider la clé : premier appel

Faire activer les modules nécessaires

Demander du float de test

Utiliser la carte de test (3D Secure)

Outiller votre intégration

Préparer le passage en production

Créer et activer un wallet client de bout en bout

Vérifier le statut du numéro

Inscrire le client (walletType)

Confirmer l'OTP (autoActivate)

Créer le PIN pour activer le wallet

Contrôler le login par PIN

Consulter le solde du wallet

Récupérer le profil complet du client

Dépôt par carte avec 3D Secure : du preview au webhook

Prévisualiser le dépôt

Exécuter avec la carte de test sandbox

Compléter l'authentification 3D Secure

Recevoir le webhook cashin.card.authorized

Vérifier l'opération

Variante agent : créditer le wallet d'un agent

Rejouer le dépôt avec la carte tokenisée

Paiement marchand par carte : du preview au remboursement

Prévisualiser le paiement (frais, faisabilité)

Premier encaissement : exécuter avec autoCapture

Valider le retour 3D Secure

Paiement en deux temps : autoriser puis capturer

Annuler une autorisation non capturée (reverse)

Rembourser un paiement capturé (total ou partiel)

Réencaisser avec la carte tokenisée

Aller plus loin : statut d'un QR Code marchand

Cash-in / cash-out par référence : de la demande à l'exécution

Créer la demande de CashIn

Consulter la demande par sa référence

Exécuter le CashIn côté agent

Dérouler le CashOut symétrique

Simuler l'exécution réseau en sandbox

Recevoir la confirmation par webhook

Variante Fatourati : la demande de CashIn dédiée

Paiement de factures Fatourati : du créancier au reçu

Lister les créanciers Fatourati

Lister les créances du créancier choisi

Construire le formulaire d'identification dynamique

Consulter les impayés du client

Confirmer le paiement (après prévisualisation)

Suivre la transaction et délivrer le reçu

Écouter les webhooks payment.*

Recharge téléphonique B2B : catalogue, recharge, variante client

Vérifier l'activation du service telco

Récupérer le catalogue des offres (B2B)

Exécuter la recharge B2B

Variante client : prévisualiser la recharge

Variante client : exécuter la recharge

Consulter l'historique des recharges d'un client

Gérer les erreurs

Vendre des vouchers : marques, articles, prévisualisation, code

Vérifier le provisioning du catalogue

Lister les marques disponibles

Récupérer les articles d'une marque

Prévisualiser l'achat

Confirmer et remettre le code du voucher

Aller plus loin : le catalogue local (SKU)