# Square Terminal Gateway

Met de Square Terminal-gateway kunt u WooCommerce-bestelbetalingen rechtstreeks vanuit WCPOS innen op [Square Terminal](https://squareup.com/hardware/terminal)-hardware. Een betaling wordt aangevraagd vanuit WooCommerce en voltooid op een gekoppeld Square Terminal-apparaat. Het resultaat wordt teruggeschreven naar de bestelling.

## Functies[​](#features "Directe link naar Functies")

#### Hardware-integratie

Stuur betalingen naar gekoppelde Square Terminal-apparaten en accepteer persoonlijke kaartbetalingen

#### Eenvoudig koppelen

Koppel terminals vanuit WooCommerce met een kort geldige Square-apparaatcode

#### Bevestigd via webhook

Geverifieerde Square-webhooks bevestigen de voltooiing, met live status terwijl u wacht

#### Veilige transacties

PCI-conforme verwerking van kaartbetalingen op Square-hardware

#### Sandbox en productie

Valideer met de Square Sandbox voordat u overschakelt naar live betalingen

## Hoe het werkt[​](#how-it-works "Directe link naar Hoe het werkt")

In tegenstelling tot browser-SDK-gateways gebruikt Square Terminal de **server-side Terminal API** van Square. Wanneer u een betaling start, maakt WooCommerce een Terminal Checkout voor de bestelling aan en pusht Square deze naar het gekoppelde apparaat. De klant betaalt op de terminal en Square meldt uw site met een ondertekende webhook. De webhook is het gezaghebbende voltooiingssignaal; de POS pollt ook zodat de status wordt bijgewerkt terwijl u wacht.

Dit betekent dat het Square Terminal-apparaat online moet zijn en moet zijn aangemeld bij hetzelfde Square-account en dezelfde locatie. Uw site moet bovendien openbaar bereikbaar zijn via HTTPS, zodat Square webhooks kan afleveren.

## Installatie[​](#installation "Directe link naar Installatie")

1

#### Installeer Square Terminal for WooCommerce

Installeer via `WP Admin > POS > Settings > Extensions`, of download de nieuwste **plugin zip asset** (niet de GitHub-broncode zip of tarball) van de [GitHub releases pagina](https://github.com/wcpos/square-terminal-for-woocommerce/releases) en upload deze via `Plugins > Add New > Upload Plugin`.

2

#### Configureer Square-instellingen

1. Navigeer naar `WP Admin > WooCommerce > Settings > Payments`
2. Zoek **Square Terminal** in de lijst met betaalmethoden en klik erop om de instellingen te openen
3. Kies de **omgeving** (`Sandbox` voor testen, `Production` voor live betalingen)
4. Voer uw **Access Token** in voor de geselecteerde omgeving (Sandbox of Production), beschikbaar via het [Square Developer Dashboard](https://developer.squareup.com/apps)
5. Voer uw **Location ID** in — de Square-locatie waar Terminal-betalingen worden aangenomen
6. Voer uw **Webhook Signature Key** en **Webhook Notification URL** in (zie de volgende stap)
7. Klik op **Instellingen valideren** om te bevestigen dat de inloggegevens werken, en sla daarna op

opmerking

U hoeft de Square Terminal-gateway niet in de WooCommerce-instellingen in te schakelen. Deze wordt in een latere stap specifiek voor de POS ingeschakeld.

3

#### Webhooks instellen in Square

Square stuurt een ondertekende webhook wanneer een Terminal-betaling is voltooid. Daarmee wordt de bestelling als betaald gemarkeerd.

1. Open uw applicatie in het [Square Developer Dashboard](https://developer.squareup.com/apps) en ga naar de sectie **Webhooks**
2. Voeg een abonnement toe voor de gebeurtenis **`terminal.checkout.updated`**
3. Stel de notificatie-URL in op de **Webhook Notification URL** die in de plugin-instellingen wordt getoond — deze moet **exact** overeenkomen
4. Kopieer de **Webhook Signature Key** naar de plugin-instellingen zodat inkomende gebeurtenissen kunnen worden geverifieerd

Belangrijk

De Webhook Notification URL in Square moet exact overeenkomen met de waarde in de plugin-instellingen, en de Webhook Signature Key moet correct zijn. Als deze niet overeenkomen, worden Square-betalingen op het apparaat voltooid, maar wordt de WooCommerce-bestelling niet bijgewerkt.

4

#### Koppel uw Square Terminal

1. Klik op dezelfde instellingenpagina op **Apparaatcode maken**
2. Er wordt een koppelingscode gegenereerd en aan u getoond
3. Meld u aan op uw Square Terminal en voer de code in op het scherm voor apparaatkoppeling
4. Zodra de terminal is gekoppeld, is deze verbonden met uw ingestelde locatie. Noteer de **Device ID** — die voert u in wanneer u een betaling aanneemt

Belangrijk

De terminal moet succesvol zijn gekoppeld en online zijn voordat u betalingen kunt verwerken. Zorg dat de koppeling is afgerond voordat u doorgaat.

5

#### Inschakelen in WCPOS

1. Ga naar `WP Admin > POS > Settings > Checkout`
2. Zoek de **Square Terminal**-gateway in de lijst
3. Schakel de gateway in voor gebruik in de POS
4. Sla uw instellingen op

## Gebruik[​](#usage "Directe link naar Gebruik")

### Betalingen verwerken[​](#processing-payments "Directe link naar Betalingen verwerken")

1. **Artikelen toevoegen**: Voeg producten toe aan uw winkelwagen in de POS
2. **Gateway selecteren**: Kies "Square Terminal" als betaalmethode
3. **Apparaat kiezen**: Voer de **Terminal Device ID** in van de gekoppelde terminal die de betaling moet aannemen
4. **Betaling starten**: Klik op **Betaling starten** — Square pusht de checkout naar het apparaat
5. **Klantbetaling**: De klant tikt, steekt of haalt de kaart door de Square Terminal
6. **Automatische voltooiing**: Wanneer de geverifieerde webhook van Square de betaling bevestigt, wordt de bestelling als betaald gemarkeerd. De live status wordt bijgewerkt terwijl u wacht.

### Betalingsbediening[​](#payment-controls "Directe link naar Betalingsbediening")

Wanneer u de Square Terminal-gateway gebruikt, hebt u de volgende opties:

* **Betaling starten**: Stuur een nieuw betalingsverzoek naar de geselecteerde terminal
* **Betaling annuleren**: Annuleer een betaling die momenteel op de terminal bezig is
* **Betalingsstatus**: Een live statusgebied toont de huidige status van de betaling
* **Betalingslogboek**: Een logboek per bestelling registreert elke betekenisvolle Square-stap en uitkomst

### Bestellingsbeheer[​](#order-management "Directe link naar Bestellingsbeheer")

* **Webhook als gezaghebbende voltooiing**: Bestellingen worden pas als betaald gemarkeerd wanneer een geverifieerde Square-webhook de Terminal-betaling bevestigt
* **Betalingstracking**: Square-identifiers en een betalingslogboek worden opgeslagen bij de bestelling, en belangrijke stappen worden naar bestelnotities geschreven
* **Bonnen genereren**: Na succesvolle betalingen worden standaard POS-bonnen gegenereerd

## Vereisten[​](#requirements "Directe link naar Vereisten")

Square-account

<!-- -->

: Actief Square-verkopersaccount

API-inloggegevens

<!-- -->

: Access Token, Location ID en Webhook Signature Key uit het Square Developer Dashboard

Compatibele hardware

<!-- -->

: Een Square Terminal-apparaat, online en aangemeld bij dezelfde Square-locatie

Openbare HTTPS-site

<!-- -->

: Uw site moet bereikbaar zijn via HTTPS zodat Square webhooks kan afleveren

WCPOS

<!-- -->

: Pro-versie vereist voor POS-afrekenen

## Hardwarecompatibiliteit[​](#hardware-compatibility "Directe link naar Hardwarecompatibiliteit")

Connectiviteitsvereisten

Square Terminal gebruikt de server-side Terminal API van Square: de checkout wordt door uw site aangemaakt en door Square naar het gekoppelde apparaat verzonden. De terminal moet online zijn en aangemeld zijn bij hetzelfde Square-account en dezelfde locatie, en uw site moet Square-webhooks via HTTPS kunnen ontvangen om bestellingen bij te werken.

### Ondersteunde terminals[​](#supported-terminals "Directe link naar Ondersteunde terminals")

* **Square Terminal** ✅ — Square's speciale kaartterminal voor op de toonbank

## Bereik en beperkingen[​](#scope-and-limitations "Directe link naar Bereik en beperkingen")

Bereik van v0.1

* Deze vroege release is gericht op **POS- / order-pay**-stromen. Beschikbaarheid in de klantgerichte storefront-checkout is standaard uitgeschakeld en moet expliciet worden ingeschakeld.
* De plugin **int alleen betalingen** — terugbetalingen worden nog niet ondersteund. Square-identifiers worden op de bestelling opgeslagen zodat ondersteuning voor terugbetalingen later kan worden toegevoegd.

## Problemen oplossen[​](#troubleshooting "Directe link naar Problemen oplossen")

### Veelvoorkomende problemen[​](#common-issues "Directe link naar Veelvoorkomende problemen")

Apparaat kan niet koppelen

* Zorg dat u de apparaatcode hebt ingevoerd voordat deze verliep — genereer indien nodig een nieuwe met **Apparaatcode maken**
* Controleer of de terminal online is en is aangemeld bij hetzelfde Square-account en dezelfde **Location ID** als de plugin
* Controleer of de **omgeving** (Sandbox/Production) en **Access Token** overeenkomen met het account waarbij de terminal is aangemeld

Instellingen valideren mislukt

* Controleer of de **Access Token** overeenkomt met de geselecteerde **omgeving** (een Sandbox-token werkt niet in Production, en omgekeerd)
* Bevestig dat de **Location ID** bij dat account hoort
* Kopieer de token opnieuw uit het Square Developer Dashboard om eventuele extra tekens uit te sluiten

Betaling wordt voltooid op de terminal, maar de bestelling wordt niet bijgewerkt

* De **Webhook Notification URL** in Square moet **exact** overeenkomen met de plugin-instelling
* Zorg dat de gebeurtenis **`terminal.checkout.updated`** is geabonneerd in het Square Developer Dashboard
* Controleer of de **Webhook Signature Key** in de plugin overeenkomt met die in Square
* Zorg dat uw site openbaar bereikbaar is via HTTPS; controleer webhook-afleverpogingen in het Square Dashboard

Betaling start niet

* Controleer of een geldige **Terminal Device ID** is ingevoerd en of het apparaat gekoppeld en online is
* Controleer of het apparaat is aangemeld bij de geconfigureerde **Location ID**
* Bekijk het **betalingslogboek** en de WordPress-foutlogs voor Square API-meldingen

### Hulp krijgen[​](#getting-help "Directe link naar Hulp krijgen")

Voor technische ondersteuning:

* Bezoek de [GitHub-opslagplaats](https://github.com/wcpos/square-terminal-for-woocommerce) om problemen te melden
* Raadpleeg de [Square Terminal API-documentatie](https://developer.squareup.com/docs/terminal-api/overview) voor hardware- en API-richtlijnen
* Neem contact op met Square-support voor account- en hardwareproblemen

## Schermafbeeldingen[​](#screenshots "Directe link naar Schermafbeeldingen")

Schermafbeeldingen worden in een toekomstige update toegevoegd om het volgende te tonen:

* Square-inloggegevens, webhook- en apparaatkoppelingsconfiguratie
* Gateway-inschakeling in WCPOS-instellingen
* Betalingsverwerking in de POS-checkout