SDK JavaScript
Ajoutez un bouton de paiement NguePay à votre site en 2 lignes de code, sans backend.
Installation
Ajoutez le script depuis notre CDN — en production :
<script src="https://cdn.live.nguepay.com/nguepay.min.js"></script>En recette (clés pk_sandbox_), chargez-le depuis https://cdn.sandbox.nguepay.com/nguepay.min.js. Le SDK choisit l'API et la page de paiement d'après le préfixe de votre clé — pk_sandbox_ → api.sandbox.nguepay.com / pay.sandbox.nguepay.com pour vos tests, pk_live_ → api.live.nguepay.com / pay.live.nguepay.com en production. Le SDK n'utilise que votre clé publique, et celle-ci exige un domaine déclaré — voir Authentification.
NguePay.init()
const paiement = NguePay.init({
publicKey: 'pk_live_...',
amount: 5000,
reference: 'commande_001',
provider: 'orange', // facultatif : sinon le client choisit (orange ou stripe)
onSuccess: (txn) => console.log('Payé ✓', txn.uuid),
onError: (err) => console.error(err)
});
paiement.open();Le SDK crée une session de paiement avec votre clé publique, puis ouvre la page NguePay dans une fenêtre superposée. Options facultatives : currency (XOF), phone, customerEmail, description, metadata.
metadata accepte 20 clés et 4 Ko au plus. Si vous y placez un return_url, il doit avoir la même origine que le domaine déclaré sur la clé publique, sinon la session est refusée.Ce que reçoivent vos callbacks
Le résultat du paiement arrive par postMessage depuis l'iframe NguePay. Le SDK n'en transmet que trois champs, et rien d'autre : ni montant, ni opérateur, ni métadonnées.
| Callback | Quand | Argument |
|---|---|---|
onOpen(session) | La session est créée et la fenêtre ouverte. | La réponse de POST /checkout/sessions : { uuid, checkout_url, expires_at, status }. |
onSuccess(payload) | La page de succès NguePay s'affiche. La fenêtre se ferme ensuite d'elle-même. | { uuid, status, reference } — status vaut succeeded. |
onError(payload) | La page d'échec NguePay s'affiche. La fenêtre reste ouverte (le client peut réessayer ou revenir). | { uuid, status, reference } — status vaut failed ou expired, voire pending si un nouvel essai reste possible. |
onError(error) | La session n'a pas pu être créée (clé, domaine, montant, réseau…). | { message } seulement : ni uuid, ni error_code. |
onClose() | À chaque fermeture : bouton ✕, clic hors de la fenêtre, touche Échap, page « paiement annulé », et aussi juste après onSuccess. | Aucun. |
uuidest l'identifiant de la transaction — celui deGET /payments/{uuid}et du champtransaction_iddes webhooks.referenceest votre référence de commande.- Un abandon (page « paiement annulé ») ne déclenche que
onClose(), sans argument : rien ne le distingue d'une fermeture par le client. - Le SDK n'accepte un message que de la page qu'il a ouverte, depuis l'origine de checkout de l'environnement de la clé, et portant l'
uuidde sa session. La page NguePay ne l'émet que vers le domaine déclaré sur la clé.
onSuccess sert à l'affichage. Ne livrez jamais sur ce seul signal : c'est le webhook reçu par votre serveur qui fait foi — ou, à défaut, GET /payments/{uuid} appelé depuis votre serveur avec l'uuid reçu.Événements sur window
Le SDK émet aussi des CustomEvent sur window, utilisables avec addEventListener ou paiement.on('success' | 'error' | 'open' | 'close', cb) — cb reçoit alors event.detail. Ces écouteurs sont globaux à la page, pas propres à une instance.
| Événement | detail |
|---|---|
nguepay:open | { transaction: { uuid, checkout_url, expires_at, status } } |
nguepay:success | { uuid, status, reference } |
nguepay:error | { uuid, status, reference }, ou { message } si la session n'a pas pu être créée |
nguepay:close | aucun (null) |
URL de retour avec le SDK
Le SDK ne transmet pas de return_url de premier niveau : pour proposer un bouton de retour sur les pages d'échec et d'annulation, placez-la dans metadata.return_url (même domaine que la clé). Comme pour un paiement serveur, elle est utilisée telle quelle, sans paramètre ajouté. Dans l'iframe, la page de succès ne redirige pas : c'est onSuccess qui vous rend la main ; les boutons de retour, eux, ouvrent l'URL dans la fenêtre principale.
Erreurs de configuration
NguePay.init() vérifie la configuration avant tout appel et lève une exception (Error, message préfixé [NguePay]) si publicKey ne commence pas par pk_, si amount n'est pas un nombre entre 100 et 5 000 000, ou si reference manque ou dépasse 100 caractères (l'API en accepte 150). Le SDK n'expose pas de code d'erreur : seul message est transmis.
Data-attributes (sans JS)
Pour les intégrations les plus simples, un bouton suffit :
<button
data-nguepay-key="pk_live_..."
data-nguepay-amount="5000"
data-nguepay-reference="commande_001">
Payer 5 000 XOF
</button>Le bouton émet les événements DOM nguepay:success et nguepay:error (qui remontent le DOM, detail identique au tableau ci-dessus), en plus des événements sur window. Attributs reconnus : data-nguepay-key, data-nguepay-amount, data-nguepay-reference et data-nguepay-currency. data-nguepay-webhook est lu mais ignoré : une page publique ne choisit pas où partent vos notifications.