Architecture, sécurité et intégrations

Vue d'ensemble

XalisPay est un ensemble de modules et de SDK qui aident les développeurs comoriens à intégrer le Mobile Money (MVola, Wakati/HuriMoney et KartaPay) dans leurs boutiques et applications. XalisPay n'est pas une solution de paiement en soi, c'est une couche d'intégration technique, déclinée pour plusieurs plateformes : PrestaShop, WooCommerce, et prochainement Next.js, React Native et Flutter.

Techniquement, XalisPay s'appuie sur KartaPay, un agrégateur de paiement qui donne accès à MVola et Wakati via une seule API. Cette dépendance est isolée dans une couche d'adaptation, ce qui permet de basculer vers un accès direct aux opérateurs plus tard sans réécrire les modules PrestaShop ou WooCommerce.

Principe directeur

• Chaque module revérifie systématiquement le statut réel d'un paiement auprès du fournisseur avant de valider une commande, jamais sur la seule foi d'un retour de navigateur.
• Aucun secret d'authentification n'est jamais exposé côté client, y compris dans les applications mobiles.
• Chaque notification de paiement entrant (webhook) est authentifiée par signature avant d'être traitée.

Architecture générale

XalisPay suit un modèle en couches, avec un adaptateur de paiement qui isole la logique propre à KartaPay du reste du système :

Boutique (PrestaShop / WooCommerce)
   -> Module XalisPay (appel direct à KartaPay, OAuth2)
       -> KartaPay API (staging ou production)
           -> MVola ou Wakati (HuriMoney)

Pour la vente directe des modules (cette landing page), une architecture différente est utilisée : un backend Next.js hébergé sur Vercel gère la création de commande, l'appel à KartaPay, la réception du webhook et la livraison automatique du fichier acheté.

La classe d'authentification et le client HTTP vers KartaPay sont isolés dans des fichiers dédiés (adaptateur d'authentification, adaptateur de paiement selon la plateforme). Le jour où un accès direct à MVola et Wakati est obtenu, seule cette couche doit être remplacée, aucune autre partie du code n'a besoin d'être modifiée.

Module PrestaShop

Compatible PrestaShop 1.6 à 8. Structure principale :

• xalispay.php : classe principale, hooks de paiement, formulaire de configuration
• classes/KartaPayAuth.php : gestion du jeton OAuth2
• classes/KartaPayDirectClient.php : client HTTP vers l'API KartaPay
• controllers/front/payment.php : création du paiement, redirection du client
• controllers/front/validation.php : vérification du statut au retour du client
• controllers/front/webhook.php : réception des notifications asynchrones

Table de correspondance

Une table dédiée (ps_xalispay_payment) associe l'identifiant de paiement KartaPay au panier et à la commande PrestaShop. Elle est créée automatiquement à l'installation du module et permet au webhook de retrouver la bonne commande, même si le client a fermé son navigateur avant son retour sur le site.

Statuts de commande

Deux états de commande dédiés sont créés à l'installation : « En attente de paiement Mobile Money » et « Paiement Mobile Money échoué », en complément de l'état standard « Paiement accepté » de PrestaShop.

Plugin WooCommerce

Équivalent fonctionnel du module PrestaShop, adapté aux conventions WordPress et WooCommerce.

• La commande WooCommerce existe déjà au moment de l'appel à KartaPay (contrairement à PrestaShop) : son ID sert directement d'identifiant de réconciliation.
• Les appels HTTP utilisent l'API native WordPress (wp_remote_*) plutôt que curl directement.
• Le cache du jeton OAuth2 utilise les transients WordPress, avec expiration automatique.
• Les retours et notifications utilisent le mécanisme wc-api (woocommerce_api_{action}).

Sécurité additionnelle

Le webhook vérifie que l'identifiant KartaPay reçu correspond bien à celui enregistré sur la commande, en plus de la vérification de signature : une protection supplémentaire contre une commande dont l'identifiant serait manipulé ou réutilisé.

SDK Next.js / React

Le SDK Next.js pour marchands est encore en développement (voir « Soyez informé » sur la page d'accueil). Ce qui suit décrit le backend déjà construit et utilisé en production pour la vente des modules sur ce site, qui sert de fondation à ce futur SDK.

La landing page et son backend de vente sont réunis dans un seul projet Next.js, déployé sur Vercel.

Livraison automatique

Une fois le paiement confirmé, un jeton de téléchargement aléatoire est généré (valable 7 jours, limité à 5 téléchargements), et un email de confirmation est envoyé automatiquement au client avec le lien correspondant.

Composants du backend de vente

SDK mobile (React Native & Flutter)

Bientôt disponible. Voir « Soyez informé » sur la page d'accueil pour être prévenu de sa sortie.

Le SDK mobile devra obligatoirement passer par un backend intermédiaire, jamais par un appel direct à KartaPay depuis l'application. Une application mobile installée sur un téléphone ne peut garantir la confidentialité d'un secret d'authentification : celui-ci peut être extrait par rétro-ingénierie. Ce principe est celui appliqué par les solutions de paiement mobile comparables du marché.

Le backend déjà construit pour la vente des modules sert de fondation à ce futur SDK mobile : mêmes principes de vérification, mêmes mécanismes de sécurité, hébergement déjà en place.

Authentification & sécurité

Authentification KartaPay (OAuth2)

KartaPay utilise le protocole OIDC, flux client_credentials. Un jeton d'accès (JWT) est obtenu via une requête POST vers leur endpoint d'authentification, à partir d'un Client ID et d'un Client Secret fournis par KartaPay.

POST https://auth.kartapay.me/staging/token
  client_id=...&client_secret=...&grant_type=client_credentials

Le jeton obtenu est valable une heure. Il est mis en cache (fichier de configuration PrestaShop, transient WordPress, ou mémoire du processus Node selon la plateforme) et renouvelé automatiquement avec une marge de sécurité de 60 secondes avant expiration.

Vérification des webhooks

KartaPay signe chaque notification avec HMAC-SHA256. Le message à recalculer suit un ordre de champs précis :

message = id,merchantId,clientId,value,currency,submittedAt,status
signature_attendue = HMAC_SHA256(message, secret_webhook)

Le merchantId n'est pas transmis dans le corps du webhook : c'est une valeur propre au compte marchand, à renseigner dans la configuration du module. La comparaison de signature utilise une fonction à temps constant (hash_equals en PHP,crypto.timingSafeEqual en Node.js) pour éviter les attaques par mesure de temps.

Principes appliqués

• Aucune confiance accordée aux paramètres d'URL de retour : le statut réel est toujours revérifié via l'API avant toute validation de commande.
• Secrets d'authentification (Client Secret, secret webhook) jamais exposés côté client, jamais intégrés dans une application mobile.
• Signature HMAC vérifiée sur chaque webhook entrant avant tout traitement.
• Liens de téléchargement à durée de vie limitée et à usage limité, plutôt que des URLs de fichiers directement accessibles.
• KartaPay indique explicitement ne pas sécuriser les points d'accès publics du marchand (URLs de retour). Cette vérification incombe entièrement à l'intégration marchand, ce qui est pris en compte dans l'ensemble des modules XalisPay.

Glossaire