Widget de paiement

Le widget est le formulaire de paiement hébergé par CashChap sur https://payment.cashchap.com, le domaine unique des paiements. Le SDK l'ouvre par-dessus votre page ; les liens de paiement CashChap Link et les QR codes l'utilisent aussi. Vous n'avez rien à héberger ni à mettre à jour.

Parcours du client

Ouverture : le SDK affiche le widget dans un cadre, fenêtre centrée sur ordinateur et plein écran sur téléphone, et lui transmet le prix, la devise, votre clé publique, votre référence et, s'ils sont fournis, les coordonnées du client.
Moyen de paiement : trois étapes s'affichent (Opérateur, Coordonnées, Validation). Le widget présente un onglet par moyen de paiement ouvert pour votre service : aujourd'hui, Mobile Money seul (la carte bancaire n'est pas encore ouverte et n'apparaît donc pas) ; seuls les opérateurs ouverts pour votre service y sont proposés ; le client choisit son opérateur, puis saisit son nom, son adresse e-mail et son numéro Mobile Money, dont l'opérateur est reconnu. Le payeur tape son numéro national (01 66 00 00 00) : l'indicatif du pays du moyen choisi est affiché à côté du champ (+229), et la page l'ajoute devant le numéro, sans « + », avant l'envoi (2290166000000).
Total : le client voit le total exact qu'il paiera, calculé par CashChap (frais à sa charge et arrondi au 5 F compris), dans « Montant à payer » et sur le bouton Payer, avant de confirmer. Les montants sont dans la devise de votre service : un prix envoyé par le SDK dans une autre devise est converti pour le client, qui ne voit jamais le XOF prélevé par l'opérateur.
Validation : la demande part vers l'opérateur ; l'écran « Validez le paiement sur votre téléphone » invite le client à composer son code secret. Le widget suit le résultat en temps réel.
Attente : si la confirmation tarde, l'écran « Confirmation en attente » indique que le paiement peut encore aboutir et propose Vérifier à nouveau ; le SDK vous prévient (onPending).
Fin : succès (« Paiement effectué », « Merci ! Vous pouvez fermer cette page. » ; « Succès ! » dans le widget ouvert par le SDK), avec le reçu à télécharger ou partager et la facture, ou échec affiché avec un message en français. Avec le SDK 2.0.2, le widget reste sur cet écran jusqu'à ce que le client le ferme, puis le renvoie à votre page s'il y a une adresse de retour.

Fenêtre de navigateur de 1920 pixels : le widget CashChap ouvert par le SDK depuis la page produit de « Boutique Démo ». Le widget occupe toute la fenêtre : son fond bleu nuit recouvre la page du marchand, et la fenêtre Paiement sécurisé est centrée, avec le bouton ✕, le bandeau « Mode test : aucun argent réel ne sera débité. », montant à payer 15 000 XOF, étapes Opérateur, Coordonnées, Validation, un seul onglet Mobile Money, choix de l'opérateur MTN ou MOOV, nom Koffi Mensah et e-mail koffi.mensah@example.com déjà remplis par le SDK, champ du numéro Mobile Money avec l'indicatif +229, bouton Payer et pied Propulsé par CashChap. — Le widget ouvert par le SDK sur ordinateur, au-dessus de la page du marchand qu'il recouvre, avec les coordonnées du client transmises par le site (clé publique Sandbox, d'où le bandeau « Mode test »).

Sur téléphone, le parcours est le même, en plein écran ; ci-dessous, celui de la page de paiement d'un lien de paiement (la page ouverte par « Procéder au paiement »), identique, joué en mode test par un même payeur, Koffi Mensah. Il tape son numéro national à côté de l'indicatif +229 : l'écran affiche « +229 01 66 00 00 00 », et la page l'envoie à l'API au format international sans « + », 2290166000000. Les écrans 1 à 3 utilisent le numéro de test 01 66 00 00 00 (paiement réussi), l'écran 4 le numéro de test 01 66 00 00 01 (confirmation tardive) :

Étape 1 sur téléphone : montant à payer 15 000 XOF, étapes Opérateur, Coordonnées, Validation, un seul onglet Mobile Money, choix de l'opérateur MTN ou MOOV, puis les champs vides Nom et prénom(s), Adresse e-mail et Numéro Mobile Money avec l'indicatif +229, le bouton Payer et le pied Propulsé par CashChap. — 1. Le client choisit son opérateur.

2. Coordonnées et total exact, frais compris (1,7 %, arrondi au 5 F supérieur).

Étape 3 sur téléphone, en mode test : en-tête Paiement sécurisé sans bouton ✕, montant à payer 15 255 XOF dont 255 XOF de frais, étapes Opérateur et Coordonnées cochées, écran Validez le paiement sur votre téléphone, demande envoyée au +229 01 66 00 00 00 via MTN, montant 15 255 XOF, compteur En attente depuis 0:02, consigne Ne fermez pas cette fenêtre avant la confirmation. — 3. Validation sur le téléphone du client.

Écran Confirmation en attente sur téléphone, en mode test : bandeau Montant à payer 15 255 XOF dont 255 XOF de frais, message « Nous n'avons pas reçu la confirmation de l'opérateur. Si vous avez validé sur votre téléphone, le paiement peut encore aboutir : vous recevrez un reçu. », récapitulatif (marchand Boutique Démo, service Boutique en ligne, montant 15 255 XOF, opérateur MTN, numéro +229 01 66 00 00 01, date, référence), boutons Vérifier à nouveau et Fermer. — 4. Confirmation en attente : « Vérifier à nouveau ». Cet écran a été obtenu avec le numéro de test 01 66 00 00 01 (scénario « en attente »).

Reçu du client

Après un paiement réussi, l'écran final affiche le reçu complet, dans le widget ouvert par le SDK comme sur la page d'un CashChap Link ou d'un QR code : logo et nom public du marchand, service, adresse, téléphone et e-mail de l'entreprise, produit ou motif, montant demandé, frais, total payé, moyen et opérateur, numéro complet sans « + » (« 229 01 66 00 00 00 »), nom et prénom du payeur, son e-mail s'il l'a donné, canal (lien, QR code de la boutique, caisse et nom de la caisse, site du marchand), date et heure de Porto-Novo, n° de reçu, références CashChap, opérateur et commande, et la mention « Mode test » en Sandbox. Puis :

le QR code d'authentification (« Vérifier ce reçu ») : il ouvre la page publique de vérification sur cashchap.com, qui confirme le paiement (« Paiement authentique », ou « Paiement de test » en Sandbox) ou répond « Reçu introuvable » pour un reçu modifié ;
Télécharger le reçu : une image PNG nette (recu-cashchap-<n° de reçu>.png, 1080 pixels de large) avec toutes ces informations et le QR code d'authentification. L'image est préparée sur l'appareil du client : elle ne le quitte pas ;
Partager : ouvre le partage du téléphone avec l'image du reçu en pièce jointe (WhatsApp, SMS, e-mail…). Le bouton n'apparaît que si le navigateur sait partager un fichier ; sinon le reçu se télécharge ;
Télécharger la facture (PDF), pour tout paiement réussi, et un QR code de la facture : le client la télécharge sur son téléphone en le scannant (affiché dans le widget, et sur grand écran pour la page d'un lien).

Le détail de chaque rubrique, la page de vérification et la facture sont décrits dans Reçus et vérification.

Avec le SDK 2.0.2, le widget reste ouvert sur cet écran jusqu'à ce que le client le ferme (Fermer en bas de l'écran, ou ✕ en haut) : il a le temps de télécharger son reçu, de le partager, de télécharger la facture ou de scanner l'un des QR codes. Vos rappels (onSuccess…) et la promesse sont rendus dès le résultat, sans attendre la fermeture ; avec une adresse de retour, le bouton devient « Fermer et revenir au site du marchand » et la redirection a lieu à la fermeture. Avec le SDK 2.0.1, le bouton Partager reste masqué et le widget se ferme 5 secondes après le résultat. Le reçu ne remplace pas la vérification du paiement par votre serveur : voir Sécurité du widget.

1. L'écran de succès du widget ouvert par le SDK 2.0.2 sur téléphone : le reçu complet.

Suite du même écran de succès, en faisant défiler : fin du reçu (Payeur Koffi Mensah, E-mail koffi.mensah@example.com, Canal Site du marchand, Date 12 octobre 2026 à 04 h 13 (heure de Porto-Novo), N° de reçu 2529A2B85F79, Réf. CashChap, Réf. opérateur, Réf. commande CMD-2026-24294), bloc « Reçu authentifié par CashChap » avec le QR code d'authentification, « Scannez ce QR code pour vérifier ce paiement sur cashchap.com. » et le lien Vérifier ce reçu, boutons Télécharger le reçu et Partager, bouton Télécharger la facture, bloc « Facture sur votre téléphone » avec le QR code de la facture et « Scannez ce QR code avec l'appareil photo de votre téléphone pour télécharger la facture (PDF). », bouton Fermer et pied Propulsé par CashChap. — 2. Plus bas : le QR code d'authentification, « Télécharger le reçu », « Partager », « Télécharger la facture », le QR code de la facture et « Fermer ».

Fenêtre de navigateur de 1920 pixels : le widget ouvert par le SDK 2.0.2 sur le site de Boutique Démo, au-dessus de son fond bleu nuit, après un paiement réussi en mode test, défilé jusqu'en bas : reçu à partir des coordonnées du marchand (adresse, Tél. 229 01 95 00 00 07, e-mail), mention Mode test, Produit Robe en wax, Montant 15 000 XOF, Frais 255 XOF, Total payé 15 255 XOF, Moyen MTN Mobile Money, Numéro 229 01 66 00 00 00, Payeur Koffi Mensah, E-mail koffi.mensah@example.com, Canal Site du marchand, Date 12 octobre 2026 à 04 h 14 (heure de Porto-Novo), N° de reçu A6C864E34C67, références et Réf. commande CMD-2026-44166 ; bloc « Reçu authentifié par CashChap » avec son QR code ; boutons Télécharger le reçu, Partager, Télécharger la facture ; bloc « Facture sur votre téléphone » avec le QR code de la facture ; bouton Fermer. — Sur ordinateur, le même écran dans la fenêtre du widget : le client scanne le QR code de la facture avec son téléphone pour l'y télécharger. Le widget reste ouvert jusqu'à « Fermer ».

Mode test

Avec une clé publique Sandbox, le widget fonctionne à l'identique : les paiements sont simulés selon le numéro saisi (le payeur tape 01 66 00 00 00 à côté de l'indicatif +229 : la page envoie 2290166000000, qui réussit ; 01 66 00 00 12 échoue pour solde insuffisant) et un bandeau rappelle qu'il s'agit d'un test : « Mode test : aucun argent réel ne sera débité. »

Personnalisation

Le logo et le nom affichés sont ceux de votre entreprise (Compte › Entreprise).
Les moyens de paiement proposés et la prise en charge des frais se règlent dans Compte › Préférences.
Le libellé du bouton qui ouvre le widget est à vous ; le widget lui-même n'est pas modifiable, pour que le client retrouve le même parcours chez tous les marchands CashChap.

Sécurité du widget

Isolation : le widget vit sur son propre domaine, dans un cadre. Votre page n'a jamais accès aux données saisies.
Politique de sécurité du contenu : le widget limite ses scripts, styles et connexions aux domaines de CashChap. Rien à configurer de votre côté.
Messages : le widget et le SDK ne dialoguent que par postMessage, avec contrôle d'origine.
Double paiement : le widget envoie la clé d'idempotence et votre référence à l'API ; une même demande rejouée rend la même transaction.
Preuve de paiement : le widget informe ; seule la lecture de la transaction depuis votre serveur fait foi.

Si votre site applique une CSP

Directives à ajouter à la politique de votre page (SDK 2.0)

Content-Security-Policy:
  script-src 'self' https://cdn.cashchap.com;
  frame-src https://payment.cashchap.com;
  connect-src 'self' https://api.cashchap.com;