Passerelle Square Terminal

La passerelle Square Terminal permet d'encaisser les paiements des commandes WooCommerce sur le matériel Square Terminal directement depuis WCPOS. Un paiement est demandé depuis WooCommerce et finalisé sur un appareil Square Terminal appairé, puis le résultat est enregistré dans la commande.

Fonctionnalités

Intégration matérielle

Envoyez les paiements vers les appareils Square Terminal appairés et encaissez des paiements avec carte présente

Connexion en un clic

Autorisez directement auprès de Square — aucun jeton d'accès à créer ou à coller

Finalisation fiable

Les paiements sont confirmés par interrogation et par un balayage en arrière-plan, les webhooks servant à accélérer le processus

Transactions sécurisées

Traitement avec carte présente conforme PCI, pris en charge par le matériel Square

Bac à sable et production

Validez avec le bac à sable Square avant de passer aux paiements réels

Fonctionnement

Contrairement aux passerelles à SDK navigateur, Square Terminal utilise l'API Terminal côté serveur de Square. Lorsque vous démarrez un paiement, WooCommerce crée un Terminal Checkout pour la commande et Square le transmet à l'appareil appairé. Le client paie sur le terminal, puis le résultat est enregistré dans la commande.

Comment un paiement est confirmé. Le PDV interroge Square pendant que le paiement est en cours, et un balayage en arrière-plan réconcilie tout ce que l'interrogation manque — un onglet de navigateur fermé, par exemple. Les webhooks Square sont un complément facultatif qui raccourcit l'attente ; ils ne sont pas nécessaires, et un site qui n'en a pas ne perd jamais de paiement.

L'appareil Square Terminal doit être en ligne et connecté au même compte et au même emplacement Square que l'extension.

Configuration

1

Installer Square Terminal for WooCommerce

Installez depuis WP Admin > POS > Réglages > Extensions, ou téléchargez la dernière archive zip de l'extension (et non le zip ou le tarball du code source GitHub) depuis la page des versions GitHub et téléversez-la via Extensions > Ajouter > Téléverser une extension.

2

Se connecter à Square

1. Rendez-vous dans WP Admin > WooCommerce > Réglages > Paiements et ouvrez Square Terminal
2. Sous Compte Square, choisissez l'Environnement — Sandbox pour les tests, Production pour les paiements réels
3. Cliquez sur Se connecter à Square et approuvez les autorisations que Square vous présente
4. Choisissez l'ID d'emplacement — l'emplacement Square pour lequel le Terminal encaisse les paiements

Choisissez l'environnement avant de vous connecter. Une connexion ne couvre qu'un seul environnement ; une connexion sandbox ne pourra jamais autoriser des paiements de production.

Vous utilisez déjà l'extension officielle WooCommerce Square ?

L'environnement et l'ID d'emplacement sont pré-remplis à partir de ses réglages. Seules ces deux valeurs sont lues — aucun identifiant n'est partagé entre les extensions, et vous devez toujours vous connecter ou fournir un jeton d'accès ici.

Vous préférez utiliser votre propre jeton d'accès ?

Ouvrez les Réglages avancés et collez un jeton d'accès correspondant à l'environnement sélectionné au lieu de vous connecter. Tout le reste fonctionne à l'identique.

3

Appairer votre Square Terminal

Sous Terminal :

1. Cliquez sur Créer un code d'appareil — un code d'appairage s'affiche
2. Sur le Square Terminal, ouvrez l'écran de connexion par code d'appareil et saisissez le code. Si le Terminal est actuellement connecté à Square POS ou à une autre intégration, déconnectez-le d'abord — l'écran de code d'appareil n'est pas accessible tant qu'il est utilisé ailleurs.
3. Cliquez sur Rechercher des lecteurs pour confirmer qu'il apparaît désormais sous Appairé avec cette extension

Une liste vide avant l'appairage est normale, ce n'est pas un défaut. L'API d'appareils de Square ne signale que les Terminals configurés pour l'usage de l'API Terminal — un Terminal exécutant Square POS n'apparaît pas du tout tant qu'un code d'appareil n'y a pas été saisi.

4

Activer dans WCPOS

1. Rendez-vous dans WP Admin > POS > Réglages > Encaissement
2. Trouvez la passerelle Square Terminal et activez-la pour le PDV
3. Enregistrez vos réglages

note

La case Activer/Désactiver de l'écran de réglages WooCommerce ne contrôle que l'encaissement de la boutique en ligne. WCPOS utilise automatiquement cette passerelle dès qu'elle est configurée, que cette case soit cochée ou non.

Appairer un Terminal

Un Square Terminal doit être appairé avec cette extension avant qu'un caissier puisse le sélectionner. L'appairage crée un code d'appareil de l'API Terminal, et c'est le seul moyen pour l'extension de s'adresser à l'appareil.

Sous Terminal, sur l'écran de réglages :

• Créer un code d'appareil — génère un code à saisir sur le Terminal. Il est de courte durée ; générez-en un nouveau s'il expire.
• Rechercher des lecteurs — répertorie ce que Square peut voir, en deux groupes :
  • Appairé avec cette extension — sélectionnable à l'encaissement
  • Autres appareils que Square voit à cet emplacement — configurés par une autre application, donc non sélectionnables ici tant qu'ils ne sont pas appairés avec cette extension
• Valider les réglages — vérifie les identifiants et l'emplacement auprès de Square

Pourquoi un Terminal qui vous appartient peut ne pas être sélectionnable

Les codes d'appareil appartiennent à l'application qui les a créés : un Terminal configuré par une autre intégration de l'API Terminal apparaît sous Autres appareils que Square voit, mais ne peut pas être sélectionné ici. Un Terminal exécutant Square POS n'apparaît pas du tout.

Dans les deux cas, la solution est la même : déconnectez le Terminal de ce à quoi il est actuellement appairé, puis saisissez un nouveau code issu de Créer un code d'appareil ici.

Webhooks

Les webhooks sont facultatifs. Ils raccourcissent le délai de confirmation d'un paiement. L'interrogation et le balayage en arrière-plan confirment de toute façon chaque paiement : un site sans abonnement webhook fonctionne donc correctement — simplement un peu plus lentement.

Non disponible si vous avez utilisé Se connecter à Square

Un abonnement webhook appartient à une application Square, et en ajouter un nécessite d'avoir accès à cette application dans le Square Developer Dashboard. Si vous vous êtes connecté avec Se connecter à Square, vous autorisez l'application WCPOS plutôt qu'une des vôtres : il n'y a donc pas de tableau de bord dans lequel ajouter un abonnement, ni de clé de signature à copier.

Les paiements se confirment normalement — par interrogation et par le balayage. Les étapes ci-dessous ne s'appliquent que si vous avez configuré l'extension avec votre propre jeton d'accès dans les Réglages avancés.

Pour en ajouter un, avec votre propre application Square :

1. Sur l'écran de réglages, sous Terminal → Webhooks, cliquez sur Copier pour copier l'URL du webhook
2. Dans le Square Developer Dashboard, ouvrez votre application et allez dans Webhooks
3. Ajoutez un abonnement pour l'événement terminal.checkout.updated, en collant cette URL comme URL de notification
4. Copiez la clé de signature du webhook depuis Square dans les Réglages avancés de l'extension

La ligne Webhooks indique alors si un webhook vérifié par signature est arrivé, et quand.

L'URL doit correspondre exactement

Square signe chaque webhook sur la base de l'URL de notification qui lui a été fournie. Si l'URL enregistrée dans Square diffère de celle de l'extension ne serait-ce que d'un caractère, chaque livraison échoue à la vérification. Utilisez le bouton Copier plutôt que de la saisir à la main.

Pourquoi cette étape est manuelle

L'API Webhook Subscriptions de Square est associée à l'application, et non aux vendeurs individuels, et ne peut pas être appelée avec un jeton d'accès vendeur. L'extension ne peut donc pas créer l'abonnement à votre place.

Si les webhooks ne se vérifient plus

La ligne Webhooks affiche Pas encore vérifié lorsqu'aucun webhook n'est arrivé et n'a été vérifié avec les réglages actuels. Si des paiements ont déjà eu lieu, vérifiez dans cet ordre :

1. La clé de signature du webhook dans les Réglages avancés correspond à celle enregistrée dans Square
2. L'URL de notification dans Square correspond exactement à l'URL affichée dans l'extension
3. L'événement terminal.checkout.updated fait bien l'objet d'un abonnement
4. Votre site est accessible publiquement en HTTPS — vérifiez les tentatives de livraison dans le Square Dashboard

Changer l'environnement, l'URL du webhook ou la clé de signature réinitialise cette ligne jusqu'à l'arrivée du webhook suivant. C'est voulu : une livraison vérifiée avec les anciens réglages ne dit rien des nouveaux.

Référence des réglages

L'écran de réglages est organisé dans l'ordre de la configuration.

Section	Contenu
Compte Square	Environnement, Se connecter à Square, ID d'emplacement
Terminal	Commandes d'appairage, liste des lecteurs, état des webhooks
Comportement de l'encaissement	Ignorer l'écran de reçu, recueillir la signature, journaux de débogage
Réglages avancés	Jetons d'accès, clé de signature du webhook, remplacement de l'URL du webhook

Les Réglages avancés sont repliés par défaut. Ils contiennent les jetons d'accès manuels — nécessaires uniquement si vous ne vous connectez pas — et la clé de signature du webhook. Le remplacement de l'URL du webhook doit rester vide, sauf si votre URL publique diffère de celle que l'extension déduit, par exemple derrière un proxy ou un domaine personnalisé.

Utilisation

Traitement des paiements

1. Ajoutez les articles : ajoutez des produits à votre panier dans le PDV
2. Sélectionnez la passerelle : choisissez « Square Terminal » comme moyen de paiement
3. Choisissez l'appareil : sélectionnez le terminal appairé dans la liste Appareil Terminal
4. Démarrez le paiement : cliquez sur Démarrer le paiement — Square transmet l'encaissement à l'appareil
5. Paiement du client : le client approche, insère ou glisse sa carte sur le Square Terminal
6. Finalisation : l'état se met à jour en direct pendant l'attente, et la commande est marquée comme payée dès que Square confirme le paiement

En Sandbox, la liste des appareils contient les identifiants d'appareils de test documentés par Square : chaque issue — succès, expiration, hors ligne — peut donc être testée sans matériel.

Commandes de paiement

• Démarrer le paiement : envoyer une nouvelle demande de paiement au terminal sélectionné
• Annuler le paiement : annuler un paiement en cours sur le terminal
• Vérifier l'état : demander immédiatement l'état actuel à Square
• Libérer le paiement : détacher un terminal qui ne répond pas afin que la commande puisse être réglée autrement ; l'encaissement abandonné est tout de même réconcilié en arrière-plan
• Journal de paiement : un journal facultatif par commande enregistrant chaque étape et chaque issue côté Square

Gestion des commandes

• Finalisation vérifiée : les commandes ne sont marquées comme payées qu'après vérification du paiement auprès de l'objet Payment de Square — jamais sur la base d'un signal non vérifié
• Suivi des paiements : les identifiants Square et un journal de paiement sont enregistrés sur la commande, et les étapes clés sont inscrites dans les notes de commande
• Génération du reçu : les reçus PDV standard sont générés après les paiements réussis

Prérequis

Compte Square: Compte vendeur Square actif

Emplacement Square: Un emplacement Square et son ID d'emplacement

Matériel compatible: Un appareil Square Terminal, en ligne et connecté au même emplacement Square

Site HTTPS public: Nécessaire uniquement si vous souhaitez des webhooks ; sans eux, les paiements se confirment par interrogation

WCPOS: Version Pro requise pour l'encaissement au PDV

Compatibilité matérielle

Exigences de connectivité

Square Terminal utilise l'API Terminal côté serveur de Square : l'encaissement est créé par votre site et livré à l'appareil appairé par Square. Le terminal doit être en ligne et connecté au même compte et au même emplacement Square que l'extension.

Terminals pris en charge

• Square Terminal ✅ — le terminal de carte de comptoir dédié de Square

Portée et limites

Portée actuelle

• Centré sur les flux PDV / paiement de commande. La disponibilité sur l'encaissement de la boutique côté client est désactivée par défaut et doit être explicitement activée.
• Encaisse uniquement les paiements — les remboursements ne sont pas encore pris en charge. Les identifiants Square sont enregistrés sur la commande afin que la prise en charge des remboursements puisse être ajoutée ultérieurement.
• Les abonnements webhook doivent être ajoutés manuellement dans Square ; voir Webhooks.

Dépannage

Problèmes courants

La liste Appareil Terminal est vide

• Le Terminal doit d'abord être appairé avec cette extension — utilisez Créer un code d'appareil et saisissez le code sur l'appareil
• Un Terminal appairé via le Square Dashboard ou l'application Square POS n'apparaîtra pas tant qu'il n'est pas appairé ici
• Cliquez sur Rechercher des lecteurs : s'il apparaît sous Autres appareils que Square voit, il existe mais n'est pas appairé avec cette extension
• Vérifiez que l'ID d'emplacement correspond à l'emplacement auquel le Terminal est connecté

L'appareil ne s'appaire pas

• Assurez-vous d'avoir saisi le code d'appareil avant son expiration — générez-en un nouveau avec Créer un code d'appareil
• Vérifiez que le terminal est en ligne et connecté au même compte Square et au même ID d'emplacement que l'extension
• Vérifiez que l'Environnement correspond au compte auquel le terminal est connecté

La validation des réglages échoue

• Si vous êtes connecté, vérifiez que la ligne Compte Square affiche toujours Connecté à Square ; si elle vous demande de vous reconnecter, l'autorisation a expiré
• Si vous utilisez un jeton d'accès, vérifiez qu'il correspond à l'Environnement sélectionné — un jeton Sandbox ne fonctionnera pas en Production, et inversement
• Vérifiez que l'ID d'emplacement appartient bien à ce compte

Le paiement aboutit sur le terminal mais la commande est lente à se mettre à jour

• C'est précisément ce que corrigent les webhooks. Sans webhook, la commande se met à jour lors de la prochaine réconciliation par l'interrogation ou le balayage en arrière-plan
• Vérifiez la ligne Webhooks — si elle indique Pas encore vérifié après des paiements, suivez Si les webhooks ne se vérifient plus
• La commande n'est jamais perdue : le balayage réconcilie tout paiement manqué par l'interrogation

Le paiement ne démarre pas

• Vérifiez qu'un terminal est sélectionné et que l'appareil est appairé et en ligne
• Vérifiez que l'appareil est connecté à l'ID d'emplacement configuré
• Consultez le Journal de paiement et WooCommerce > État > Journaux pour les messages de l'API Square

Un message indique qu'une reconnexion à Square est nécessaire

Les autorisations Square sont renouvelées automatiquement. Si un renouvellement ne peut pas aboutir, l'extension met fin à l'autorisation plutôt que de la laisser dans un état inutilisable, et l'écran de réglages vous demande de vous reconnecter. Cliquez sur Se reconnecter à Square — rien d'autre n'est à modifier.

Obtenir de l'aide

Pour le support technique :

• Rendez-vous sur le dépôt GitHub pour signaler des problèmes
• Consultez la documentation de l'API Square Terminal pour les questions de matériel et d'API
• Contactez le support Square pour les problèmes de compte et de matériel

Les journaux sont écrits dans WooCommerce > État > Journaux sous le handle sqtwc, et enregistrent chaque recherche d'appareil et chaque issue de webhook.

Captures d'écran

Des captures d'écran seront ajoutées dans une prochaine mise à jour pour montrer :

• Les sections Compte Square, Terminal et Réglages avancés
• L'activation de la passerelle dans les réglages WCPOS
• Le déroulement du traitement des paiements dans l'encaissement du PDV