Paywiser

Contexte

Paywiser fournit une infrastructure d'acquisition marchande et de passerelle de paiement pour les paiements par carte. Pour les marchands WooCommerce, l'intégration doit s'adapter au cycle de vie des commandes WooCommerce et gérer les résultats asynchrones (flux redirect et postbacks côté serveur) sans laisser les commandes dans des états ambigus.

Problématique

Les flux de paiement par carte dans WooCommerce ont quelques impératifs :

• Le checkout doit faire transiter les commandes vers des états prévisibles (en attente → payée/échouée).
• Les flux basés sur redirect doivent gérer correctement le "retour client".
• Les notifications serveur-à-serveur doivent être vérifiées pour éviter la falsification.
• Le checkout moderne (WooCommerce Blocks) nécessite une couche d'intégration dédiée.

Objectifs du projet

• Fournir Paywiser comme méthode de paiement de premier ordre dans le checkout WooCommerce.
• Prendre en charge les solutions Redirect et Hosted de Paywiser depuis un seul plugin.
• Vérifier les charges utiles postback et mettre à jour l'état des commandes de manière déterministe.
• Maintenir la compatibilité de l'intégration avec le checkout legacy et Blocks.

Contraintes et défis

• Suivre le cycle de vie `WC_Payment_Gateway` pour éviter un comportement de checkout fragile.
• Traiter les paramètres postback/retour comme des entrées non fiables et les vérifier.
• Éviter les erreurs d'arrondi en alignant les montants envoyés à la passerelle avec les totaux WooCommerce.
• Garder la configuration conviviale pour les marchands sous `WooCommerce → Réglages → Paiements`.

Aperçu de la solution

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

• Enregistre une nouvelle méthode de paiement (`paywiser`) avec titre/description configurables.
• Prend en charge deux modes de passerelle : Redirect (pages hébergées) et Hosted (détails de carte capturés au checkout).
• Soumet les transactions au TxHandler Paywiser via HTTP POST vers `https://office.paywiser.com/secure/txHandler.php`.
• Reçoit et vérifie les résultats de paiement via `/wc-api/pw-postback` et le flux de retour `order-received`.

Architecture et approche technique

Configuration de la passerelle

• `sid` et `rcode`
• type de solution : `redirect` ou `hosted`
• action de transaction : `PREAUTH` ou `PAYMENT`

Initiation du checkout

• envoie un formulaire au TxHandler avec les totaux, champs client, URL de postback et URL de redirect
• inclut un hash MD5 de requête pour validation

Vérification postback et finalisation de commande

Le gestionnaire postback vérifie la charge utile en utilisant la signature SHA-256 `vrfy` (`sid;rcode;txid;status;amount;currency;tx_action`).

• Les paiements réussis finalisent via `payment_complete(txid)`.
• Les paiements échoués mettent à jour la commande à `failed` avec un message de diagnostic.

Support WooCommerce Blocks

L'intégration Blocks (`checkout.js`) enregistre Paywiser comme méthode de paiement Blocks avec gestion des entrées et interface utilisateur.

Stack technologique

• WordPress
• WooCommerce
• PHP (implémentation de la passerelle WooCommerce)
• JavaScript (intégration checkout Blocks + masquage d'entrée pour flux hosted)
• TxHandler Paywiser + vérification postback (API d'acquisition)

Processus de mise en œuvre

1. Modéliser les flux redirect vs hosted et les mapper vers les transitions de statut WooCommerce.
2. Implémenter les paramètres de passerelle et validation dans wp-admin.
3. Implémenter la soumission POST TxHandler et le hachage de requête.
4. Ajouter la gestion postback vérifiée (`/wc-api/pw-postback`) et vérification d'URL de retour.
5. Intégrer le checkout WooCommerce Blocks et tester les flux de bout en bout pour les deux solutions.

Résultats et impact

• Les marchands WooCommerce peuvent activer les paiements par carte Paywiser avec un flux opérationnel prévisible.
• Les solutions redirect et hosted sont toutes deux prises en charge depuis un seul plugin.
• Les postbacks côté serveur sont vérifiés avant de changer l'état de la commande.
• Le checkout reste compatible avec les expériences WooCommerce legacy et Blocks.

Réflexion

Les paiements basés sur redirect ne restent opérationnels que si le postback serveur-à-serveur est traité comme source de vérité et est vérifié avant de changer l'état de la commande. Intégrer cela dès le départ empêche le comportement "statut par paramètre d'URL" propice à la fraude et réduit la charge de support causée par des résultats ambigus.

Résumé

Ce plugin intègre Paywiser dans WooCommerce avec deux modes de paiement pris en charge, gestion postback vérifiée, et compatibilité avec les flux de checkout legacy et Blocks.