@bjpay/js

Chargement du widget de paiement BjPay — noyau sans framework.

Pour React, préférez @bjpay/react, qui ajoute le cycle de vie.

Installation

npm install @bjpay/js

Usage

import { loadBjPay } from "@bjpay/js";

const bjpay = await loadBjPay({
  baseUrl: "https://bjpay-staging.service-public.bj/widget/v2",
});

bjpay.pay({
  token: "…",                    // obtenu par VOTRE serveur auprès de TresorPay
  merchant: "Direction Générale des Impôts",
  title: "Quittance — Impôt foncier 2026",
  ref: "BJ-2026-00482",
  amount: 5000,
  currency: "XOF",
  onSuccess: ({ transaction, ref }) => { /* … */ },
  onError:   ({ reason, code })     => { /* … */ },
  onClose:   ({ reason, completed }) => { /* … */ },
});

bjpay.close() ferme la modale depuis votre code.

baseUrl n'a pas de valeur par défaut

C'est délibéré : cette valeur décide vers quel déploiement part le paiement. Un défaut sur la production ferait engager de vrais débits à une intégration de recette qui aurait oublié de le surcharger — et le symptôme n'apparaîtrait qu'après débit.

C'est l'URL sous laquelle le widget est publié, soit tout ce qui précède /bjpay.min.js. Elle peut comporter un préfixe de chemin.

Ce que ce paquet fait, et ne fait pas

Il charge le loader servi par le déploiement et en rend l'API. Il ne réimplémente rien du protocole de paiement : contrôle d'origine, anti-rejeu, cycle de vie de la modale et contrat d'événements restent dans le loader.

Ce n'est pas un détail d'architecture. Le loader est servi sans version dans l'URL et sans cache long, pour qu'un correctif de sécurité atteigne tous les marchands au prochain chargement de page. Un loader figé dans ce paquet aurait rendu cette promesse fausse : chaque marchand serait resté sur la version installée jusqu'à ce qu'il pense à monter de version.

Ce paquet pose donc une vraie balise <script> plutôt que d'importer le loader. Le loader déduit l'origine du widget de sa propre balise et refuse de s'ouvrir quand il n'en trouve pas — un import par bundler est exactement ce cas. La balise lui rend ce dont il a besoin sans affaiblir sa règle.

Rendu côté serveur

L'import est sans effet sur le serveur. loadBjPay doit être appelé au montage du composant, jamais pendant le rendu serveur : il lève alors une erreur qui nomme la cause, plutôt qu'un document is not defined.

bjpay:success ne vaut pas preuve de paiement

C'est un événement de navigateur, émis par une page que vous ne contrôlez pas. Confirmez toute transaction côté serveur auprès de TresorPay avant de livrer un service ou de marquer une commande comme réglée.

Licence

MIT