10 projets à réaliser avec les API Business PI-SPI et leur fonctionnement technique
Par DJAMA Med · Publié le · Lecture : 14 min · Basé sur la spécification API Business 1.5.0
Depuis le 2 novembre 2026, PI-SPI est le passage obligé des transferts interopérables de monnaie électronique dans l’UEMOA. Pour les développeurs et les entrepreneurs, la vraie opportunité se trouve dans l’API Business PI-SPI : elle permet d’intégrer le paiement instantané directement dans un site e-commerce, un logiciel de paie, un ERP ou une application métier. Voici 10 projets concrets à réaliser, avec pour chacun le parcours utilisateur, les endpoints utilisés et les pièges techniques à éviter.
💡 Qu’est-ce que l’API Business PI-SPI ?
L’API Business est une API standardisée par la BCEAO. Elle est exposée par les participants de PI-SPI (banques, émetteurs de monnaie électronique, établissements de paiement) à leurs clients entreprises. Son but : offrir partout la même interface technique et éviter que chaque établissement développe sa propre solution isolée.
D’après la spécification officielle (version 1.5.0, publiée le 27 août 2026), elle permet de :
📖 Pour le détail de chaque fonctionnalité, lisez d’abord notre guide API Business PI-SPI : fonctionnement et fonctionnalités.
Pour une entreprise, le paiement n’est donc plus un service séparé : il devient une fonctionnalité native de son logiciel. C’est un levier majeur pour la digitalisation des entreprises en Côte d’Ivoire et dans toute l’UEMOA.
🏗️ Le rôle de l’API Business dans l’architecture technique
Quel que soit le projet, le principe d’intégration est le même. L’entreprise ne se connecte pas à chaque banque ou opérateur : elle utilise l’API Business de son participant, qui donne accès à tout l’écosystème PI-SPI.
🧩 Les briques de l’API : endpoints et scopes
Chaque appel est protégé par un scope OAuth2. Ne demandez que les scopes dont votre application a besoin. Voici les principales briques que l’on retrouve dans les 10 projets :
| Fonctionnalité | Endpoints principaux | Scope |
|---|---|---|
| Demande de paiement | POST /demandes-paiements GET /demandes-paiements/{txId} | demande_paiement.write |
| Demandes de paiement en masse | POST /demandes-paiements-groupes | demande_paiement_groupe.write |
| Envoyer un paiement | POST /paiements-envoyes | paiement.write |
| Paiement en masse | POST /paiements-groupes PUT /paiements-groupes/{instructionId}/confirmations | paiement_groupe.write |
| Paiements reçus | GET /paiements-recus GET /paiements/{end2endId} | paiement.read |
| Retour de fonds | PUT /paiements/{end2endId}/retours | retour_fonds.write |
| Demande d’annulation | POST /paiements/{end2endId}/annulations | demande_annulation.write |
| Alias | POST /comptes/{numero}/alias GET /alias/{cle} | alias.write |
| Comptes et transferts intra-comptes | GET /comptes POST /comptes/transactions | compte.read compte_transaction.write |
| Participants PI | GET /participants | participant.read |
| Webhooks | POST /webhooks POST /webhooks/{id}/secrets | webhook.write |
Les demandes de paiement utilisent un code categorie qui adapte les règles au contexte, par exemple 500 pour un paiement immédiat sur site, 521 pour un paiement e-commerce et 401 pour une facture.
🚀 10 projets à réaliser avec l’API Business PI-SPI
Pour chaque projet : l’objectif, le moment où l’API Business intervient, les endpoints utilisés et un point technique tiré de la spécification.
Plateforme de paiement pour e-commerce
Objectif : Permettre à une boutique en ligne d’encaisser ses commandes depuis n’importe quel compte bancaire ou portefeuille mobile connecté à PI-SPI.
Fonctionnement avec l’API Business
- Le client valide son panier et saisit son alias de paiement (par exemple son numéro de téléphone).
- Le backend enregistre la commande avec un
txIdunique, au statut « En attente ». - Il envoie une demande de paiement e-commerce (catégorie
521) avec le montant et le motif. - Le client reçoit la demande dans son application financière et la valide.
- Le webhook
PAIEMENT_RECUarrive sur le serveur de la boutique ; le backend vérifie la signature puis l’opération. - La commande passe automatiquement au statut « Payée » et la préparation démarre.
- En cas d’annulation ou de retour produit, la boutique rembourse via un retour de fonds.
Endpoints utilisés
Exemple concret : Une boutique WooCommerce ou Shopify à Abidjan ajoute PI-SPI comme moyen de paiement, à côté de la carte bancaire : un seul bouton suffit pour les clients Orange Money, MTN MoMo, Wave ou des banques participantes.
👉 Point technique : Pour limiter la fraude, la spécification impose une dateLimitePaiement inférieure à 3 minutes pour les demandes e-commerce. Prévoyez un écran d’attente avec compte à rebours et la possibilité de relancer la demande.
Plateforme de gestion des salaires et des primes
Objectif : Automatiser le versement des salaires, primes, indemnités et paiements de prestataires.
Fonctionnement avec l’API Business
- L’entreprise importe son fichier de paie (Excel ou CSV).
- Le logiciel contrôle les bénéficiaires, les montants et les plafonds autorisés.
- Le directeur financier valide la liste dans l’application (double validation interne).
- Le backend crée un paiement en masse, identifié par un
instructionId. - Il confirme l’envoi du lot après vérification du récapitulatif.
- Le logiciel consulte le détail du lot pour repérer les paiements réussis et ceux rejetés.
- Les paiements rejetés sont corrigés et relancés, puis les états de paie sont mis à jour.
Endpoints utilisés
Exemple concret : Une entreprise de 300 salariés prépare sa paie dans le logiciel, la fait valider par sa direction financière et déclenche tous les virements en une seule opération depuis son compte professionnel.
👉 Point technique : La documentation recommande des lots de 500 à 5 000 transactions et de découper au-delà. Depuis la version 1.5.0, un paiement individuel peut aussi viser un IBAN ou un numéro de compte, utile pour les salariés sans alias. Un paiement vers un particulier est plafonné à 10 000 000 FCFA.
Plateforme de facturation et de recouvrement
Objectif : Facturer les clients, leur envoyer une demande de paiement et suivre automatiquement les règlements.
Fonctionnement avec l’API Business
- L’entreprise crée une facture dans la plateforme.
- Le logiciel génère une demande de paiement de facture (catégorie
401) avec la référence du document. - Le client reçoit la demande : il peut payer tout de suite, programmer le paiement ou refuser.
- À réception du webhook
PAIEMENT_RECU, la facture passe au statut « Payée ». - Les champs
refDocTypeetrefDocNumeropermettent le rapprochement automatique. - À l’approche de l’échéance, le logiciel programme une relance ; en fin de mois, il envoie toutes les factures en masse.
Endpoints utilisés
Exemple concret : Un cabinet comptable qui facture 50 entreprises envoie toutes ses demandes de paiement en une fois et voit en temps réel qui a payé, sans réclamer de justificatifs.
👉 Point technique : Une demande peut être accompagnée d’une remise, valable jusqu’à la dateLimitePaiement. Sans dateLimiteReponse, le client a 90 jours pour répondre.
Application d’encaissement pour commerçants
Objectif : Transformer un smartphone ou une tablette en terminal d’encaissement, sans TPE.
Fonctionnement avec l’API Business
- Le commerçant crée l’alias de son compte d’encaissement et affiche le QR code correspondant.
- Pour une vente, il saisit le montant dans l’application.
- L’application envoie une demande de paiement sur site (catégorie
500) au client, ou le client scanne le QR code statique. - Le client valide le paiement depuis son application financière.
- Le webhook
PAIEMENT_RECUdéclenche instantanément l’écran « Paiement reçu ». - La vente est inscrite dans le journal de caisse, avec export pour la comptabilité.
Endpoints utilisés
Exemple concret : Un restaurant utilise une tablette : le serveur saisit l’addition, le client paie depuis son téléphone et la confirmation s’affiche en quelques secondes.
👉 Point technique : Une demande de paiement sur site n’a pas de date limite : elle expire au plus tard 24 heures après sa création. Vérifiez toujours que le montant reçu correspond au montant attendu.
Plateforme de gestion immobilière et de loyers
Objectif : Automatiser l’appel et la collecte des loyers, puis le reversement aux propriétaires.
Fonctionnement avec l’API Business
- L’agence enregistre les biens, les baux et l’alias de chaque locataire.
- Le logiciel génère les échéances mensuelles.
- Chaque mois, il envoie toutes les demandes de loyer en une seule demande de paiement en masse.
- Les locataires paient depuis leur application, éventuellement en programmant le paiement.
- Les webhooks mettent à jour le compte de chaque locataire en temps réel.
- Les loyers impayés restent visibles dans le tableau de bord et déclenchent des relances.
- En fin de mois, l’agence reverse aux propriétaires leur part, déduction faite des honoraires.
Endpoints utilisés
Exemple concret : Une agence qui gère 500 appartements envoie tous les appels de loyer le 1er du mois et suit, dans un seul tableau de bord, les loyers encaissés, en attente et en retard.
👉 Point technique : Utilisez la référence du bail dans refDocNumero pour rattacher chaque paiement au bon contrat, même quand le locataire paie depuis le compte d’un proche.
Plateforme de collecte de fonds et de cotisations
Objectif : Faciliter les collectes des associations, ONG, tontines, églises et organisations professionnelles.
Fonctionnement avec l’API Business
- L’organisateur crée une campagne avec un objectif et une date de fin.
- La plateforme associe un alias (et son QR code) à la campagne, selon les règles du participant.
- Les contributeurs paient en scannant le QR code ou en recevant une demande de paiement.
- Un webhook filtré sur l’alias de la campagne notifie chaque contribution.
- La plateforme rattache chaque paiement à la campagne et au contributeur.
- Le tableau de bord affiche le total collecté, la progression et la liste des donateurs.
Endpoints utilisés
Exemple concret : Une association collecte 10 millions FCFA pour construire une école : chaque membre contribue depuis son téléphone et le bureau suit les dons en direct.
👉 Point technique : Les webhooks peuvent être configurés par type d’événement et par alias : c’est la manière la plus simple de séparer les contributions de plusieurs campagnes.
Plateforme de paiement pour livreurs et transporteurs
Objectif : Encaisser les livraisons à la porte et rémunérer automatiquement les livreurs et les chauffeurs.
Fonctionnement avec l’API Business
- Le livreur arrive chez le client et déclenche l’encaissement depuis son application.
- Le backend envoie une demande de paiement sur site au client.
- Le client valide ; le webhook confirme le paiement avant la remise du colis.
- La plateforme calcule les commissions du livreur et de l’entreprise.
- En fin de journée, le responsable valide les montants dus.
- Le backend paie tous les livreurs en une seule opération de paiement en masse.
- Si besoin, l’entreprise déplace les fonds entre ses propres comptes (compte de collecte vers compte de paie).
Endpoints utilisés
Exemple concret : Une société qui travaille avec 150 livreurs supprime la manipulation d’espèces : les livraisons sont payées à la porte et les livreurs reçoivent leur rémunération chaque soir.
👉 Point technique : Les transferts intra-comptes ne servent qu’à déplacer des fonds entre les comptes d’un même client dans le même établissement. Pour payer un livreur, il faut un paiement (simple ou en masse).
Plateforme de paiement pour écoles et universités
Objectif : Digitaliser les frais d’inscription, de scolarité, de cantine, de transport et d’examens.
Fonctionnement avec l’API Business
- L’établissement enregistre les élèves, les classes et les grilles de frais.
- Le logiciel génère les échéances par trimestre ou par mois.
- À chaque échéance, il envoie les demandes de paiement aux parents en masse.
- Les parents paient tout de suite ou programment le paiement.
- Les webhooks mettent à jour le dossier financier de chaque élève.
- L’administration consulte l’état des paiements par classe, par élève ou par période.
- En cas de trop-perçu ou de départ, l’école rembourse par un retour de fonds.
Endpoints utilisés
Exemple concret : Une école de 1 500 élèves envoie les appels de scolarité en un clic et connaît à tout moment le taux de recouvrement de chaque classe.
👉 Point technique : Mettez le matricule de l’élève dans refDocNumero : un parent peut ainsi payer pour plusieurs enfants sans risque de confusion.
Plateforme de rapprochement bancaire et de gestion de trésorerie
Objectif : Centraliser toutes les transactions et les rapprocher automatiquement des factures et des écritures comptables.
Fonctionnement avec l’API Business
- L’entreprise connecte son logiciel à l’API Business de son participant.
- Les webhooks alimentent la base en temps réel ; une synchronisation périodique rattrape les événements manqués.
- Le logiciel liste les paiements reçus et envoyés, avec filtres et pagination.
- Le moteur de rapprochement associe chaque opération à une facture grâce à
refDocNumero, au montant et à la date. - Les opérations non rapprochées sont signalées au comptable.
- Le solde des comptes est consulté pour produire un tableau de trésorerie.
- Les excédents sont déplacés entre les comptes de l’entreprise par transfert intra-comptes.
Endpoints utilisés
Exemple concret : Une PME qui traite plusieurs centaines de transactions par jour retrouve automatiquement les paiements de ses factures et repère les écarts en quelques minutes au lieu de plusieurs jours.
👉 Point technique : Ne vous reposez pas uniquement sur les webhooks : une réconciliation quotidienne via les endpoints de liste garantit qu’aucune opération n’est oubliée en cas d’indisponibilité de votre serveur.
Marketplace avec paiement interopérable
Objectif : Permettre aux acheteurs de payer leurs commandes et aux vendeurs de recevoir leurs règlements.
Fonctionnement avec l’API Business
- Le vendeur publie ses produits ou services.
- L’acheteur valide sa commande ; la marketplace envoie une demande de paiement e-commerce.
- Le webhook confirme le paiement ; la marketplace enregistre la vente.
- Après la livraison ou la prestation, la commande est validée.
- La marketplace calcule la part de chaque vendeur, après commission.
- Elle règle les vendeurs par paiements simples ou en masse.
- Les litiges sont traités par retour de fonds ou par demande d’annulation.
Endpoints utilisés
Exemple concret : Une marketplace de 200 commerçants centralise les paiements des clients et automatise les reversements aux vendeurs.
👉 Point technique : La conservation temporaire des fonds, le séquestre ou le fractionnement automatique des paiements ne sont pas fournis par l’API Business. Ces mécanismes doivent être validés avec le participant et respecter la réglementation applicable.
📋 Tableau récapitulatif : quelle API pour quel projet ?
| Projet | Fonctionnalités PI-SPI principales |
|---|---|
| E-commerce | Demandes de paiement, webhooks, vérification, retours de fonds |
| Salaires et primes | Paiements en masse, paiements par IBAN ou numéro de compte |
| Facturation | Demandes de paiement (en masse), références de document |
| Encaissement commerçant | Alias, QR code, demandes de paiement sur site, webhooks |
| Gestion immobilière | Demandes de paiement en masse, paiements en masse |
| Collecte de fonds | Alias, webhooks filtrés par alias, paiements reçus |
| Livraison et transport | Demandes de paiement, paiements en masse, transferts intra-comptes |
| Paiement scolaire | Demandes de paiement en masse, retours de fonds |
| Trésorerie | Comptes, listes d’opérations, transferts intra-comptes |
| Marketplace | Demandes de paiement, paiements en masse, retours, annulations |
💻 Exemple : une demande de paiement e-commerce
Voici le corps d’une requête POST /demandes-paiements pour une commande en ligne, adapté de l’exemple officiel de la spécification :
{
"txId": "CMD-2026-000123",
"confirmation": false,
"categorie": "521",
"payeurAlias": "<alias du client>",
"payeAlias": "<alias de la boutique>",
"montant": 25000,
"dateLimitePaiement": "2026-11-09T10:03:00.000Z",
"motif": "Commande n°123 - Boutique en ligne"
}txId: votre identifiant unique (35 caractères maximum). Générez-le et enregistrez-le avant l’appel ;categorie:521pour un paiement immédiat en ligne ;dateLimitePaiement: moins de 3 minutes après l’envoi pour l’e-commerce ;confirmation: trueactive une validation en deux étapes : le participant renvoie d’abord le nom et le pays du payeur, puis attend votre confirmation (24 h maximum).
La réponse indique le statut ENVOYE : la demande est partie, mais rien n’est encore payé. La confirmation arrivera par webhook.
⚠️ Les précautions techniques importantes
PAIEMENT_RECU, puis vérifiez l’opération avec GET /paiements/{end2endId} (montant, bénéficiaire, référence) avant de livrer.txId par opération, jamais réutilisé. L’API répond 409 à un doublon sur certains endpoints. Côté serveur, traitez chaque webhook une seule fois même s’il est reçu plusieurs fois.La disponibilité exacte de chaque fonctionnalité dépend de la version de l’API et des services effectivement ouverts par votre participant. Vérifiez-la avec lui avant de lancer le développement.
🧭 Comment démarrer avec l’API Business PI-SPI
- Explorez le portail développeur de la BCEAO : documentation OpenAPI, guides, simulateurs, collection Postman et environnement de test (sandbox).
- Prototypez dans la sandbox les parcours clés de votre projet : demande de paiement, webhook, vérification, retour de fonds.
- Choisissez votre participant : votre banque ou établissement doit proposer l’API Business à ses clients entreprises. Mi-septembre 2026, 24 établissements étaient homologués.
- Obtenez vos accès : identifiants OAuth2 et certificat mTLS, provisionné via le portail PICERT.
- Passez en production après les tests de recette demandés par le participant.
Besoin d’un site ou d’une application pour porter votre projet ? Consultez nos guides sur le prix d’un site internet à Abidjan et le prix d’une application mobile.
❓ Questions fréquentes sur l’API Business PI-SPI
Qu’est-ce que l’API Business PI-SPI ?
C’est une API standardisée par la BCEAO et exposée par les participants de PI-SPI (banques, émetteurs de monnaie électronique…) à leurs clients entreprises. Elle permet d’automatiser les paiements : demandes de paiement, paiements simples et en masse, alias, retours de fonds, consultation des opérations et notifications par webhook.
Un développeur peut-il se connecter directement à PI-SPI ?
Non. L’entreprise accède à l’API Business par l’intermédiaire de son participant (sa banque ou son établissement de monnaie électronique), qui fournit les identifiants, les certificats et l’accès à la production.
Comment savoir qu’un paiement PI-SPI est réellement reçu ?
Il ne faut jamais se fier à la seule création d’une demande de paiement. Attendez l’événement webhook PAIEMENT_RECU, vérifiez sa signature, puis contrôlez l’opération avec GET /paiements/{end2endId} avant de livrer ou de valider une commande.
Peut-on rembourser un client avec l’API Business ?
Oui, grâce au retour de fonds (PUT /paiements/{end2endId}/retours), initié par celui qui a reçu le paiement, jusqu’à 90 jours après la date du paiement. Le payeur peut aussi envoyer une demande d’annulation dans le même délai.
Existe-t-il un environnement de test pour l’API Business PI-SPI ?
Oui. La BCEAO met à disposition un portail développeur avec un environnement sandbox, la documentation OpenAPI, des simulateurs et une collection Postman.
Quels sont les montants maximums d’un paiement via l’API Business ?
Ils dépendent du type d’émetteur et de destinataire. Une entreprise peut envoyer jusqu’à 10 000 000 FCFA à un particulier ou un commerçant et jusqu’à 100 000 000 FCFA à une autre entreprise ou une entité gouvernementale. Elle peut recevoir jusqu’à 5 000 000 FCFA d’un particulier ou d’un commerçant.
La véritable opportunité ne consiste pas à vendre du paiement, mais à résoudre un problème métier grâce au paiement interopérable.
🎯 Conclusion : PI-SPI, une opportunité pour les développeurs et les entrepreneurs
L’API Business PI-SPI ne sert pas seulement à créer une application de paiement. Elle permet de construire des solutions métiers complètes dans lesquelles l’encaissement et le décaissement deviennent des fonctions natives : logiciel de facturation, gestion scolaire, application d’encaissement, ERP, marketplace…
Avec une interface commune à tous les participants, un même logiciel peut fonctionner avec n’importe quelle banque ou n’importe quel opérateur de l’UEMOA. C’est le bon moment pour se positionner, avant que le marché ne se structure.
- Une API unique — la même spécification chez tous les participants
- Des webhooks signés — confirmation en temps réel, sans interroger l’API en boucle
- Des paiements en masse — salaires, reversements et appels de fonds en une opération
- Des retours de fonds — remboursements possibles pendant 90 jours
💡
Vous avez un projet basé sur l’API Business PI-SPI ?
Cadrage, architecture, développement du backend et de l’application — je peux vous accompagner de l’idée à la mise en production.
Discutons de votre projetSources
Mots-clés : API Business PI-SPI, API PI-SPI, PI-SPI développeur, intégration PI-SPI, BCEAO API, demande de paiement PI-SPI, paiement en masse, webhook PI-SPI, alias PI-SPI, paiement e-commerce UEMOA, logiciel de paie Côte d’Ivoire, fintech Abidjan, paiement instantané API.