# Passerelle Square Terminal

La passerelle Square Terminal permet d'encaisser les paiements des commandes WooCommerce sur le matériel [Square Terminal](https://squareup.com/hardware/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[​](#features "Lien direct vers 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[​](#how-it-works "Lien direct vers 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[​](#installation "Lien direct vers 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](https://github.com/wcpos/square-terminal-for-woocommerce/releases) 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](https://developer.squareup.com/apps)
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](https://developer.squareup.com/apps), 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[​](#usage "Lien direct vers Utilisation")

### Traitement des paiements[​](#processing-payments "Lien direct vers 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[​](#payment-controls "Lien direct vers 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[​](#order-management "Lien direct vers 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[​](#requirements "Lien direct vers 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[​](#hardware-compatibility "Lien direct vers 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[​](#supported-terminals "Lien direct vers Terminaux pris en charge")

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

## Périmètre et limitations[​](#scope-and-limitations "Lien direct vers 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[​](#troubleshooting "Lien direct vers Dépannage")

### Problèmes courants[​](#common-issues "Lien direct vers 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[​](#getting-help "Lien direct vers Obtenir de l'aide")

Pour l'assistance technique :

* Consultez le [dépôt GitHub](https://github.com/wcpos/square-terminal-for-woocommerce) pour signaler des problèmes
* Consultez la [documentation de l'API Square Terminal](https://developer.squareup.com/docs/terminal-api/overview) pour des informations sur le matériel et l'API
* Contactez le support Square pour les questions relatives au compte et au matériel

## Captures d'écran[​](#screenshots "Lien direct vers 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