PI-SPI : ce que les développeurs doivent savoir avant d'intégrer le paiement instantané de la BCEAO
Ce qu'est PI-SPI, le fonctionnement de son API Business et les pièges d'intégration : authentification OAuth2, alias, demandes de paiement et webhooks.
Dans l'UEMOA, payer quelqu'un dont le compte est dans une autre banque, ou passer d'une banque à un portefeuille mobile, a longtemps voulu dire attendre, payer des frais ou passer par un intermédiaire. PI-SPI change cela. J'ai intégré son API Business dans une application de paiement, du jeton OAuth jusqu'au virement de remboursement. Voici ce que j'aurais aimé savoir avant de commencer.
PI-SPI, en deux minutes
PI-SPI (Plateforme Interopérable du Système de Paiement Instantané) est l'infrastructure de paiement instantané de la BCEAO, la banque centrale des huit pays de l'UEMOA. Elle a été officiellement lancée le 30 septembre 2025, après une phase pilote ouverte à de vrais utilisateurs à partir de juin 2025.
Concrètement :
- Instantané et permanent : un virement arrive en quelques secondes, 24 h/24, 7 j/7.
- Interopérable : banques, établissements de monnaie électronique (EME) et autres institutions autorisées sont reliés au même rail. Un client d'une banque peut payer un client d'une autre institution sans intermédiaire.
- Alias plutôt que RIB : on paie un alias, un identifiant lié au compte, au lieu de communiquer son numéro de compte.
- QR code interopérable : un même QR peut être payé depuis n'importe quelle institution participante.
Le nombre d'institutions raccordées augmente vite : la BCEAO en annonçait 80 connectées au printemps 2026.
Pour les développeurs, la porte d'entrée est l'API Business, avec un bac à sable public ouvert par la BCEAO le 13 novembre 2025 (portail développeur : developer.pispi.bceao.int). C'est lui que j'ai utilisé.
Qui parle à qui
Premier point qui surprend : une entreprise ne se connecte pas à la BCEAO. Elle est cliente d'un participant (sa banque ou son EME), et c'est la passerelle de ce participant qui expose l'API Business. En bac à sable, le portail vous attribue un participant virtuel, avec son code (du type BJBxxx), un compte et des identifiants.
Deux sens de circulation :
| Besoin | Opération PI-SPI | Qui valide ? |
|---|---|---|
| Encaisser (le client vous paie) | une demande de paiement (RTP, request to pay) | le client, dans l'app de sa banque |
| Décaisser (vous payez quelqu'un : remboursement, reversement) | un paiement envoyé | vous, en l'émettant |
L'alias : le seul identifiant qui compte
PI-SPI ne débite et ne crédite pas un compte à partir d'un RIB ou d'un IBAN. Il travaille avec des alias. L'API Business utilise l'alias de type SHID : une clé aléatoire de 36 caractères au format UUID, rattachée à un compte.
const SHID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
export const isAlias = (value: string) => SHID.test(value.trim());
// Forme envoyée à l'API : minuscules, sans espaces.
export const normalizeAlias = (value: string) => value.trim().toLowerCase();Conséquences pour votre produit :
- Le formulaire « Ajouter un compte bancaire » doit demander l'alias, pas le RIB. Si vous gardez un champ RIB, refusez-le clairement au moment du paiement au lieu d'essayer de deviner.
- Votre entreprise a elle aussi besoin d'un alias, rattaché à son compte : c'est le
payeAliasde vos encaissements et lepayeurAliasde vos décaissements. Il se crée par l'API (POST /comptes/{numero}/aliasavec le typeSHID). - Vérifier un alias renvoie l'identité du titulaire (nom, pays, catégorie), jamais son solde. N'affichez donc pas de « solde » pour un compte bancaire lié par PI-SPI : votre application ne peut pas le connaître.
S'authentifier : OAuth2 et une clé d'API
Chaque appel porte deux éléments : un jeton OAuth2 obtenu en client_credentials, et l'en-tête x-api-key. En production s'ajoute le mTLS (certificat client) ; le bac à sable propose une URL sans mTLS pour démarrer.
async function getToken(): Promise<string> {
if (cache && cache.expiresAt > Date.now()) return cache.token;
const res = await fetch(process.env.PISPI_TOKEN_URL!, {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: new URLSearchParams({
grant_type: 'client_credentials',
client_id: process.env.PISPI_CLIENT_ID!,
client_secret: process.env.PISPI_CLIENT_SECRET!,
// Uniquement les scopes accordés à votre client (voir les pièges plus bas).
scope: ['paiement.write', 'paiement.read', 'demande_paiement.write',
'demande_paiement.read', 'compte.read', 'alias.read', 'alias.write']
.map((s) => `piz/${s}`).join(' '),
}),
});
if (!res.ok) throw new Error(`Authentification PI-SPI refusée (${res.status})`);
const { access_token, expires_in } = await res.json();
// On garde une marge d'une minute avant l'expiration.
cache = { token: access_token, expiresAt: Date.now() + (expires_in - 60) * 1000 };
return access_token;
}
async function pispi(method: string, path: string, body?: unknown) {
return fetch(`${process.env.PISPI_API_URL}/${process.env.PISPI_PARTICIPANT_CODE}${path}`, {
method,
headers: {
Authorization: `Bearer ${await getToken()}`,
'x-api-key': process.env.PISPI_API_KEY!,
'Content-Type': 'application/json',
},
body: body === undefined ? undefined : JSON.stringify(body),
});
}Remarquez le code du participant en préfixe de chaque chemin. Ce n'est pas ce que dit toute la documentation, et c'est le premier piège (voir plus bas).
Tous ces secrets restent côté serveur. Une application mobile ne doit jamais appeler PI-SPI directement : elle appelle votre back-end, qui appelle PI-SPI.
Encaisser : la demande de paiement
Pour encaisser, vous créez une demande ; c'est la banque du payeur qui la lui présente, et c'est lui qui la valide.
const res = await pispi('POST', '/demandes-paiements', {
txId: 'CMD-2026-000123', // VOTRE référence, unique (voir idempotence)
categorie: '500', // demande « sur site »
payeurAlias: normalizeAlias(aliasDuClient),
payeAlias: ALIAS_ENTREPRISE,
montant: 5000, // en francs CFA (XOF), entier
motif: 'Commande 123',
confirmation: false,
});
// 201 : la demande existe, statut INITIE. Rien n'est encore payé.Le paiement n'est pas fini quand l'appel répond. La demande attend la validation du client, qui peut prendre quelques secondes… ou ne jamais arriver. Votre commande reste donc « en attente » jusqu'à un statut final.
Décaisser : le paiement envoyé
Pour payer quelqu'un (remboursement, reversement à un commerçant), les rôles s'inversent : vous êtes le payeur.
await pispi('POST', '/paiements-envoyes', {
txId: 'REMB-000042',
payeurAlias: ALIAS_ENTREPRISE,
payeAlias: normalizeAlias(aliasDuBeneficiaire),
montant: 4000,
motif: 'Remboursement commande 123',
confirmation: false,
});Avant d'envoyer, lisez le solde de votre compte : GET /comptes/{numero} renvoie un champ solde. Un virement refusé pour fonds insuffisants est plus simple à gérer avant l'envoi qu'après.
Les statuts : un seul vaut « payé »
On relit une opération par GET /demandes-paiements/{txId} ou GET /paiements-envoyes/{txId}. Le champ statut se traduit ainsi :
type Outcome = 'paye' | 'echec' | 'attente';
function outcome(statut?: string): Outcome {
if (statut === 'IRREVOCABLE') return 'paye'; // seul succès final
if (statut === 'REJETE' || statut === 'ANNULE') return 'echec'; // lire statutRaison
return 'attente'; // INITIE, ENVOYE, CONFIRME
}Deux règles qui évitent des erreurs coûteuses :
- 01.
CONFIRMEn'est pasIRREVOCABLE. Ne livrez rien, ne créditez rien avantIRREVOCABLE. - 02.Un
404sur la relecture n'est pas un échec. Une opération toute récente peut ne pas être encore visible : traitez-le comme une attente et relisez plus tard.
Idempotence : le txId est votre meilleur ami
PI-SPI refuse un txId déjà utilisé (code de raison DU03). C'est une excellente nouvelle : si votre appel échoue sur un délai d'attente sans que vous sachiez si la demande est partie, renvoyez-la avec le même txId. Soit elle est créée, soit PI-SPI répond « déjà reçue », et vous relisez son statut. Il n'y a jamais de double débit.
if (res.status === 409 || body?.statutRaison === 'DU03') {
return relireStatut(txId); // elle existe déjà : son verdict est celui du statut
}Utilisez donc une référence stable, dérivée de votre objet (commande, remboursement), jamais un identifiant aléatoire tiré à chaque tentative.
Webhooks : un déclencheur, pas une preuve
Vous enregistrez une URL de rappel (POST /webhooks). PI-SPI y envoie des événements { data: [{ evCode, txId, end2endId, … }] }, signés dans l'en-tête X-Signature : un HMAC-SHA256 du corps brut avec un secret qui vous est remis une seule fois, à l'enregistrement. Conservez-le immédiatement.
import crypto from 'crypto';
function verifySignature(rawBody: Buffer, header: string | undefined, secret: string) {
const received = header?.trim().replace(/^sha256=/i, '').toLowerCase();
if (!received) return false;
const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
return received.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
}Trois conseils :
- Calculez la signature sur le corps brut, avant tout parsing JSON. Un corps réécrit par votre framework ne correspond plus à la signature.
- Ne faites jamais confiance au contenu du webhook pour valider un paiement. Servez-vous-en pour savoir quelle opération relire, puis relisez son statut par l'API.
- Prévoyez une relecture périodique des opérations en attente. Un webhook peut se perdre ; votre système ne doit pas rester bloqué pour autant.
Les pièges du Sandbox
Voici ce que j'ai constaté en appelant réellement le bac à sable, là où la documentation disait autre chose. Les guides évoluent : vérifiez sur votre propre environnement, mais si un appel échoue sans raison apparente, regardez ici d'abord.
- 01.Les chemins sont préfixés par le code du participant :
/{CODE}/comptes/…, comme dans le Playground du portail. Avec le préfixe/v1de certains guides, j'obtenais un403ou des sous-routes introuvables. - 02.Ne demandez que les scopes qui vous sont accordés. Si la liste contient un seul scope non accordé (
participant.readdans mon cas), toute la demande de jeton est refusée en400. Les scopes sont préfixés parpiz/. - 03.Le solde est le champ
soldedeGET /comptes/{numero}. Il n'y a pas de route/soldedédiée. - 04.La catégorie de demande
500refusedateLimitePaiement. N'envoyez pas de date limite pour une demande « sur site » : PI-SPI la fait expirer de lui-même. - 05.Le
txIddoit survivre à une URL. Mes références commençaient par#; une fois encodé (%23…), letxIdn'était plus retrouvé à la relecture (404), et la demande serait restée « en attente » pour toujours. Limitez-vous àA-Z a-z 0-9 _ -, et gardez exactement cetxIdcomme référence chez vous : c'est lui que renvoient la relecture et le webhook. - 06.Erreurs au format RFC 7807 : en cas de refus, lisez
detail(puistitle) pour un message affichable.
Mettre en production : la checklist
- Secrets (client, clé d'API, secret du webhook) chiffrés au repos, jamais dans le code ni dans l'app mobile.
- Jeton OAuth mis en cache jusqu'à son expiration, au lieu d'en demander un par appel.
- mTLS configuré avec le certificat fourni par votre participant.
- Alias de l'entreprise créé et rattaché au bon compte.
txIdstable et unique par opération, sans caractères spéciaux.- Seul
IRREVOCABLEdéclenche la livraison ou le crédit. - Webhook en HTTPS public, signature vérifiée sur le corps brut.
- Relecture périodique des opérations en attente, avec un délai d'abandon pour les demandes jamais validées.
- Solde vérifié avant chaque décaissement.
- Formulaires et messages qui parlent d'alias, pas de RIB.
Pour conclure
L'API de PI-SPI est sobre : un jeton, un alias, une demande, un statut. La difficulté est ailleurs, dans ce que l'API ne fait pas à votre place : attendre la validation du client, distinguer « confirmé » d'« irrévocable », survivre aux délais d'attente sans double débit, et ne pas croire un webhook sur parole. Si votre intégration traite ces quatre points, vous êtes prêt.
Le bac à sable est ouvert à tous : c'est le meilleur endroit pour vérifier chacun de ces comportements avant d'engager un vrai franc CFA.
Sources
- BCEAO, lancement de la Plateforme Interopérable du Système de Paiement Instantané
- BCEAO, communiqué du déploiement du sandbox de l'API Business (13 novembre 2025)
- Osiris, interopérabilité des paiements dans l'UEMOA : la BCEAO dresse un bilan d'étape
- allAfrica, PI-SPI : la BCEAO fait entrer l'Afrique de l'Ouest dans l'ère du paiement intégré
Développeur Full-Stack & Mobile à Cotonou, Bénin. Vous avez un projet web, mobile ou d'intégration de paiement en tête ?