API Kaalice Passerelle de paiement mobile money Une intégration, quatre opérateurs mobile money

L’API Kaalice permet à votre site, votre application ou votre logiciel de gestion d’encaisser des paiements Orange Money, Moov Money, Telecel Money et Wave au Burkina Faso, d’envoyer de l’argent vers le portefeuille de vos clients et de suivre chaque transaction jusqu’à son statut final.

API REST en JSON sur HTTPS. Montants en FCFA (XOF). Numéros burkinabè à 8 chiffres.

Interface recréée pour ce site. Données fictives. Démonstration animée. Aucune opération réelle n’est effectuée.

Ce que votre code peut faire

  • Encaisser

    Créez un paiement avec POST /v1/transaction/payment. Votre client le valide sur son téléphone.

  • Envoyer de l’argent

    Versez de l’argent sur le portefeuille mobile d’un client : remboursement, gains, paiement d’un fournisseur.

  • Créer un lien de paiement

    Un lien unique, valable 30 minutes, qui ouvre la page de paiement Kaalice.

  • Suivre chaque transaction

    Statut à la demande, et notification automatique sur votre serveur au statut final.

  • Connaître vos soldes

    Votre solde pour chaque opérateur, en temps réel.

  • Sortir vos chiffres

    Transactions sur une période, retraits, mouvements de solde, chiffre d’affaires mensuel et par service.

Votre premier paiement

Un appel crée la transaction. L’API vous renvoie le code USSD que votre client compose pour valider.

Requête
curl -X POST "https://api.kaalice.com/v1/transaction/payment" \
  -H "Authorization: Bearer VOTRE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agence": "VOTRE_CODE_AGENCE",
    "service": "ORANGE_BFA_MARCHAND",
    "amount": 5000,
    "customerPhone": "76000000",
    "partnerTransId": 20260924001,
    "callbackUrl": "https://votre-boutique.example/webhooks/kaalice"
  }'
Réponse
{
  "status": "INITIATED",
  "transId": 1024,
  "partnerTransId": 20260924001,
  "amount": 5000,
  "customerPhone": "76000000",
  "fee": 0,
  "ussdCode": "*144*...#"
}

Valeurs d’exemple. Remplacez VOTRE_ACCESS_TOKEN et VOTRE_CODE_AGENCE par les vôtres.

Requête

agence
le code de votre agence.
service
le service de l’opérateur. ORANGE_BFA_MARCHAND encaisse par Orange Money.
amount
le montant en FCFA.
customerPhone
le numéro du client sur 8 chiffres, sans l’indicatif +226. L’API vérifie qu’il correspond bien à l’opérateur choisi.
partnerTransId
votre référence. Numérique, de 1 à 20 chiffres, unique pour votre agence.
callbackUrl
l’adresse publique où Kaalice vous envoie le statut final.
Champs facultatifs
customerName, customerEmail et custom_data pour vos propres métadonnées.

Réponse

status
INITIATED, la transaction est créée et attend votre client.
transId
l’identifiant de la transaction chez Kaalice.
fee
les frais appliqués à cette transaction, selon votre contrat.
ussdCode
le code à afficher à votre client. Pour Wave, la réponse contient waveNumber, le numéro vers lequel votre client envoie le montant.

Le parcours d’un paiement

  1. Vous créez la transaction

    POST /v1/transaction/payment. La transaction naît au statut INITIATED.

  2. Votre client valide sur son téléphone

    Il compose le code USSD de son opérateur, ou envoie le montant depuis l’application Wave.

  3. Kaalice suit le paiement

    La transaction passe en attente, puis en traitement.

  4. Kaalice vous prévient

    Au statut final, un POST en JSON arrive sur votre callbackUrl.

  5. Vous livrez

    Vous confirmez le statut, puis vous livrez la commande.

Cette démonstration a besoin de JavaScript. Voici son état final.

Requête
curl -X POST "https://api.kaalice.com/v1/transaction/payment" \
  -H "Authorization: Bearer VOTRE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agence": "VOTRE_CODE_AGENCE",
    "service": "ORANGE_BFA_MARCHAND",
    "amount": 5000,
    "customerPhone": "76000000",
    "partnerTransId": 20260924001,
    "callbackUrl": "https://votre-boutique.example/webhooks/kaalice"
  }'
RéponseHTTP 200
{
  "status": "INITIATED",
  "transId": 1024,
  "partnerTransId": 20260924001,
  "amount": 5000,
  "customerPhone": "76000000",
  "fee": 0,
  "ussdCode": "*144*...#"
}

Côté client

  1. INITIATEDInitiée
  2. PENDINGEn attente
  3. PROCESSINGEn traitement
  4. COMPLETEDRéussie
POSThttps://votre-boutique.example/webhooks/kaalice
{
  "transId": 1024,
  "partnerTransId": 20260924001,
  "transRef": "REF_EXEMPLE",
  "service": "ORANGE_BFA_MARCHAND",
  "amount": 5000,
  "fee": 0,
  "status": "COMPLETED",
  "createdAt": "2026-09-24 10:15:00"
}

Interface recréée pour ce site. Données fictives. Démonstration animée. Aucun appel réel n’est envoyé.

Sept statuts, quatre issues

Le cycle de vie d’une transaction : INITIATED, puis PENDING, puis PROCESSING, et enfin l’un des quatre statuts finaux.

Schéma du cycle de vie d’une transaction : INITIATED, PENDING, PROCESSING, puis l’un des quatre statuts finaux COMPLETED, FAILED, CANCELLED ou EXPIRED.
  1. INITIATEDInitiée

    La transaction est créée. Votre client n’a pas encore validé. Vous pouvez encore l’annuler avec POST /v1/transaction/cancel.

  2. PENDINGEn attente

    Le paiement attend sa confirmation.

  3. PROCESSINGEn traitement

    Le paiement est en cours de traitement.

  • Statut final

    COMPLETEDRéussie

    Le paiement est confirmé. Le montant net est crédité sur votre solde de l’opérateur concerné.

  • Statut final

    FAILEDÉchouée

    Le paiement n’a pas abouti.

  • Statut final

    CANCELLEDAnnulée

    La transaction a été annulée avant la validation du client.

  • Statut final

    EXPIREDExpirée

    Le client n’a pas validé dans les 30 minutes.

Une transaction non validée expire d’elle-même au bout de 30 minutes. Vous n’avez rien à nettoyer.

Le paiement se valide sur le téléphone du client

Pas de carte bancaire : votre client confirme le paiement avec son propre compte mobile money.

Affichez à votre client le code renvoyé dans ussdCode. Il le compose sur son téléphone pour valider.

Orange Money
Code USSD #144#
Moov Money
Code USSD *555#
Telecel Money
Code USSD *301#, pour obtenir le code OTP
Wave
Envoi du montant depuis l’application Wave, vers le numéro indiqué dans waveNumber

Avec la page de paiement hébergée, ces instructions s’affichent toutes seules.

Prévenu dès que c’est fini

Quand une transaction atteint un statut final (COMPLETED, FAILED, CANCELLED ou EXPIRED), Kaalice envoie un POST en JSON à la callbackUrl que vous avez fournie. Le message contient tous les détails : transId, partnerTransId, transRef, service, montant, frais, statut et dates.

Bonne pratique

Avant de livrer, confirmez le statut avec GET /v1/status/{agenceCode}/{partnerTransId}. Il reste consultable à tout moment.

POSThttps://votre-boutique.example/webhooks/kaalice
{
  "transId": 1024,
  "partnerTransId": 20260924001,
  "transRef": "REF_EXEMPLE",
  "service": "ORANGE_BFA_MARCHAND",
  "amount": 5000,
  "fee": 0,
  "status": "COMPLETED",
  "createdAt": "2026-09-24 10:15:00"
}
Exemple de notification reçue (illustratif, champs à aligner sur la documentation officielle).
GETVérification du statut
curl "https://api.kaalice.com/v1/status/VOTRE_CODE_AGENCE/20260924001" \
  -H "Authorization: Bearer VOTRE_ACCESS_TOKEN"

Les points d’entrée

URL de base https://api.kaalice.com/v1

MéthodeCheminÀ quoi il sert
POST/v1/generate-tokenObtenir un access token (e-mail et mot de passe du compte marchand)
POST/v1/transaction/paymentEncaisser un paiement
POST/v1/transaction/cashinEnvoyer de l’argent vers le portefeuille d’un client
POST/v1/payment/linkCréer un lien de paiement, valable 30 minutes
GET/v1/status/{agenceCode}/{partnerTransId}Connaître le statut à partir de votre référence
GET/v1/transactions/{transId}Consulter une transaction par son identifiant Kaalice
GET/v1/balance/{agenceCode}Lire votre solde pour chaque opérateur
POST/v1/transaction/cancelAnnuler une transaction encore au statut INITIATED
GET/v1/servicesLister les services et leur disponibilité
GET/v1/transactions/agence/{code}/{from}/{to}Lister les transactions d’une période
GET/v1/turnover/{agence}/{year}Chiffre d’affaires mensuel sur une année

Les erreurs renvoient un message clair en français, au format {"status": "FAILED", "msg": "..."}. Les erreurs de validation répondent en HTTP 422 avec la liste des champs à corriger.

Un code service par opérateur et par sens

OpérateurEncaisserEnvoyer
Orange MoneyORANGE_BFA_MARCHANDORANGE_BFA_CASHIN
Moov MoneyMOOV_BFA_MARCHANDMOOV_BFA_CASHIN
Telecel MoneyTELECEL_BFA_MARCHANDTELECEL_BFA_CASHIN
WaveWAVE_BFA_MARCHANDWAVE_BFA_CASHIN

GET /v1/services indique si chaque service est disponible. Un service en maintenance est refusé avec un message explicite.

Pas de page de paiement à développer

Créez un lien avec POST /v1/payment/link : montant, description du produit, URL de succès, URL d’erreur et URL de callback. Partagez-le avec votre client. Il reste valable 30 minutes.

Ce que voit votre client

Votre nom, le produit et le montant en FCFA. Il choisit son opérateur, saisit son numéro et reçoit le code à composer, ou les instructions Wave. La page se met à jour toute seule dès que le paiement est confirmé, puis le renvoie vers votre site.

Chaque issue a son écran : réussi, échoué, annulé, expiré.

Page de paiement hébergée Kaalice : montant de 5 000 FCFA, choix de l’opérateur, numéro du client et code USSD à composer. Données fictives.
Page de paiement
Boutique démoCommande n° 20260924001

5 000 FCFA

Choisissez votre opérateur
Votre numéro+22676 00 00 00

Sécurisé par Kaalice

Cette démonstration a besoin de JavaScript. Voici son état final.

Interface recréée pour ce site. Données fictives.

Envoyez de l’argent à vos clients

Avec POST /v1/transaction/cashin, versez de l’argent directement sur le compte mobile money d’un client : remboursement, versement de gains, paiement d’un fournisseur. Kaalice vérifie votre solde, frais inclus, avant l’envoi.

Vos soldes, opérateur par opérateur

GET /v1/balance/{agenceCode} renvoie votre solde sur ORANGE_BFA, MOOV_BFA, TELECEL_BFA et WAVE_BFA. Les paiements reçus le créditent, les envois le débitent, frais inclus.

Le tableau de bord marchand

Solde global et solde par opérateur, paiements et retraits sur une période, chiffre d’affaires mensuel et par service, dernières transactions, listes des transactions et des retraits (montant, frais, net, statut), journal des soldes.

Plusieurs points de vente ?

Un partenaire peut avoir plusieurs agences. Chacune a son code et ses propres soldes par opérateur.

Interface recréée pour ce site. Données fictives.

Des garde-fous intégrés

  • Votre partnerTransId est unique par agence : impossible de créer deux fois la même transaction.
  • Un paiement identique (même numéro, même montant) déjà en cours est bloqué.
  • Chaque numéro est vérifié selon l’opérateur choisi.
  • Les requêtes sont limitées en débit.
  • Les erreurs s’expliquent en français.
  • Un envoi ne part pas si votre solde, frais inclus, ne suffit pas.

Une documentation où l’on essaie

Depuis la documentation interactive, générez votre token, consultez votre solde et essayez un paiement, un cashin, un lien de paiement ou une vérification de statut. Pour chaque appel, le code est généré en cURL, Node.js, Python et PHP.

Branchez le mobile money sur votre produit

Dites-nous ce que vous vendez et comment vos clients paient. Nous revenons vers vous pour ouvrir votre accès.

Demander un accès à l’API Kaalice

Dites-nous ce que vous vendez, sur quel support (site, application, logiciel) et avec quels opérateurs. Nous revenons vers vous pour ouvrir votre accès.

Nous joindre directement

E-mail
Écrire à Oxnov Technology : contact@oxnov.com
Téléphone
Appeler Oxnov Technology au (+226) 71 87 34 02 Appeler Oxnov Technology au (+226) 74 98 58 46
Adresse
Secteur 21, Wayalghin, Ouagadougou, Burkina Faso

Les champs marqués d’un astérisque sont obligatoires.

Si vous préférez être rappelé. Format : 70 00 00 00 ou +226 70 00 00 00.

Indiquez au moins un moyen de vous répondre : e-mail ou téléphone.

Quelques lignes suffisent : votre activité, ce que vous voulez changer, vos délais s’il y en a.

Ce formulaire a besoin de JavaScript. Écrivez-nous directement à contact@oxnov.com.

Ces informations servent uniquement à vous répondre. Détails dans les mentions légales.

Nos autres logiciels