Demande reçue
Reçu n°000 001
Sujet : Autre demande
Merci. Nous avons bien reçu votre demande et nous revenons vers vous par e-mail ou par téléphone.
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.
POST/v1/transaction/payment
{ "service": "ORANGE_BFA_MARCHAND", "amount": 5000, "customerPhone": "76000000", "partnerTransId": 20260924001}
Réponse 200 : transaction créée, statut INITIATED
Le client compose le code USSD
Callback envoyé à votre callbackUrl
Interface recréée pour ce site. Données fictives. Démonstration animée. Aucune opération réelle n’est effectuée.
Créez un paiement avec POST /v1/. Votre client le valide sur son téléphone.
Versez de l’argent sur le portefeuille mobile d’un client : remboursement, gains, paiement d’un fournisseur.
Un lien unique, valable 30 minutes, qui ouvre la page de paiement Kaalice.
Statut à la demande, et notification automatique sur votre serveur au statut final.
Votre solde pour chaque opérateur, en temps réel.
Transactions sur une période, retraits, mouvements de solde, chiffre d’affaires mensuel et par service.
Un appel crée la transaction. L’API vous renvoie le code USSD que votre client compose pour valider.
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"
}'// Node.js (axios)
import axios from "axios";
const { data } = await axios.post(
"https://api.kaalice.com/v1/transaction/payment",
{
agence: "VOTRE_CODE_AGENCE",
service: "ORANGE_BFA_MARCHAND",
amount: 5000,
customerPhone: "76000000",
partnerTransId: 20260924001,
callbackUrl: "https://votre-boutique.example/webhooks/kaalice",
},
{ headers: { Authorization: "Bearer VOTRE_ACCESS_TOKEN" } }
);
console.log(data.status, data.ussdCode); // INITIATED *144*...## Python (requests)
import requests
response = requests.post(
"https://api.kaalice.com/v1/transaction/payment",
headers={"Authorization": "Bearer VOTRE_ACCESS_TOKEN"},
json={
"agence": "VOTRE_CODE_AGENCE",
"service": "ORANGE_BFA_MARCHAND",
"amount": 5000,
"customerPhone": "76000000",
"partnerTransId": 20260924001,
"callbackUrl": "https://votre-boutique.example/webhooks/kaalice",
},
timeout=30,
)
data = response.json()
print(data["status"], data["ussdCode"]) # INITIATED *144*...#<?php
// PHP (cURL)
$payload = [
'agence' => 'VOTRE_CODE_AGENCE',
'service' => 'ORANGE_BFA_MARCHAND',
'amount' => 5000,
'customerPhone' => '76000000',
'partnerTransId' => 20260924001,
'callbackUrl' => 'https://votre-boutique.example/webhooks/kaalice',
];
$ch = curl_init('https://api.kaalice.com/v1/transaction/payment');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer VOTRE_ACCESS_TOKEN',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($payload),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $data['status'] . ' ' . $data['ussdCode']; // INITIATED *144*...#{
"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
agenceserviceORANGE_BFA_MARCHAND encaisse par Orange Money.amountcustomerPhonepartnerTransIdcallbackUrlcustomerName, customerEmail et custom_data pour vos propres métadonnées.Réponse
statusINITIATED, la transaction est créée et attend votre client.transIdfeeussdCodewaveNumber, le numéro vers lequel votre client envoie le montant.POST /v1/. La transaction naît au statut INITIATED.
Il compose le code USSD de son opérateur, ou envoie le montant depuis l’application Wave.
La transaction passe en attente, puis en traitement.
Au statut final, un POST en JSON arrive sur votre callbackUrl.
Vous confirmez le statut, puis vous livrez la commande.
Cette démonstration a besoin de JavaScript. Voici son état final.
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"
}'{
"status": "INITIATED",
"transId": 1024,
"partnerTransId": 20260924001,
"amount": 5000,
"customerPhone": "76000000",
"fee": 0,
"ussdCode": "*144*...#"
}Côté client
Appel USSD
#144#
Validation du paiement de 5 000 FCFA
Ouvrez Wave et envoyez 5 000 FCFA au numéro indiqué.
70 00 00 00
INITIATEDInitiéePENDINGEn attentePROCESSINGEn traitementCOMPLETEDRéussieAu bout de 30 minutes sans validation, la transaction expire.
{
"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é.
Le cycle de vie d’une transaction : INITIATED, puis PENDING, puis PROCESSING, et enfin l’un des quatre statuts finaux.
INITIATEDInitiée
La transaction est créée. Votre client n’a pas encore validé. Vous pouvez encore l’annuler avec POST /v1/.
PENDINGEn attente
Le paiement attend sa confirmation.
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.
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.
#144#*555#*301#, pour obtenir le code OTPwaveNumberAvec la page de paiement hébergée, ces instructions s’affichent toutes seules.
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.
Avant de livrer, confirmez le statut avec GET /v1/. Il reste consultable à tout moment.
{
"transId": 1024,
"partnerTransId": 20260924001,
"transRef": "REF_EXEMPLE",
"service": "ORANGE_BFA_MARCHAND",
"amount": 5000,
"fee": 0,
"status": "COMPLETED",
"createdAt": "2026-09-24 10:15:00"
}curl "https://api.kaalice.com/v1/status/VOTRE_CODE_AGENCE/20260924001" \
-H "Authorization: Bearer VOTRE_ACCESS_TOKEN"URL de base https://
| Méthode | Chemin | À quoi il sert |
|---|---|---|
| POST | /v1/ | Obtenir un access token (e-mail et mot de passe du compte marchand) |
| POST | /v1/ | Encaisser un paiement |
| POST | /v1/ | Envoyer de l’argent vers le portefeuille d’un client |
| POST | /v1/ | Créer un lien de paiement, valable 30 minutes |
| GET | /v1/ | Connaître le statut à partir de votre référence |
| GET | /v1/ | Consulter une transaction par son identifiant Kaalice |
| GET | /v1/ | Lire votre solde pour chaque opérateur |
| POST | /v1/ | Annuler une transaction encore au statut INITIATED |
| GET | /v1/ | Lister les services et leur disponibilité |
| GET | /v1/ | Lister les transactions d’une période |
| GET | /v1/ | 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.
| Opérateur | Encaisser | Envoyer |
|---|---|---|
| Orange Money | ORANGE_BFA_MARCHAND | ORANGE_BFA_CASHIN |
| Moov Money | MOOV_BFA_MARCHAND | MOOV_BFA_CASHIN |
| Telecel Money | TELECEL_BFA_MARCHAND | TELECEL_BFA_CASHIN |
| Wave | WAVE_BFA_MARCHAND | WAVE_BFA_CASHIN |
GET /v1/ indique si chaque service est disponible. Un service en maintenance est refusé avec un message explicite.
Créez un lien avec POST /v1/ : 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.
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é.
5 000 FCFA
5 000 FCFA
Composez ce code sur votre téléphone pour valider :
#144#
Ouvrez Wave et envoyez 5 000 FCFA au numéro indiqué.
70 00 00 00
5 000 FCFA
Retour au site du marchand5 000 FCFA
Retour au site du marchand5 000 FCFA
Retour au site du marchand5 000 FCFA
Retour au site du marchandSécurisé par Kaalice
Cette démonstration a besoin de JavaScript. Voici son état final.
Interface recréée pour ce site. Données fictives.
Avec POST /v1/, 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.
GET /v1/ 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.
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.
Un partenaire peut avoir plusieurs agences. Chacune a son code et ses propres soldes par opérateur.
Solde global
2 980 000 FCFA
Solde par opérateur
Chiffre d’affaires mensuel
Dernières transactions
PaiementsRetraits
| Montant | Frais | Net | Statut |
|---|---|---|---|
| 5 000 | ••• | ••• | COMPLETEDRéussie |
| 12 500 | ••• | ••• | PROCESSINGEn traitement |
| 2 000 | ••• | ••• | EXPIREDExpirée |
| 25 000 | ••• | ••• | COMPLETEDRéussie |
Interface recréée pour ce site. Données fictives.
partnerTransId est unique par agence : impossible de créer deux fois la même transaction.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.
Dites-nous ce que vous vendez et comment vos clients paient. Nous revenons vers vous pour ouvrir votre accès.
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.
Merci. Nous avons bien reçu votre demande et nous revenons vers vous par e-mail ou par téléphone.
Demande reçue
Reçu n°000 001
Sujet : Autre demande
Merci. Nous avons bien reçu votre demande et nous revenons vers vous par e-mail ou par téléphone.