·9 min read

PI-SPI: what developers need to know before integrating the BCEAO's instant payment system

What PI-SPI is, how its Business API works, and the pitfalls I hit integrating it for real: authentication, aliases, requests to pay, statuses, webhooks.

PI-SPIBCEAOPaymentsWAEMUAPIFintech

In the West African Economic and Monetary Union (WAEMU, or UEMOA in French), paying someone whose account sits at another bank, or moving money from a bank to a mobile wallet, has long meant waiting, paying fees or going through a middleman. PI-SPI changes that. I integrated its Business API into a payment application, from the OAuth token all the way to refund payouts. Here is what I wish I had known before starting.

PI-SPI in two minutes

PI-SPI (Plateforme Interopérable du Système de Paiement Instantané, the interoperable instant payment platform) is the instant payment infrastructure of the BCEAO, the central bank of the eight WAEMU countries. It officially launched on 30 September 2025, after a pilot phase opened to real users from June 2025.

In practice:

  • Instant and always on: a transfer lands in seconds, 24/7.
  • Interoperable: banks, electronic money issuers (EMIs) and other authorised institutions all sit on the same rail. A customer of one bank can pay a customer of another institution with no middleman.
  • Aliases instead of account numbers: you pay an alias, an identifier linked to the account, instead of sharing your account number.
  • Interoperable QR code: the same QR code can be paid from any participating institution.

The number of connected institutions is growing fast: the BCEAO reported 80 connected participants in spring 2026.

For developers, the entry point is the Business API, with a public sandbox the BCEAO opened on 13 November 2025 (developer portal: developer.pispi.bceao.int). That is what I used.

A note on vocabulary: PI-SPI is a French-language system, and its API keeps French names for paths, fields and statuses (demandes-paiements, montant, IRREVOCABLE…). I keep them as they are in the code below, and translate them in the text.

Who talks to whom

Your back end calls your participant's Business API, which goes through PI-SPI to the customer's bank; the result comes back through a signed webhook.
Your back end calls your participant's Business API, which goes through PI-SPI to the customer's bank; the result comes back through a signed webhook.

The first surprise: a business does not connect to the BCEAO. It is a client of a participant (its bank or EMI), and that participant's gateway exposes the Business API. In the sandbox, the portal assigns you a virtual participant, with its code (something like BJBxxx), an account and credentials.

Money moves in two directions:

NeedPI-SPI operationWho approves?
Collect (the customer pays you)a request to pay (RTP, demandes-paiements)the customer, in their bank's app
Pay out (you pay someone: refund, merchant payout)a sent payment (paiements-envoyes)you, by issuing it

The alias: the only identifier that matters

PI-SPI does not debit or credit an account from a bank account number (RIB) or an IBAN. It works with aliases. The Business API uses the SHID alias type: a random 36-character key in UUID format, attached to an account.

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());
// Form sent to the API: lowercase, no surrounding spaces.
export const normalizeAlias = (value: string) => value.trim().toLowerCase();

What this means for your product:

  • Your "Add a bank account" form must ask for the alias, not the account number. If you keep an account-number field, reject it clearly at payment time instead of trying to guess.
  • Your business also needs an alias, attached to its own account: it is the payeAlias (payee) of your collections and the payeurAlias (payer) of your payouts. You create it through the API (POST /comptes/{numero}/alias with type SHID).
  • Looking up an alias returns the holder's identity (name, country, category), never their balance. So don't show a "balance" for a bank account linked through PI-SPI: your application cannot know it.

Authenticating: OAuth2 plus an API key

Every call carries two things: an OAuth2 token obtained with client_credentials, and the x-api-key header. Production adds mTLS (a client certificate); the sandbox offers a non-mTLS URL to get started.

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!,
      // Only the scopes granted to your client (see the pitfalls below).
      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(`PI-SPI authentication refused (${res.status})`);

  const { access_token, expires_in } = await res.json();
  // Keep a one-minute margin before expiry.
  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),
  });
}

Notice the participant code prefixing every path. Not all of the documentation says so, and it is the first pitfall (see below).

All of these secrets stay server-side. A mobile app must never call PI-SPI directly: it calls your back end, which calls PI-SPI.

Collecting: the request to pay

Sequence: token, request to pay created, shown to the payer by their bank, approval, webhook, status re-read until IRREVOCABLE.
Sequence: token, request to pay created, shown to the payer by their bank, approval, webhook, status re-read until IRREVOCABLE.

To collect, you create a request; the payer's bank shows it to them, and they approve it.

ts
const res = await pispi('POST', '/demandes-paiements', {
  txId: 'ORD-2026-000123',          // YOUR reference, unique (see idempotency)
  categorie: '500',                 // "on-site" request
  payeurAlias: normalizeAlias(customerAlias),
  payeAlias: BUSINESS_ALIAS,
  montant: 5000,                    // amount in CFA francs (XOF), integer
  motif: 'Order 123',               // description
  confirmation: false,
});
// 201: the request exists, status INITIE (initiated). Nothing has been paid yet.

The payment is not done when the call returns. The request waits for the customer's approval, which can take a few seconds… or never come. Your order therefore stays "pending" until a final status.

Paying out: the sent payment

To pay someone (a refund, a merchant payout), the roles flip: you are the payer.

ts
await pispi('POST', '/paiements-envoyes', {
  txId: 'REFUND-000042',
  payeurAlias: BUSINESS_ALIAS,
  payeAlias: normalizeAlias(recipientAlias),
  montant: 4000,
  motif: 'Refund for order 123',
  confirmation: false,
});

Before sending, read your account balance: GET /comptes/{numero} returns a solde (balance) field. A payout refused for insufficient funds is easier to handle before sending than after.

Statuses: only one means "paid"

INITIE, ENVOYE and CONFIRME are pending; IRREVOCABLE is the only final success; REJETE and ANNULE are failures.
INITIE, ENVOYE and CONFIRME are pending; IRREVOCABLE is the only final success; REJETE and ANNULE are failures.

You re-read an operation with GET /demandes-paiements/{txId} or GET /paiements-envoyes/{txId}. Its statut field translates as follows:

ts
type Outcome = 'paid' | 'failed' | 'pending';

function outcome(statut?: string): Outcome {
  if (statut === 'IRREVOCABLE') return 'paid';                       // the only final success
  if (statut === 'REJETE' || statut === 'ANNULE') return 'failed';   // rejected / cancelled: read statutRaison
  return 'pending';                                                  // INITIE, ENVOYE, CONFIRME
}

Two rules that prevent costly mistakes:

  1. 01.CONFIRME (confirmed) is not IRREVOCABLE. Ship nothing and credit nothing before IRREVOCABLE.
  2. 02.A 404 when re-reading is not a failure. A very recent operation may not be visible yet: treat it as pending and re-read later.

Idempotency: txId is your best friend

PI-SPI refuses a txId that was already used (reason code DU03). That is great news: if your call times out and you don't know whether the request went through, send it again with the same txId. Either it gets created, or PI-SPI answers "already received" and you re-read its status. You never debit twice.

ts
if (res.status === 409 || body?.statutRaison === 'DU03') {
  return rereadStatus(txId);   // it already exists: its outcome is its status
}

So use a stable reference derived from your own object (order, refund), never an identifier you randomly generate on each attempt.

Webhooks: a trigger, not proof

You register a callback URL (POST /webhooks). PI-SPI sends events { data: [{ evCode, txId, end2endId, … }] } to it, signed in the X-Signature header: an HMAC-SHA256 of the raw body with a secret given to you only once, at registration. Store it right away.

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));
}

Three tips:

  • Compute the signature on the raw body, before any JSON parsing. A body rewritten by your framework no longer matches the signature.
  • Never trust the webhook's content to confirm a payment. Use it to know which operation to re-read, then re-read its status through the API.
  • Plan a periodic re-read of pending operations. A webhook can get lost; your system must not get stuck because of it.

Sandbox pitfalls

This is what I observed by actually calling the sandbox, where the documentation said otherwise. Guides evolve, so check your own environment, but if a call fails for no obvious reason, look here first.

  1. 01.Paths are prefixed by the participant code: /{CODE}/comptes/…, as in the portal's Playground. With the /v1 prefix some guides mention, I got a 403 or sub-routes that could not be found.
  2. 02.Only request the scopes you were granted. If the list contains a single scope you don't have (participant.read in my case), the whole token request is refused with a 400. Scopes are prefixed with piz/.
  3. 03.The balance is the solde field of GET /comptes/{numero}. There is no dedicated /solde route.
  4. 04.Request category 500 rejects dateLimitePaiement (payment deadline). Don't send a deadline for an "on-site" request: PI-SPI expires it on its own.
  5. 05.txId must survive a URL. My references started with #; once encoded (%23…), the txId could no longer be found on re-read (404), and the request would have stayed "pending" forever. Stick to A-Z a-z 0-9 _ -, and keep exactly that txId as your own reference: it is what the re-read and the webhook send back.
  6. 06.Errors follow RFC 7807: when a request is refused, read detail (then title) for a message you can display.

Going to production: the checklist

  • Secrets (client secret, API key, webhook secret) encrypted at rest, never in the code or the mobile app.
  • OAuth token cached until it expires, instead of requesting one per call.
  • mTLS set up with the certificate provided by your participant.
  • Business alias created and attached to the right account.
  • A stable, unique txId per operation, with no special characters.
  • Only IRREVOCABLE triggers shipping or crediting.
  • Webhook on public HTTPS, signature checked against the raw body.
  • Periodic re-read of pending operations, with a timeout for requests that are never approved.
  • Balance checked before every payout.
  • Forms and messages that talk about aliases, not account numbers.

Wrapping up

The PI-SPI API is lean: a token, an alias, a request, a status. The hard part lies elsewhere, in what the API does not do for you: waiting for the customer's approval, telling "confirmed" from "irrevocable", surviving timeouts without double debits, and not taking a webhook at its word. If your integration handles those four points, you're ready.

The sandbox is open to everyone: it is the best place to check each of these behaviours before moving a single real CFA franc.

Sources

Cyrille Adjalala

Full-Stack & Mobile Developer in Cotonou, Benin. Have a web, mobile, or payment integration project in mind?

Contact me