Journal des changements

Les versions publiées de l'API CashChap v2 et du SDK JavaScript, de la plus récente à la plus ancienne. L'adresse de l'API ne porte que la version majeure (/v2) ; la version complète est renvoyée dans l'en-tête de réponse CashChap-Version (aujourd'hui 2.4.0). Voir Version de l'API.

Comment lire les versions

API : numéro majeure.mineure.corrective. Une évolution compatible (nouveau champ, nouvelle route, nouveau code d'erreur) change la version mineure ou corrective, sans changer l'adresse. Une rupture changerait l'adresse (/v3) et serait annoncée à l'avance.
SDK JavaScript : https://cdn.cashchap.com/v2/sdk.js sert toujours la dernière version 2.x ; chaque version figée reste disponible à son adresse propre (sdk-2.0.2.js, sdk-2.0.1.js).
Chaque version publiée est notée ici, avec sa date.

API 2.5.0 : soldes et encaissements à confirmer 12 octobre 2026

Évolution compatible : aucun champ existant ne change de forme.

GET /v2/balance (clé secrète) : soldes available, pending et pending_confirmation (détail).
Transaction : objet funds (status, simulated), réservé au marchand.
Encaissements à confirmer : en Live, les paiements reçus par un opérateur qui verse les fonds sur le compte bancaire de CashChap (hors MTN et Moov du Bénin) restent réussis, mais leur montant n'entre dans le solde disponible qu'après confirmation de la réception des fonds (explications). Webhooks funds.held / funds.released avec funds.reason = collection_confirmation.

API 2.4.0 12 octobre 2026

Marge de change sur les devises à taux variable. Évolution compatible : aucun champ existant ne change de forme.

Tarif : un prix fixé dans une devise à taux variable (USD, NGN, GHS, CAD, CDF) et prélevé dans une autre devise porte une marge de change : le cours du jour est dégradé de 10 % par défaut, réglé par devise (équivalent XOF divisé par 0,9 pour 10 %), payée comme la commission : comprise dans amount_charged quand le client paie les frais, retenue sur net_amount sinon. Les prix en XOF, XAF et EUR (parité fixe) ne changent pas.
exchange (transaction, devis, webhooks), avec une clé secrète, de terminal ou de session : margin, margin_currency, margin_percent et margin_payer (customer ou merchant) quand la marge s'applique. Absents des réponses destinées au payeur (lien public, clé publique).
Bloc display et summary : la marge est comprise dans fees ; exchange_fee reste la seule part des frais de change.
L'en-tête CashChap-Version vaut 2.4.0. La spécification OpenAPI décrit les champs.

Tarifs : marge de change sur les devises à taux variable 12 octobre 2026

Pourquoi : le cours des devises à taux variable change chaque jour et les banques ne l'appliquent pas toujours ; la marge couvre cet écart.
Vos clients voient la marge comprise dans les frais, dans la devise de votre service (jamais de ligne « marge », jamais de XOF).
Portail : ligne « Marge de change (cours − 10 %) » dans le détail d'un paiement (« payée par le client » ou « retenue sur le net ») ; exports CSV avec marge_change_xof, marge_change_taux et marge_change_payee_par à la fin. La page Tarifs donne un exemple chiffré.
Aucune marge sur les retraits, les remboursements ni l'affichage de vos montants dans la devise de votre service (cours réel).

API 2.3.0 12 octobre 2026

Frais de change sur un prix dans une autre devise. Évolution compatible : aucun champ existant ne change de forme.

Tarif : un prix fixé dans une autre devise que celle prélevée par l'opérateur (par exemple 25 EUR prélevés en XOF) porte désormais des frais de change de 1 %, payés comme la commission du service : compris dans amount_charged quand le client paie les frais (total toujours arrondi au 5 F supérieur en XOF), retenus sur net_amount sinon. Un prix en XOF prélevé en XOF ne change pas ; une passerelle hors XOF garde son 1 % à la charge du marchand, jamais appliqué deux fois.
exchange (transaction, devis) : fee, fee_currency et fee_payer (customer ou merchant) quand le paiement porte des frais de change.
Bloc display : exchange_fee, la part de fees due au change, dans la devise du service (0 sinon).
Textes : summary mentionne la part de change (« Vous paierez 25,68 EUR, dont 0,68 EUR de frais (frais de change de 0,25 EUR compris). »).
L'en-tête CashChap-Version vaut 2.3.0. La spécification OpenAPI décrit les champs.

Tarifs : frais de change de 1 % sur un prix dans une autre devise 12 octobre 2026

Vos clients voient les frais de change dans la devise du service, compris dans les frais : devis (« dont 0,68 EUR de frais (frais de change de 0,25 EUR compris) »), écran final, reçu (ligne « dont change »), facture PDF (ligne « Frais de change »), e-mail de reçu et page de vérification. Jamais de XOF.
Portail : le détail d'un paiement indique si les frais de change ont été « payés par le client » ou « retenus sur le net » ; les exports CSV ajoutent à la fin frais_change_xof et frais_change_payes_par. La page Tarifs donne un exemple chiffré.
CashChap Link : changer la devise d'un lien à prix fixe demande une confirmation et vide le montant, à ressaisir dans la nouvelle devise.

API 2.2.0 12 octobre 2026

La devise du service partout. Évolution compatible : aucun champ existant ne change.

Bloc display sur transaction, quote, receipt et payment_link : prix, frais, total payé (et net crédité avec une clé) dans la devise du service, avec le taux appliqué. Voir Bloc display.
Moyens de paiement : display_currency, display_min_amount, display_max_amount ; les canaux api, shop et pos acceptent aussi la devise du service.
Textes : le summary du devis et les messages des montants minimum et maximum sont rédigés dans la devise du service (texte lisible, pas un montant).
Liens de paiement : un montant libre peut être envoyé dans la devise du service ; POST /v2/checkouts sans currency prend la devise du service (plus le XOF d'office).
Correction du webhook historique : currency.rate donne désormais le vrai taux « 1 XOF = rate × devise demandée » (il valait le taux de l'opérateur, 1 pour le XOF, quand la devise demandée était l'euro).
L'en-tête CashChap-Version vaut 2.2.0. La spécification OpenAPI décrit le bloc.

Portail et page de paiement : la devise du service partout 12 octobre 2026

Vos clients voient le prix, les frais, le total, l'écran final, le reçu, la facture, l'e-mail et la page de vérification dans la devise de votre service ; seule la demande de confirmation de l'opérateur peut annoncer le montant dans la monnaie de leur compte Mobile Money. Voir Devise du service.
Portail : une seule règle d'affichage (le choix Figé/Dynamique est retiré) : chaque opération dans la devise du service, au taux de sa date, avec le montant en XOF en second ; détail d'un paiement complet (prix, total payé, frais, commission, net, taux) ; filtres et tris par montant corrigés ; exports CSV enrichis à la fin.
CashChap Link : les nouveaux liens sont dans la devise du service ; un bandeau et une pastille signalent les liens plus anciens à prix fixe dans une autre devise. Ma boutique et les QR codes de caisse encaissent dans la devise du service.
Retraits : saisis en XOF, avec l'équivalent dans la devise du service en direct ; soldes et historique des reversements dans la devise du service, XOF en second. E-mails « Paiement reçu », « Fonds disponibles », remboursements et retraits : devise du service, puis XOF.
Documentation : exemple complet d'un service en euros (une robe à 25 EUR), avec les écrans du client (page produit, paiement, attente, écran final, reçu, facture, vérification, caisse) et du marchand (tableau de bord, paiements, détail, liens, Ma boutique, retrait).
Corrections : le détail d'un paiement n'étiquette plus en euros des montants en XOF ; le taux de la devise demandée est enregistré à chaque paiement et exporté correctement.

API 2.1.0 12 octobre 2026

QR codes de paiement. Évolution compatible : aucun champ ni aucune route existants ne changent.

QR codes de caisse (objet checkout) : POST /v2/checkouts, GET /v2/checkouts/{id} (avec wait) et POST /v2/checkouts/{id}/cancel, pour la clé secrète, une clé de terminal ou un jeton de session de caisse. Un QR de caisse est à usage unique et à durée limitée (60 à 900 secondes, 5 minutes par défaut), contrôlés par CashChap ; la vente est attribuée à la caisse (canal shop ou pos, terminal, caissier). Voir QR codes de caisse.
Liens de paiement : GET /v2/payment-links/{id} rend kind (link, shop ou checkout) et, pour un QR de caisse, status, expires_at, expires_in et terminal.
Nouveaux codes d'erreur : payment_link_expired et payment_link_cancelled (410), payment_link_already_paid, payment_link_in_progress et checkout_not_cancellable (409), checkout_not_found (404) ; code de champ invalid_expires_in.
Reçu enrichi (objet receipt) : coordonnées et logo du marchand, produit ou motif, frais, moyen et opérateur en clair, référence opérateur, nom du payeur (masqué hors clé secrète), canal (channel), date en toutes lettres à l'heure de Porto-Novo, verify_url (page publique de vérification, QR code d'authentification) et invoice_url (facture PDF de tout paiement réussi). Nouvelle route sans clé GET /v2/payment-links/{id}/transactions/{transaction}/receipt. Les champs existants du reçu ne changent pas.
Reçu complet du payeur (ajout du 12 octobre au soir) : champs customer_details, customer_phone, phone_display et customer_email ; la réponse de création d'un encaissement rend receipt_token, qui ouvre le reçu complet avec la clé publique ou sur la route d'un lien (?receipt_token=). Sans ce jeton, le reçu reste masqué et invoice_url vaut null : la facture, qui porte les coordonnées complètes du payeur, n'est plus donnée à un tiers. Voir Reçu complet ou masqué.
L'en-tête CashChap-Version vaut 2.1.0. La spécification OpenAPI décrit les nouvelles routes.

SDK JavaScript 2.0.2 12 octobre 2026

Le cadre du widget est autorisé à partager (allow="payment; web-share") : le client peut partager son reçu (WhatsApp, SMS…) depuis l'écran de succès. Voir Reçu du client dans le widget.
Le widget ne se ferme plus de lui-même après le résultat : le client garde son reçu, le QR code d'authentification et sa facture à l'écran, puis ferme le widget (« Fermer » ou ✕). Les rappels, les événements et la promesse partent toujours dès le résultat.
return_url : la redirection a lieu quand le client ferme le widget (bouton « Fermer et revenir au site du marchand »), jamais avant.
Aucun changement d'options, de rappels, d'événements ni de promesse. https://cdn.cashchap.com/v2/sdk.js sert la 2.0.2 ; la version figée https://cdn.cashchap.com/v2/sdk-2.0.2.js est nouvelle et https://cdn.cashchap.com/v2/sdk-2.0.1.js reste servie, inchangée.

Portail et page de paiement 12 octobre 2026

QR codes de paiement (page dédiée) : QR code de chaque CashChap Link (PNG, SVG, affiches A4 et A6, PDF) ; nouvelle page Paiements › QR code de la boutique, QR code permanent à montant libre par service et par mode, à régénérer avec votre mot de passe ; bouton Afficher un QR dans Ma boutique, QR code à usage unique de 5 minutes, paiement suivi en direct jusqu'à « Paiement reçu ».
Reçu complet, à télécharger et à partager : à la fin d'un paiement par le widget, un CashChap Link ou un QR code, reçu détaillé (logo et coordonnées du marchand, produit, montant, frais, total, opérateur, numéro complet, nom et e-mail du payeur, canal, date de Porto-Novo, références, « Mode test » en Sandbox), boutons Télécharger le reçu (image PNG) et Partager, Télécharger la facture et QR code de la facture, widget du SDK compris. Voir Reçu du client.
QR code d'authentification sur chaque reçu et chaque facture : page publique cashchap.com/verifier/… qui affiche « Paiement authentique », « Paiement de test » ou « Reçu introuvable ». Le reçu imprimé à la caisse le porte aussi. Voir Reçus et vérification.
Facture PDF : les montants s'affichent correctement (« 15 255 XOF »), avec la date et l'heure, le même contenu que le reçu et le QR code d'authentification.
Reçus et factures du payeur sans masquage : numéro complet sans « + » (« 229 01 66 00 00 00 »), nom et prénom, e-mail du payeur quand il l'a donné, sur l'écran final, l'image du reçu, le reçu imprimé de la caisse et la facture PDF. La page publique de vérification reste masquée. Voir Le reçu.
Page de paiement d'un QR code : « Paiement en caisse » avec le délai restant, ou « Payer » avec le champ du montant pour le QR code de la boutique ; messages « QR code déjà payé », « QR code expiré », « QR code annulé » et « Paiement en cours ».

API 2.0.0 11 octobre 2026

Première version publique de l'API v2.

v1 retirée : l'API v2 (https://api.cashchap.com/v2) est la seule API de CashChap. Toute adresse /v1/… répond 410 Gone (api_v1_removed) ; le guide de migration donne l'équivalent v2 de chaque route et de chaque champ.
En-tête CashChap-Version sur chaque réponse /v2, succès comme erreurs, préflight CORS compris, et lisible depuis un navigateur (Access-Control-Expose-Headers: CashChap-Version, Retry-After, X-Request-Id). Seule la version majeure figure dans l'adresse.
Numéros de téléphone au format international obligatoire, sans « + » (2290166000000), dans toutes les requêtes qui en portent : encaissements, paiement d'un lien, retraits, vérification d'un numéro (détails).
- Un « + » ou un « 00 » en tête est toléré en entrée, ainsi que les séparateurs (espaces, points, tirets, parenthèses).
- Le pays est déduit de l'indicatif. Au Bénin, l'indicatif 229 est suivi de 01 et de 8 chiffres ; l'ancien format 229 + 8 chiffres est complété.
- Un numéro national seul est refusé : 422 phone_international_required.
- country, facultatif, ne sert qu'au contrôle : 422 phone_country_mismatch s'il contredit l'indicatif.
- Les réponses et les webhooks rendent toujours le numéro sans « + » (2290166000000, masqué 22901••••0000 hors clé secrète).
Choix automatique de l'opérateur ("provider": "auto") limité aux opérateurs du pays de l'indicatif ; la réponse 202 indique l'opérateur retenu dans provider.
Catalogue des erreurs à jour : Erreurs de l'API v2 (codes internes E314 et E315 dans Codes internes). La spécification OpenAPI porte la version 2.0.0.

SDK JavaScript 2.0.1 11 octobre 2026

Le widget s'ouvre sur https://payment.cashchap.com, le domaine unique des paiements (widget et liens de paiement).
Contrôle à l'appel de idempotency_key et de metadata, avec les mêmes règles que l'API v2.
customer.phone peut être national (0197000000) ou international (2290197000000, « + » toléré) : la page de paiement reconnaît le pays, affiche le numéro national et envoie toujours le format international sans « + ». Aucun changement de code n'est nécessaire de votre côté.
La version figée 2.0.0 n'est plus servie : utilisez https://cdn.cashchap.com/v2/sdk.js ou https://cdn.cashchap.com/v2/sdk-2.0.1.js.

Portail et page de paiement 11 octobre 2026

Changements visibles de l'interface, sans effet sur l'API :

CashChap Link : les liens de paiement (anciennement CashLink) portent ce nom partout (menu Paiements, titres, fils d'Ariane, accueil, tarifs). La page de doc est désormais /docs/cashchap-link ; l'ancienne adresse y redirige.
Fils d'Ariane en français et complets sur toutes les pages (« CashChap › Paiements › CashChap Link › Créer un lien ») ; « CashChap » ramène au tableau de bord.
Dates et nombres en français, dans le fuseau de votre compte : « 11 oct. 2026, 14:55 » sur le tableau de bord, « 28/09/2026 15:55 » dans la liste des liens et le journal d'activité ; mois en français sur la courbe.
Connexion : page « Connexion à CashChap », libellé « E-mail » partout.
Activation du compte : étapes « Promoteur », « Informations de l'entreprise » et « Pièces de l'entreprise ».
Journaux API : le chemin public de l'appel (POST /v2/collections) dans la liste, le détail et l'export.
Sécurité : appareils et connexions affichés en clair (« Chrome 146 sur Windows »).
Numéros affichés avec leur indicatif et par groupes de deux chiffres (« +229 01 97 00 00 01 ») dans Mon profil, Entreprise, la boutique et la page de paiement ; dans la page de paiement, la boutique, l'inscription et le dossier d'activation, le numéro national se tape à côté de l'indicatif du pays. Cet affichage est fait pour être lu : l'API attend et renvoie le format international sans « + » (« 2290166000000 »).
E-mail « Paiement reçu » : avec la case Prélèvement validé de Compte › Préférences, bloc Notifications, le titulaire reçoit un e-mail à chaque paiement Live validé (« [CashChap] Paiement reçu : 32 000 XOF »).
Menu du profil : « Changer de thème » fait passer le portail en mode sombre ou clair.
Page de paiement : après un paiement réussi, l'écran final « Paiement effectué » dit « Merci ! Vous pouvez fermer cette page. ».
CashChap Link en deux pages : le lien affiche d'abord le produit (image, description, marchand, service, prix), puis, avec « Procéder au paiement », la page de paiement ; le ✕ ou le bouton Retour du navigateur ramène au produit. Même adresse : les liens déjà partagés ne changent pas.
Onglets du widget : seuls les moyens de paiement ouverts pour le service s'affichent (Mobile Money aujourd'hui) ; les onglets « Carte bancaire (Bientôt) » et « Débit direct » ne s'affichent plus quand ils ne sont pas proposés.
Tableaux ajustés pour tenir dans leur carte, sur ordinateur comme sur téléphone, sans défilement horizontal.