Retour aux articles
Lire cet article en :FREN
·9 min de lecture

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.

PI-SPIBCEAOPaiementsUEMOAAPIFintech

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

Votre back-end appelle l'API Business de votre participant, qui passe par PI-SPI jusqu'à la banque du client ; le résultat revient par webhook signé.
Votre back-end appelle l'API Business de votre participant, qui passe par PI-SPI jusqu'à la banque du client ; le résultat revient par webhook signé.

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 :

BesoinOpération PI-SPIQui 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.

ts
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 payeAlias de vos encaissements et le payeurAlias de vos décaissements. Il se crée par l'API (POST /comptes/{numero}/alias avec le type SHID).
  • 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.

ts
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

Séquence : jeton, création de la demande de paiement, présentation au payeur par sa banque, validation, webhook, relecture du statut jusqu'à IRREVOCABLE.
Séquence : jeton, création de la demande de paiement, présentation au payeur par sa banque, validation, webhook, relecture du statut jusqu'à IRREVOCABLE.

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.

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

ts
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é »

INITIE, ENVOYE et CONFIRME sont des attentes ; IRREVOCABLE est le seul succès final ; REJETE et ANNULE sont des échecs.
INITIE, ENVOYE et CONFIRME sont des attentes ; IRREVOCABLE est le seul succès final ; REJETE et ANNULE sont des échecs.

On relit une opération par GET /demandes-paiements/{txId} ou GET /paiements-envoyes/{txId}. Le champ statut se traduit ainsi :

ts
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 :

  1. 01.CONFIRME n'est pas IRREVOCABLE. Ne livrez rien, ne créditez rien avant IRREVOCABLE.
  2. 02.Un 404 sur 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.

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

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

  1. 01.Les chemins sont préfixés par le code du participant : /{CODE}/comptes/…, comme dans le Playground du portail. Avec le préfixe /v1 de certains guides, j'obtenais un 403 ou des sous-routes introuvables.
  2. 02.Ne demandez que les scopes qui vous sont accordés. Si la liste contient un seul scope non accordé (participant.read dans mon cas), toute la demande de jeton est refusée en 400. Les scopes sont préfixés par piz/.
  3. 03.Le solde est le champ solde de GET /comptes/{numero}. Il n'y a pas de route /solde dédiée.
  4. 04.La catégorie de demande 500 refuse dateLimitePaiement. N'envoyez pas de date limite pour une demande « sur site » : PI-SPI la fait expirer de lui-même.
  5. 05.Le txId doit survivre à une URL. Mes références commençaient par # ; une fois encodé (%23…), le txId n'é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 ce txId comme référence chez vous : c'est lui que renvoient la relecture et le webhook.
  6. 06.Erreurs au format RFC 7807 : en cas de refus, lisez detail (puis title) 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.
  • txId stable et unique par opération, sans caractères spéciaux.
  • Seul IRREVOCABLE dé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

Cyrille Adjalala

Développeur Full-Stack & Mobile à Cotonou, Bénin. Vous avez un projet web, mobile ou d'intégration de paiement en tête ?

Me contacter