SDK JavaScript 2.0.2

Le SDK ajoute un paiement CashChap à votre page en quelques lignes : il ouvre le widget par-dessus la page, sans redirection, puis vous rend le résultat confirmé par l'API v2. Aucune dépendance, un seul fichier, chargé une seule fois même s'il est inclus deux fois.

Installation

<script src="https://cdn.cashchap.com/v2/sdk.js"></script>

L'adresse https://cdn.cashchap.com/v2/sdk-2.0.2.js fige la version 2.0.2. Empreinte de ce fichier, pour vérifier une copie que vous hébergeriez vous-même : sha384-PO9WS5xBZTd5lAVcWfnXlbqE+uDVOaxj+t7rkK17uhHlAT1UQ4QTT55PgTGa5n1G (SHA-384, format SRI). Voir aussi Versions.

Le script expose window.CashChap (CashChap.version, CashChap.checkout(), CashChap.on()) et l'élément <cashchap-checkout>. Il n'utilise que votre clé publique : le mode (Live ou Sandbox) est celui de la clé.

Bouton prêt à l'emploi

<!DOCTYPE html>
<html lang="fr">
<head>
  <meta charset="utf-8">
  <title>Payer avec CashChap</title>
  <script src="https://cdn.cashchap.com/v2/sdk.js"></script>
</head>
<body>
  <cashchap-checkout
      data-public-key="VOTRE_CLE_PUBLIQUE"
      data-amount="2500"
      data-currency="XOF"
      data-reference="CMD-2026-00417"
      data-customer-name="Koffi Mensah"
      data-customer-email="koffi.mensah@example.com"
      data-return-url="https://www.votre-site.bj/paiement/retour"
      button-text="Payer 2 500 FCFA"></cashchap-checkout>

  <script>
    document.querySelector("cashchap-checkout").addEventListener("cashchap:success", function (e) {
      // e.detail.transaction : objet transaction de l'API v2 (données du client masquées).
      // Le navigateur ne prouve rien : confirmez côté serveur avant de livrer.
    });
  </script>
</body>
</html>

Attributs de l'élément

L'élément émet des événements DOM : cashchap:success, cashchap:error, cashchap:pending et cashchap:close, avec event.detail.transaction (et event.detail.error pour une erreur).

Ouvrir un paiement en JavaScript

CashChap.checkout({
  public_key: "VOTRE_CLE_PUBLIQUE",          // le mode (Live ou Sandbox) est celui de la clé
  amount: 2500,
  currency: "XOF",
  reference: "CMD-2026-00417",               // unique par commande : protège du double paiement
  customer: { name: "Koffi Mensah", email: "koffi.mensah@example.com", phone: "2290197000000" },
  metadata: { panier: "42" },
  return_url: "https://www.votre-site.bj/paiement/retour", // facultatif
  onSuccess: function (transaction) { /* transaction.status === "succeeded" */ },
  onError: function (erreur, transaction) { /* erreur.code, erreur.message (en français) */ },
  onPending: function (transaction) { /* confirmation encore attendue : ne relancez pas le paiement */ },
  onClose: function (transaction) { /* widget fermé ; transaction vaut null si rien n'a été payé */ }
}).then(function (resultat) {
  // resultat.status : succeeded | failed | expired | cancelled | pending | closed
});

Options

Un seul paiement est ouvert à la fois : un nouvel appel à CashChap.checkout() ferme le précédent.

Événements

CashChap.on("transaction.succeeded", function (transaction) { /* … */ });
CashChap.on("transaction.failed", function (transaction) { /* transaction.failure.message */ });
// Aussi : transaction.expired, transaction.cancelled, transaction.pending, checkout.closed

L'objet transaction est celui de l'API v2 (id, status, reference, amount, amount_charged = total payé par le client, fees, failure…), lu par le SDK avec votre clé publique : les données du client y sont masquées. Le deuxième argument des rappels indique sa source : {source: "api"}, ou {source: "widget"} si l'API n'a pas pu être lue.

Après le paiement

Avec return_url, le SDK renvoie le client vers votre page quand il ferme le widget (SDK 2.0.2 : le bouton devient « Fermer et revenir au site du marchand »), en ajoutant trois paramètres :

https://www.votre-site.bj/paiement/retour
    ?transaction_id=2f1c3b6e-9a0d-4c1e-8f5a-2b7d9e4c6a10
    &reference=CMD-2026-00417
    &status=succeeded

Avec le SDK 2.0.2, le widget ne se ferme plus de lui-même : il garde à l'écran le reçu détaillé, le QR code d'authentification, « Télécharger la facture » et le QR code de la facture, jusqu'à ce que le client touche Fermer ou ✕. Vos rappels (onSuccess, onError, onPending), les événements et la promesse partent dès le résultat, sans attendre la fermeture ; onClose suit la fermeture. Pour fermer plus tôt, appelez CashChap.close(). Avec le SDK 2.0.1, le widget se ferme 5 secondes après le résultat et return_url redirige aussitôt. Appuyez-vous sur onSuccess pour l'affichage et sur un webhook ou la lecture de la transaction côté serveur pour la commande.

Paiement encore en attente

Le client valide sur son téléphone : cela peut prendre du temps. Si la confirmation tarde, le widget l'indique au client (« Vérifier à nouveau ») et le SDK appelle onPending(transaction) (événement transaction.pending). Le paiement peut encore aboutir : ne le traitez pas comme un échec et ne relancez pas un second paiement. Suivez la transaction depuis votre serveur, comme décrit dans Confirmer un paiement.

Erreurs d'intégration

Options invalides (clé, montant, devise, adresse de retour…) : le SDK écrit le problème en français dans la console du navigateur, appelle onError avec {code: "invalid_options", message}, rejette la promesse avec la même erreur et n'ouvre aucune fenêtre. Testez votre page avec la console ouverte. Les refus de l'API arrivent dans onError avec le code et le message de l'API v2.

Sécurité

• Le widget s'ouvre dans un cadre sur https://payment.cashchap.com ; le SDK n'écoute que les messages de cette origine et de ce cadre.
• Le SDK n'injecte aucune bibliothèque tierce. Si votre site applique une politique de sécurité du contenu (CSP), autorisez script-src https://cdn.cashchap.com, frame-src https://payment.cashchap.com et connect-src https://api.cashchap.com (voir CSP marchande).
• Seule la clé publique figure dans la page. La clé secrète reste sur votre serveur.

Reçu du client dans le widget

Après un paiement réussi, le widget affiche le reçu complet avec son QR code d'authentification et propose au client Télécharger le reçu (image PNG), Partager (WhatsApp, SMS…) si son téléphone le permet, Télécharger la facture et le QR code de la facture : voir Reçu du client et Reçus et vérification. Le SDK 2.0.2 ouvre le widget dans un cadre autorisé à partager (allow="payment; web-share") ; avec le SDK 2.0.1, le bouton Partager reste masqué et le reçu se télécharge.

Si votre page envoie un en-tête Permissions-Policy qui restreint web-share, autorisez-le pour le domaine des paiements, sinon le bouton Partager restera masqué :