Guide

Checkout Blocks et paiements bancaires français

Mis à jour le 24 septembre 2026

Réponse courte

Le checkout en blocs de WooCommerce (« Cart & Checkout Blocks ») n’affiche pas un moyen de paiement du seul fait qu’il est activé dans les réglages. Le plugin doit s’enregistrer auprès des Blocks, côté serveur et côté navigateur. Il doit aussi déclarer sa compatibilité. Pour un paiement bancaire à redirection (Up2pay e‑Transactions, Mercanet, Sherlock’s, Sogenactif), le bloc a peu à faire. Il affiche seulement un titre et une description. WooCommerce crée ensuite la commande et redirige le client vers la page de la banque, comme au checkout classique.

Checkout classique et checkout Blocks : ce qui change

Le checkout classique est une page PHP rendue par le serveur. Le checkout Blocks est une interface construite dans le navigateur, qui dialogue avec WooCommerce par la Store API. Un plugin de paiement écrit uniquement pour le checkout classique n’a pas de représentation dans cette interface : le moyen de paiement peut alors ne pas apparaître, même s’il est actif et correctement configuré.

Les paiements des banques françaises décrits ici ont un point commun : la carte n’est jamais saisie sur votre site. Le client est envoyé vers une page de paiement hébergée par la banque ou son prestataire. C’est une bonne nouvelle pour les Blocks : il n’y a pas de champ de carte à intégrer dans le bloc, seulement un choix à afficher et une redirection à déclencher.

Ce qu’un moyen de paiement à redirection doit faire

Voici les éléments à prévoir. Le code peut varier d’un plugin à l’autre, mais ces points restent à vérifier dans chacun.

1. Déclarer la compatibilité

Le plugin déclare la fonctionnalité cart_checkout_blocks auprès de WooCommerce, sur le crochet before_woocommerce_init, avec FeaturesUtil::declare_compatibility(). Sans cette déclaration, WooCommerce signale le plugin comme incompatible dans l’administration.

2. Enregistrer une classe côté serveur

Une classe qui étend AbstractPaymentMethodType (espace de noms Automattic\WooCommerce\Blocks\Payments\Integrations) est enregistrée sur le crochet woocommerce_blocks_payment_method_type_registration. Elle indique :

• si le moyen de paiement est actif (is_active()) ;
• quel script charger ;
• quelles données transmettre au navigateur.

3. Fournir un petit script côté navigateur

Le script enregistre le moyen de paiement dans le registre des Blocks. Pour une redirection, il affiche seulement le titre et la description.

4. Laisser process_payment() faire le travail

Quand le client valide, la Store API crée la commande et appelle la même méthode process_payment() que le checkout classique. La suite dépend du plugin. Pour un paiement à redirection, cette méthode n’a pas besoin de contacter la banque. Elle peut se contenter de préparer la tentative de paiement et de renvoyer une redirection vers la page de paiement de la commande. Cette page génère alors le formulaire envoyé automatiquement à la banque. Comme la méthode est la même, le parcours est ensuite identique dans les deux types de checkout.

5. Ne transmettre que des données publiques

Les données envoyées au navigateur sont visibles par tout visiteur. Elles doivent se limiter au titre, à la description et aux fonctions prises en charge. Jamais d’identifiant de boutique ni de clé.

Vérifications pas à pas

1. Quel checkout utilisez-vous ? Ouvrez la page de validation de commande dans l’éditeur de WordPress. Si elle contient le bloc de validation de commande (Checkout), vous êtes en Blocks. Si elle contient le code court [woocommerce_checkout], vous êtes en classique.
2. Le plugin est-il déclaré compatible ? Dans WooCommerce, un plugin non déclaré est signalé comme incompatible. Consultez les avis de l’administration et la liste des extensions incompatibles, si WooCommerce l’affiche.
3. Le moyen de paiement est-il disponible ? Un bloc bien écrit suit la disponibilité réelle de la passerelle. Le plus souvent, il faut que la passerelle soit activée, que la devise de la boutique soit prise en charge par le plugin, et que les identifiants du mode actif soient complets et valides. Si une condition manque, le moyen n’apparaît ni en classique ni en Blocks.
4. Testez les deux parcours. Passez une commande de test en Blocks, puis en classique. Dans les deux cas, vous devez arriver sur la page de paiement de votre banque, avec le même montant.
5. Vérifiez la commande après la notification. Le statut doit changer après la notification serveur à serveur de la banque, pas au retour du client. Ce point ne dépend pas du checkout utilisé.

Pièges fréquents

Le moyen apparaît en classique mais pas en Blocks. Le plugin n’a probablement pas d’intégration Blocks, ou ne l’enregistre pas (classe côté serveur sur le crochet woocommerce_blocks_payment_method_type_registration, script côté navigateur). Voir le moyen de paiement n’apparaît pas au checkout.

Le moyen disparaît des deux types de checkout. Cherchez une condition de disponibilité : devise autre que l’euro, identifiants incomplets, clé invalide.

Les crochets sont posés plusieurs fois. WooCommerce peut instancier plusieurs fois une classe de passerelle. Si un plugin pose ses crochets dans le constructeur, ils peuvent s’exécuter en double. La parade : les poser une seule fois, dans le fichier principal du plugin.

Le point relais. Les plugins de point relais écrivent souvent leurs propres données dans la commande. Un plugin de paiement ne doit jamais les réécrire, quel que soit le checkout. Voir point relais écrasé après paiement.

Ce que fait Relqor

Les plugins Relqor pour Up2pay et Sips utilisent un script de bloc sans étape de compilation, qui s’appuie sur les bibliothèques déjà chargées par WordPress et WooCommerce (notamment wc-blocks-registry, wc-settings et wp-element). Le moyen de paiement n’apparaît que si la passerelle est activée, que la boutique est en euro et que les identifiants du mode actif sont complets et valides.

Dans ces deux plugins, process_payment() crée la tentative de paiement et renvoie vers la page de paiement de la commande. Cette page génère le formulaire envoyé automatiquement à la banque.

En résumé

Les plugins Relqor pour Up2pay et Sips déclarent la compatibilité cart_checkout_blocks, enregistrent une intégration Blocks qui n’affiche que le titre et la description, et passent par la même méthode process_payment() que le checkout classique. Pour Up2pay, un test automatisé en navigateur vérifie le parcours Blocks, avec HPOS activé et désactivé. Pour Sips, des tests d’intégration passent commande par la Store API, en HPOS et en posts. Voir la page Compatibilité testée, la page Up2pay e‑Transactions et la documentation installation et réglages Up2pay.

Pour votre banque, voir les pages Up2pay e‑Transactions, Mercanet, Sherlock’s et Sogenactif.