Passer au contenu principal
Version : 1.x

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 des paiements aux appareils Square Terminal appairés et encaissez des paiements par carte en personne

Appairage simplifié

Appairez les terminaux depuis WooCommerce à l'aide d'un code d'appareil Square temporaire

Confirmation par webhook

Les webhooks Square vérifiés confirment la finalisation du paiement, avec un suivi en temps réel pendant l'attente

Transactions sécurisées

Traitement des paiements par carte en personne, conforme PCI, géré par le matériel Square

Sandbox et Production

Validez dans le Square Sandbox avant de passer aux paiements en production

Fonctionnement​

Contrairement aux passerelles basées sur un SDK navigateur, Square Terminal utilise l'API Terminal côté serveur de Square. Lorsqu'un paiement est initié, WooCommerce crée un Terminal Checkout pour la commande et Square l'envoie à l'appareil associé. Le client paie sur le terminal, et Square notifie votre site via un webhook signé. Le webhook est le signal de confirmation faisant autorité ; le PDV interroge également le statut afin que celui-ci se mette à jour pendant l'attente.

Cela signifie que l'appareil Square Terminal doit être en ligne et connecté au même compte et au même point de vente Square, et que votre site doit être accessible publiquement en HTTPS pour que Square puisse envoyer les webhooks.

Installation​

1

Installer Square Terminal for WooCommerce

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

2

Configurer les réglages Square

  1. Accédez à WP Admin > WooCommerce > Réglages > Paiements
  2. Trouvez Square Terminal dans la liste des moyens de paiement et cliquez dessus pour ouvrir les réglages
  3. Choisissez l'Environnement (Sandbox pour les tests, Production pour les paiements réels)
  4. Saisissez votre Jeton d'accès pour l'environnement sélectionné (Sandbox ou Production), disponible depuis le tableau de bord Square Developer
  5. Saisissez votre ID d'emplacement — l'emplacement Square où les paiements Terminal sont effectués
  6. Saisissez votre Clé de signature du webhook et l'URL de notification du webhook (voir l'étape suivante)
  7. Cliquez sur Valider les paramètres pour confirmer le bon fonctionnement des identifiants, puis enregistrez
note

Il n'est pas nécessaire d'activer la passerelle Square Terminal dans les réglages de WooCommerce. Elle sera activée spécifiquement pour le PDV lors d'une étape ultérieure.

3

Configurer les webhooks dans Square

Square envoie un webhook signé lorsqu'un paiement Terminal est terminé, et c'est ce qui marque la commande comme payée.

  1. Dans le tableau de bord Square Developer, ouvrez votre application et accédez à la section Webhooks
  2. Ajoutez un abonnement pour l'événement terminal.checkout.updated
  3. Définissez l'URL de notification sur l'URL de notification Webhook affichée dans les paramètres de l'extension — elle doit correspondre exactement
  4. Copiez la clé de signature Webhook dans les paramètres de l'extension afin que les événements entrants puissent être vérifiés
Important

L'URL de notification Webhook dans Square doit correspondre exactement à la valeur indiquée dans les paramètres de l'extension, et la clé de signature Webhook doit être correcte. En cas de non-concordance, les paiements Square aboutiront sur le terminal mais la commande WooCommerce ne sera pas mise à jour.

4

Associer votre Square Terminal

  1. Sur la même page de paramètres, cliquez sur Créer un code d'appareil
  2. Un code d'association est généré et affiché
  3. Sur votre Square Terminal, connectez-vous et saisissez le code sur l'écran d'association de l'appareil
  4. Une fois associé, le terminal est lié à l'emplacement configuré. Notez son identifiant d'appareil — vous le saisirez lors d'un paiement
Important

Le terminal doit être correctement associé et en ligne avant de pouvoir traiter des paiements. Assurez-vous que l'association est terminée avant de continuer.

5

Activer dans WCPOS

  1. Accédez à WP Admin > POS > Paramètres > Validation de la commande
  2. Recherchez la passerelle Square Terminal dans la liste
  3. Activez la passerelle pour l'utiliser dans le point de vente
  4. Enregistrez vos paramètres

Utilisation​

Traitement des paiements​

  1. Ajouter des articles : ajoutez des produits à votre panier dans le point de vente
  2. Sélectionner la passerelle : choisissez « Square Terminal » comme méthode de paiement
  3. Choisir l'appareil : saisissez l'identifiant de l'appareil Terminal du terminal associé qui doit recevoir le paiement
  4. Lancer le paiement : cliquez sur Lancer le paiement — Square envoie le paiement au terminal
  5. Paiement client : le client approche, insère ou glisse sa carte sur le Square Terminal
  6. Finalisation automatique : lorsque le webhook vérifié de Square confirme le paiement, la commande est marquée comme payée. Le statut se met à jour en temps réel pendant l'attente.

Contrôles de paiement​

Lorsque vous utilisez la passerelle Square Terminal, les options suivantes sont disponibles :

  • Lancer le paiement : envoyer une nouvelle demande de paiement au terminal sélectionné
  • Annuler le paiement : annuler un paiement actuellement en cours sur le terminal
  • Statut du paiement : une zone de statut en temps réel affiche l'état actuel du paiement
  • Journal des paiements : un journal par commande enregistre chaque étape et résultat significatif de Square

Gestion des commandes​

  • Finalisation par webhook : les commandes ne sont marquées comme payées que lorsqu'un webhook vérifié de Square confirme le paiement par le terminal
  • Suivi des paiements : les identifiants Square et un journal des paiements sont enregistrés sur la commande, et les étapes clés sont consignées dans les notes de commande
  • Génération de reçus : les reçus PDV standard sont générés après chaque paiement réussi

Prérequis​

Compte Square: Compte vendeur Square actif
Identifiants API: Access Token, Location ID et clé de signature Webhook depuis le tableau de bord Square Developer
Matériel compatible: Un appareil Square Terminal, en ligne et connecté au même point de vente Square
Site HTTPS public: Le site doit être accessible en HTTPS pour que Square puisse envoyer les webhooks
WCPOS: Version Pro requise pour le passage en caisse PDV

Compatibilité matérielle​

Exigences de connectivité

Square Terminal utilise l'API Terminal côté serveur de Square : le paiement est créé par votre site et transmis à l'appareil associé par Square. Le terminal doit être en ligne et connecté au même compte et au même emplacement Square, et votre site doit recevoir les webhooks Square via HTTPS pour que les commandes soient mises à jour.

Terminaux pris en charge​

  • Square Terminal ✅ — Terminal de paiement de comptoir dédié de Square

Périmètre et limitations​

Périmètre v0.1
  • Cette version préliminaire est centrée sur les flux PDV / paiement de commande. La disponibilité sur la page de paiement côté client est désactivée par défaut et doit être activée explicitement.
  • Cette version encaisse les paiements uniquement — les remboursements ne sont pas encore pris en charge. Les identifiants Square sont enregistrés sur la commande afin de pouvoir ajouter la prise en charge des remboursements ultérieurement.

Dépannage​

Problèmes courants​

L'appareil ne s'apparie pas
  • Vérifiez que le code d'appareil a été saisi avant son expiration — générez-en un nouveau avec Créer un code d'appareil si nécessaire
  • Vérifiez que le terminal est en ligne et connecté au même compte Square et au même ID d'emplacement que le plugin
  • Vérifiez que l'Environnement (Sandbox/Production) et le Jeton d'accès correspondent au compte auquel le terminal est connecté
La validation des paramètres échoue
  • Vérifiez que le Jeton d'accès correspond à l'Environnement sélectionné (un jeton Sandbox ne fonctionnera pas en Production, et inversement)
  • Vérifiez que l'ID d'emplacement appartient à ce compte
  • Copiez à nouveau le jeton depuis le tableau de bord développeur Square au cas où des caractères parasites se seraient glissés
Le paiement aboutit sur le terminal mais la commande ne se met pas à jour
  • L'URL de notification Webhook dans Square doit correspondre exactement au paramètre du plugin
  • Vérifiez que l'événement terminal.checkout.updated est bien souscrit dans le tableau de bord développeur Square
  • Vérifiez que la Clé de signature Webhook dans le plugin correspond à celle configurée dans Square
  • Vérifiez que votre site est accessible publiquement en HTTPS ; consultez les tentatives de livraison des webhooks dans le tableau de bord Square
Le paiement ne démarre pas
  • Vérifiez qu'un identifiant d'appareil Terminal valide est renseigné et que l'appareil est appairé et en ligne
  • Vérifiez que l'appareil est connecté à l'identifiant de lieu configuré
  • Consultez le journal des paiements et les journaux d'erreurs WordPress pour les messages de l'API Square

Obtenir de l'aide​

Pour l'assistance technique :

Captures d'écran​

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

  • Configuration des identifiants Square, du webhook et de l'appairage de l'appareil
  • Activation de la passerelle dans les paramètres WCPOS
  • Flux de traitement des paiements dans le passage en caisse du PDV