WooCommerce

L’extension Xaalis for WooCommerce (dans integrations/woocommerce/xaalis-for-woocommerce) ajoute un moyen de paiement « Wave / Orange Money (Xaalis) ». Le client est redirigé vers la page de paiement hébergée de Xaalis, paie avec Wave ou Orange Money, et la commande est marquée comme payée quand Xaalis le confirme.

Prérequis : WordPress 6.4+, WooCommerce 8.2+ (testé avec la version 11.1), PHP 8.1+, devise de la boutique franc CFA (XOF). Fonctionne avec la page de commande classique et avec les blocs Panier / Validation de commande, ainsi qu’avec HPOS (High-Performance Order Storage, le stockage des commandes haute performance).

Installer et configurer

1. Compressez le dossier xaalis-for-woocommerce en fichier zip, téléversez-le dans Extensions → Ajouter → Téléverser (Plugins → Add New → Upload), puis activez-le.
2. WooCommerce → Réglages → Général (Settings → General) : devise franc CFA (XOF), nombre de décimales 0.
3. WooCommerce → Réglages → Paiements → Wave / Orange Money (Xaalis) (Settings → Payments) :

Réglage	Valeur
Test mode (mode test)	activé tant que vous n’avez pas testé tout le parcours
Test secret key (clé secrète de test)	sk_test_…
Live secret key (clé secrète de production)	sk_live_…
Webhook secret (secret de webhook)	whsec_… (remis une seule fois, à la création de votre compte)
API base URL (URL de base de l’API)	https://api.xaalis.sn (laissez la valeur par défaut)

4. Copiez l’URL de webhook affichée en haut de cette page — https://your-store/wp-json/xaalis/v1/webhook — et définissez-la comme webhook_url de votre compte (PATCH /v1/account, elle doit être en https:// ; voir Webhooks).

Les secrets enregistrés ne sont plus jamais affichés : les champs restent vides, avec un aperçu masqué (sk_test_••••ab12). Laissez un champ vide pour conserver sa valeur. Le mode production est refusé sans clé sk_live_ et sans URL d’API en https://, et le mode test n’utilise jamais une clé de production.

Le moyen de paiement est masqué sur la page de commande quand la devise n’est pas XOF ou quand le mode actuel n’a pas de clé valide ; un avis dans l’administration en indique la raison.

Ce qui se passe au moment du paiement

sequenceDiagram
    participant C as Client
    participant W as WooCommerce
    participant X as Xaalis
    C->>W: Passe commande (Wave / Orange Money)
    W->>X: POST /v1/payments (Idempotency-Key wc:mode:order:amount)
    X-->>W: paiement + checkout_url
    W-->>C: redirection vers checkout_url (commande « Attente paiement »)
    C->>X: paie avec Wave / Orange Money
    X->>W: webhook payment.succeeded signé
    W->>W: vérifie, contrôle commande/montant/mode, payment_complete() une seule fois
    X-->>C: retour sur la page de commande reçue

• Le paiement est créé avec le total de la commande sous forme de montant XOF entier, client_reference = numéro de commande, metadata = {order_id, order_key}, success_url = la page de commande reçue.
• Un total avec des décimales (par exemple 15000.50) est refusé avec une erreur, jamais arrondi. Le total doit être compris entre 100 et 100 000 000 XOF.
• Si le client relance la validation de commande, il retrouve le même paiement Xaalis (même Idempotency-Key). Si le total du panier change, un nouveau paiement est créé. Si le client réessaie après un paiement échoué ou expiré, un nouveau paiement est créé aussi.

Quand une commande est-elle payée ?

Uniquement quand Xaalis le confirme — jamais parce que le client est arrivé sur la page « merci » (La redirection ne prouve rien) :

1. par le webhook payment.succeeded signé, ou
2. quand le client arrive sur la page de commande reçue, l’extension interroge GET /v1/payments/{id} depuis le serveur.

Dans les deux cas, les mêmes contrôles sont faits avant tout changement : le paiement est bien celui créé pour cette commande (identifiant, order_id et order_key dans metadata), livemode correspond au mode de la boutique, la devise est XOF et le montant est égal au total de la commande. En attendant, la page affiche « Payment awaiting confirmation » (paiement en attente de confirmation).

Événement	Commande
payment.succeeded	En cours (Processing : stock diminué, e-mails envoyés) — une seule fois, même si le webhook est rejoué ou arrive en même temps que la page de retour
payment.failed	Échouée (Failed : le client peut réessayer depuis son compte ; un nouveau paiement est créé)
payment.expired	Annulée (Cancelled, si elle est toujours en attente)
réussi, mais le total de la commande a changé entre-temps	En attente (On hold) avec une note : vérifiez, puis remboursez ou ajustez
un second paiement réussit sur une commande déjà payée	note « rembourser un des paiements » (refund one payment)

Le webhook répond 400 à une signature invalide, absente ou expirée, 503 tant qu’aucun secret de webhook n’est configuré (pour que Xaalis réessaie), et 200 sinon. Chaque commande affiche son identifiant de paiement Xaalis sur l’écran de la commande ; une fois la commande payée, l’identifiant de transaction est l’identifiant du paiement. Journaux : WooCommerce → État → Journaux (Status → Logs), source xaalis (identifiants et codes uniquement, jamais les clés).

Mode test

Avec une clé sk_test_, aucun argent réel ne circule. Passez une commande, puis approuvez-la sur la page de paiement hébergée, ou depuis votre serveur avec POST /v1/payments/{id}/simulate {"outcome":"succeeded"} (voir Mode test). La commande doit passer à En cours (Processing) en quelques secondes.

Développer l’extension

integrations/woocommerce/dev fournit un WordPress + WooCommerce jetable (Docker, http://localhost:8480) relié à une API Xaalis locale et à un nouveau commerçant de test :

integrations/woocommerce/tests/docker-test.sh   # php -l + unit tests
integrations/woocommerce/dev/setup.sh           # WordPress, WooCommerce, XOF store, 15 000 FCFA product, plugin configured
integrations/woocommerce/dev/e2e.sh             # payment, webhooks, replays, forged signatures, failure, expiry, blocks
docker compose -p xaalis-woo -f integrations/woocommerce/dev/docker-compose.yml down -v

Détails : integrations/woocommerce/xaalis-for-woocommerce/README.md (en anglais). Vous construisez plutôt votre propre intégration PHP ? Utilisez le SDK PHP.