@pi-spi/checkout

SDK JavaScript pour le paiement en ligne PI-SPI. Offre une expérience de checkout unifiée pour les sites e-commerce (boutiques en ligne, marketplaces) dans l’espace UEMOA.

Installation

npm install @pi-spi/checkout

Utilisation

import { mountCheckout } from '@pi-spi/checkout';

const instance = mountCheckout({
  container: '#checkout-pispi',
  amount: 15000, // centimes
  orderId: 'CMD-2025-001',
  motif: 'Achat librairie',
  createPaymentRequest: async (payload) => {
    const res = await fetch('/api/demandes-paiements-online', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(payload),
    });
    if (!res.ok) throw new Error((await res.json()).detail || 'Erreur');
    return res.json();
  },
  getPaymentStatus: async (txId) => {
    const res = await fetch(`/api/demandes-paiements-online/${txId}`);
    return res.json();
  },
});

// Pour détruire le widget plus tard :
// instance.unmount();

Le widget affiche toujours un bouton « Payer avec » suivi du logo PI-SPI (logos intégrés au plugin). La seule option visuelle pour l'intégrateur est la couleur de fond du bouton ; le plugin choisit alors automatiquement le variant de logo adapté : (fond clair → amber/marron ; fond sombre → blanc / négatif). Au clic, un popup de paiement s’ouvre avec :

• En-tête : logo PI-SPI (centré ou à gauche, option modalLogoPosition) et montant total à payer (option currencyLabel pour la devise).
• Stepper 1–2–3 : (1) Alias — le client saisit ou colle son alias / scanne ou choisit une photo QR (si le QR est valide, l’envoi est déclenché automatiquement) ; (2) Paiement en attente — après envoi, message « En attente de l’acceptation de la demande de paiement » ; (3) Terminé — coche verte et message « Paiement réussi », bouton Fermer.
• À la fermeture du popup (Annuler, clic à l’extérieur, ou Fermer après succès), le callback onClose(result) est appelé avec { success: boolean, invoiceUrl?: string } pour que le système sache si le paiement a abouti ou a été annulé.

Couleur du bouton

Optionnel : buttonBackgroundColor (hex, ex. #F2A900 ou #1a1a1a). Par défaut #F2A900. Le plugin choisit automatiquement la variante du logo selon le fond :

| Fond | Variante du logo | |------|------------------| | Amber (ex. #F2A900) | Version_sur_Fond_Variant_2 | | Marron / noir | Version_sur_Fond_Variant_1 | | Blanc | Variant 1 ou Variant 2 | | Tout autre fond coloré | Négatif |

Ce qu’attend le plugin du marchand

Le plugin appelle createPaymentRequest(payload) avec { payeurAlias, montant, orderId?, motif? }. Le marchand doit implémenter cette fonction pour :

1. Contacter son propre backend (ex. POST /api/demandes-paiements-online ou POST /demandes-paiements-sites selon son API).
2. Pendant l’appel : le plugin affiche « Envoi de la demande en cours » (étape 1, loader).
3. Quand le backend répond : le backend du marchand doit lui-même appeler l’API Business du participant (PI-SPI) pour envoyer la demande de paiement en ligne. Il renvoie au front au minimum { txId, payeurNom? }.
4. Après réception de la réponse : le plugin passe à l’étape 2 « Paiement en attente » avec le message « En attente de l’acceptation de la demande de paiement » (le client accepte sur l’application de son institution).
5. Si le marchand fournit getPaymentStatus(txId), le plugin fait un polling ; lorsque le statut est IRREVOCABLE, il affiche l’étape 3 (succès) et optionnellement un lien vers la facture (invoiceUrl).

Exemple de backend marchand : piz-sample-business-api (POST /demandes-paiements-sites) qui reçoit le payload et contacte l’API Business du participant pour créer la demande.

Options

| Option | Type | Description | |--------|------|-------------| | container | string \| HTMLElement | Sélecteur ou élément où monter le bouton | | amount | number | Montant en centimes | | orderId | string | Identifiant de commande (optionnel) | | motif | string | Motif du paiement (optionnel) | | buttonBackgroundColor | string | Couleur de fond du bouton en hex (défaut: #F2A900). Détermine le variant du logo. | | createPaymentRequest | (payload) => Promise<response> | Appel au backend pour créer la demande | | getPaymentStatus | (txId) => Promise<status> | Optionnel : polling du statut | | decodeQrPayload | (qrPayload) => { alias } \| null | Optionnel : décodage QR personnalisé | | pollIntervalMs | number | Intervalle de polling (défaut: 3000) | | onClose | (result: { success, invoiceUrl? }) => void | Callback à la fermeture du popup (succès ou annulation) | | modalLogoPosition | 'center' \| 'left' | Position du logo dans le popup (défaut: center) | | currencyLabel | string | Libellé devise pour le montant (défaut: "F CFA") |

Script tag (UMD)

Pour une intégration sans bundler :

<script src="https://unpkg.com/@pi-spi/checkout/umd"></script>
<script>
  PispiCheckout.mountCheckout({ ... });
</script>

Licence

MIT · BCEAO - PI-SPI