Fliqa

Contexte

Fliqa fournit un produit de paiement qui permet aux clients de payer via leur banque choisie (PIS / flux open banking). Pour les marchands WooCommerce, cela nécessitait un plugin de passerelle qui s'intègre au cycle de vie des commandes WooCommerce et supporte la réalité opérationnelle des redirections, callbacks et finalisation de paiement asynchrone.

Problème

Le checkout WooCommerce est opiniâtre :

• Il s'attend à des transitions d'état de paiement prévisibles (pending → on-hold/paid/failed).
• Il nécessite une gestion claire des scénarios "retour client" (succès, annulation, fermeture).
• Il requiert un stockage de configuration sécurisé et une UX admin sous `WooCommerce → Réglages → Paiements`.

L'intégration devait également gérer les cas limites du monde réel (checkout abandonné, échecs de paiement, soumissions doubles) sans créer d'états de commande incohérents.

Objectifs du projet

• Offrir Fliqa comme méthode de paiement de première classe dans le checkout WooCommerce (legacy + Blocks).
• Garder l'état de la commande cohérent même lorsque le client quitte le site pendant le paiement.
• Fournir une interface de configuration claire dans wp-admin.
• Supporter les environnements sandbox et production.

Contraintes et défis

• Suivre le cycle de vie `WC_Payment_Gateway` pour garder le comportement du checkout prévisible.
• Garder les secrets côté serveur (clé/secret API ; secret webhook) et éviter de les fuiter vers le frontend.
• Vérifier l'authenticité du webhook (validation de signature, support de rotation de secret).
• Rendre la finalisation de paiement robuste même si le client ne revient pas (webhook + réconciliation).

Aperçu de la solution

Nous avons implémenté un plugin de passerelle WooCommerce qui :

• Enregistre une nouvelle méthode de paiement (`fliqa`, titre/description configurables).
• Charge le SDK Fliqa (`https://assets.fliqa.io/sdk/latest/fliqaComponent.js`) et ouvre le dialogue/iframe de paiement.
• Inclut les métadonnées de commande dans la requête de paiement (id/clé commande, id/email client quand disponibles).
• Finalise les commandes via un endpoint webhook vérifié (`/wc-api/fq-postback`) et une tâche de réconciliation de secours pour les commandes "on-hold".
• Stocke le `paymentId` sur la commande (`_fq_paymentId`) pour la réconciliation et les workflows de support marchand.

Architecture et approche technique

Le plugin suit le flux de passerelle WooCommerce standard :

• Configuration de passerelle (requise) : environnement, slug tenant, point de vente (ID), clé/secret API, secret webhook.
• Checkout : `process_payment()` crée la commande et redirige vers la page de reçu de paiement, où le dialogue SDK est exécuté avec montant, devise et métadonnées.
• Retour client : sur `order-received`, si `paymentId` est présent, le plugin récupère le statut de paiement et le mappe vers les états WooCommerce :
• `successful` → `payment_complete(paymentId)`
• `pending` / `expired` → `on-hold` ("En attente du paiement Fliqa")
• `rejected` / `canceled` / `failed` → `failed`
• Webhook : `/wc-api/fq-postback` valide `X-Fliqa-Signature` (HMAC) contre le secret configuré (et le secret précédent pour rotation), puis met à jour le statut de commande en utilisant les mêmes règles de mapping.
• Réconciliation : une tâche planifiée vérifie les commandes Fliqa "on-hold" avec `_fq_paymentId` et les finalise en appelant l'API de statut de paiement.

L'implémentation inclut les déclarations de compatibilité de fonctionnalités WooCommerce (y compris le checkout Blocks et les tables de commandes personnalisées).

Stack technologique

• WordPress
• WooCommerce
• PHP (implémentation de passerelle + vérification de signature webhook)
• JavaScript (intégration WooCommerce Blocks + exécution SDK)
• API de paiement Fliqa + webhooks

Processus d'implémentation

1. Définir le modèle d'état et le chemin de complétion autoritaire (webhook-first).
2. Implémenter les paramètres de passerelle et la validation dans wp-admin.
3. Intégrer l'exécution du SDK et transmettre les métadonnées de commande déterministes.
4. Implémenter la gestion de webhook avec vérification de signature et support de rotation de secret.
5. Ajouter la réconciliation pour les commandes on-hold et tester les flux de bout en bout (sandbox → production).

Résultats et impact

• Les marchands WooCommerce peuvent activer une méthode de paiement bancaire sans réécriture de checkout personnalisée.
• La finalisation de paiement est déterministe : le webhook met à jour les commandes même si le client abandonne le flux de retour.
• Les équipes opérationnelles obtiennent une référence stable (`paymentId`) stockée sur la commande pour le support et la réconciliation.

Réflexion

Le choix de conception le plus important était de traiter la complétion de paiement comme asynchrone par défaut et de rendre le chemin webhook autoritaire, avec la réconciliation comme filet de sécurité. Cela évite les commandes "bloquées" et réduit l'intervention manuelle.

Résumé

Ce plugin intègre Fliqa comme passerelle de paiement WooCommerce de qualité production avec webhooks vérifiés, mapping d'état clair, et compatibilité avec les flux de checkout legacy et Blocks.