Square Terminal Gateway

Met de Square Terminal-gateway kunt u WooCommerce-bestelbetalingen rechtstreeks vanuit WCPOS innen op Square Terminal-hardware. Een betaling wordt aangevraagd vanuit WooCommerce en voltooid op een gekoppeld Square Terminal-apparaat. Het resultaat wordt teruggeschreven naar de bestelling.

Functies

Hardware-integratie

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

Verbinden met één klik

Autoriseer rechtstreeks bij Square — geen access token die u hoeft aan te maken of te plakken

Betrouwbare voltooiing

Betalingen worden bevestigd door polling en een achtergrondopruimer, met webhooks om het te versnellen

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

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 het resultaat wordt teruggeschreven naar de bestelling.

Hoe een betaling wordt bevestigd. De POS pollt Square terwijl de betaling loopt, en een achtergrondopruimer verwerkt alsnog alles wat de polling mist — bijvoorbeeld een gesloten browsertabblad. Square-webhooks zijn een optionele toevoeging die de wachttijd verkort; ze zijn niet vereist, en een site zonder webhooks verliest nooit een betaling.

Het Square Terminal-apparaat moet online zijn en aangemeld zijn bij hetzelfde Square-account en dezelfde locatie als de plugin.

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 en upload deze via Plugins > Add New > Upload Plugin.

2

Verbinden met Square

1. Ga naar WP Admin > WooCommerce > Settings > Payments en open Square Terminal
2. Kies onder Square account de omgeving — Sandbox om te testen, Production voor live betalingen
3. Klik op Connect to Square en keur de machtigingen goed die Square u toont
4. Kies de Location ID — de Square-locatie waarvoor de Terminal betalingen aanneemt

Kies de omgeving voordat u verbinding maakt. Een verbinding geldt voor één omgeving; een sandboxverbinding kan nooit productiebetalingen autoriseren.

Gebruikt u al de officiële WooCommerce Square-plugin?

Omgeving en Location ID worden vooraf ingevuld vanuit de instellingen daarvan. Alleen die twee waarden worden gelezen — er worden geen inloggegevens gedeeld tussen de plugins, en u moet hier nog steeds verbinding maken of een access token opgeven.

Liever uw eigen access token gebruiken?

Open Advanced settings en plak daar een access token voor de geselecteerde omgeving in plaats van verbinding te maken. Al het overige werkt identiek.

3

Koppel uw Square Terminal

Onder Terminal:

1. Klik op Create Device Code — er verschijnt een koppelingscode
2. Open op de Square Terminal het aanmeldscherm voor apparaatcodes en voer de code in. Als de Terminal op dat moment is aangemeld bij Square POS of een andere integratie, meld u daar dan eerst af — het scherm voor apparaatcodes is niet bereikbaar zolang het apparaat elders in gebruik is.
3. Klik op Check for readers om te bevestigen dat het apparaat nu verschijnt onder Paired with this plugin

Een lege lijst vóór het koppelen is te verwachten en duidt niet op een fout. De apparaat-API van Square rapporteert alleen Terminals die zijn ingericht voor gebruik met de Terminal API — een Terminal die Square POS draait, verschijnt helemaal niet totdat er een apparaatcode op is ingevoerd.

4

Inschakelen in WCPOS

1. Ga naar WP Admin > POS > Settings > Checkout
2. Zoek de Square Terminal-gateway en schakel deze in voor de POS
3. Sla uw instellingen op

opmerking

Het selectievakje Enable/Disable op het WooCommerce-instellingenscherm regelt alleen het afrekenen in de onlinewinkel. WCPOS gebruikt deze gateway automatisch zodra hij is geconfigureerd, of dat vakje nu is aangevinkt of niet.

Een terminal koppelen

Een Square Terminal moet met deze plugin worden gekoppeld voordat een kassamedewerker hem kan selecteren. Bij het koppelen wordt een Device Code van de Terminal API aangemaakt, en dat is de enige manier waarop de plugin het apparaat kan aanspreken.

Onder Terminal op het instellingenscherm:

• Create Device Code — genereert een code die u op de Terminal invoert. De code is kort geldig; genereer een nieuwe als hij verloopt.
• Check for readers — toont wat Square kan zien, in twee groepen:
  • Paired with this plugin — selecteerbaar bij het afrekenen
  • Other devices Square can see at this location — ingericht door een andere applicatie en daarom hier niet selecteerbaar totdat het apparaat met deze plugin is gekoppeld
• Validate Settings — controleert de inloggegevens en de locatie bij Square

Waarom een Terminal die u bezit niet selecteerbaar is

Device Codes horen bij de applicatie die ze heeft aangemaakt, dus een Terminal die door een andere Terminal API-integratie is ingericht, verschijnt onder Other devices Square can see maar kan hier niet worden geselecteerd. Een Terminal die Square POS draait, verschijnt helemaal niet.

In beide gevallen is de oplossing dezelfde: meld de Terminal af bij waar hij nu aan gekoppeld is en voer hier een nieuwe Create Device Code in.

Webhooks

Webhooks zijn optioneel. Ze verkorten de tijd die nodig is om een betaling te bevestigen. Polling en de achtergrondopruimer bevestigen elke betaling hoe dan ook, dus een site zonder webhook-abonnement werkt nog steeds correct — alleen iets trager.

Niet beschikbaar als u Connect to Square hebt gebruikt

Een webhook-abonnement hoort bij een Square-applicatie, en er een toevoegen vereist toegang tot die applicatie in het Square Developer Dashboard. Als u verbinding hebt gemaakt via Connect to Square, autoriseert u de WCPOS-applicatie in plaats van een eigen applicatie, dus is er voor u geen dashboard om een abonnement in toe te voegen en geen signature key om te kopiëren.

Betalingen worden nog steeds normaal bevestigd — door polling en de opruimer. De onderstaande stappen gelden alleen als u de plugin hebt ingesteld met uw eigen access token onder Advanced settings.

Zo voegt u er een toe met uw eigen Square-applicatie:

1. Klik op het instellingenscherm onder Terminal → Webhooks op Copy om de webhook-URL te kopiëren
2. Open in het Square Developer Dashboard uw applicatie en ga naar Webhooks
3. Voeg een abonnement toe voor de gebeurtenis terminal.checkout.updated en plak die URL als notificatie-URL
4. Kopieer de Webhook Signature Key van Square naar Advanced settings in de plugin

De rij Webhooks meldt daarna of er een webhook met geverifieerde handtekening is binnengekomen, en wanneer.

De URL moet exact overeenkomen

Square ondertekent elke webhook op basis van de notificatie-URL die het heeft gekregen. Als de URL in Square ook maar één teken afwijkt van die van de plugin, mislukt elke aflevering bij de verificatie. Gebruik de knop Copy in plaats van de URL over te typen.

Waarom deze stap handmatig is

De Webhook Subscriptions API van Square geldt op het niveau van de applicatie, niet van individuele verkopers, en kan niet worden aangeroepen met een access token van een verkoper. De plugin kan het abonnement daarom niet voor u aanmaken.

Als webhooks niet meer worden geverifieerd

De rij Webhooks toont Not verified yet wanneer er onder de huidige instellingen geen webhook is binnengekomen en geverifieerd. Als er al betalingen zijn gedaan, controleer dan in deze volgorde:

1. De Webhook Signature Key in Advanced settings komt overeen met die in Square
2. De notificatie-URL in Square komt exact overeen met de URL die de plugin toont
3. De gebeurtenis terminal.checkout.updated is geabonneerd
4. Uw site is openbaar bereikbaar via HTTPS — controleer de afleverpogingen in het Square Dashboard

Het wijzigen van de omgeving, de webhook-URL of de signature key zet deze rij terug tot de volgende webhook binnenkomt. Dat is bedoeld: een aflevering die onder de oude instellingen is geverifieerd, zegt niets over de nieuwe.

Overzicht van instellingen

Het instellingenscherm is geordend in de volgorde waarin de installatie verloopt.

Sectie	Bevat
Square account	Omgeving, Connect to Square, Location ID
Terminal	Koppelingsknoppen, lijst met lezers, webhookstatus
Checkout behaviour	Bonscherm overslaan, handtekening vragen, debuglogs
Advanced settings	Access tokens, webhook signature key, override van de webhook-URL

Advanced settings is standaard ingeklapt. Daar staan de handmatige access tokens — alleen nodig als u geen verbinding maakt — en de webhook signature key. De Webhook URL override moet leeg blijven, tenzij uw openbare URL afwijkt van de URL die de plugin afleidt, bijvoorbeeld achter een proxy of een aangepast domein.

Gebruik

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: Selecteer de gekoppelde terminal in de lijst Terminal Device
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. Voltooiing: De status wordt live bijgewerkt terwijl u wacht, en de bestelling wordt als betaald gemarkeerd zodra Square de betaling bevestigt

In Sandbox bevat de apparaatlijst de gedocumenteerde test-apparaat-ID's van Square, zodat elke uitkomst — geslaagd, time-out, offline — zonder hardware kan worden geoefend.

Betalingsbediening

• Betaling starten: Stuur een nieuw betalingsverzoek naar de geselecteerde terminal
• Betaling annuleren: Annuleer een betaling die momenteel op de terminal bezig is
• Status controleren: Vraag Square direct om de huidige status
• Betaling vrijgeven: Maak een niet-reagerende terminal los zodat de bestelling op een andere manier kan worden betaald; de verlaten checkout wordt alsnog op de achtergrond afgehandeld
• Betalingslogboek: Een optioneel logboek per bestelling dat elke Square-stap en -uitkomst registreert

Bestellingsbeheer

• Geverifieerde voltooiing: Bestellingen worden pas als betaald gemarkeerd nadat de betaling is geverifieerd tegen het Payment-object van Square — nooit op basis van een ongeverifieerd signaal
• 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

Square-account: Actief Square-verkopersaccount

Square-locatie: Een Square-locatie en de bijbehorende Location ID

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

Openbare HTTPS-site: Alleen vereist als u webhooks wilt; zonder webhooks worden betalingen via polling bevestigd

WCPOS: Pro-versie vereist voor POS-afrekenen

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 als de plugin.

Ondersteunde terminals

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

Bereik en beperkingen

Huidig bereik

• Gericht op POS- / order-pay-stromen. Beschikbaarheid in de klantgerichte storefront-checkout is standaard uitgeschakeld en moet expliciet worden ingeschakeld.
• Int alleen betalingen — terugbetalingen worden nog niet ondersteund. Square-identifiers worden op de bestelling opgeslagen zodat ondersteuning voor terugbetalingen later kan worden toegevoegd.
• Webhook-abonnementen moeten handmatig in Square worden toegevoegd; zie Webhooks.

Problemen oplossen

Veelvoorkomende problemen

De lijst Terminal Device is leeg

• De Terminal moet eerst met deze plugin worden gekoppeld — gebruik Create Device Code en voer de code in op het apparaat
• Een Terminal die via het Square Dashboard of de Square POS-app is gekoppeld, verschijnt pas nadat hij hier is gekoppeld
• Klik op Check for readers: verschijnt het apparaat onder Other devices Square can see, dan bestaat het wel maar is het niet met deze plugin gekoppeld
• Controleer of de Location ID overeenkomt met de locatie waarbij de Terminal is aangemeld

Apparaat kan niet koppelen

• Zorg dat u de apparaatcode hebt ingevoerd voordat deze verliep — genereer een nieuwe met Create Device Code
• Controleer of de terminal online is en is aangemeld bij hetzelfde Square-account en dezelfde Location ID als de plugin
• Controleer of de omgeving overeenkomt met het account waarbij de terminal is aangemeld

Instellingen valideren mislukt

• Bent u verbonden, controleer dan of de rij Square account nog steeds Connected to Square toont; wordt u gevraagd opnieuw verbinding te maken, dan is de autorisatie verlopen
• Gebruikt u een access token, controleer dan of die overeenkomt met de geselecteerde omgeving — een Sandbox-token werkt niet in Production, en omgekeerd
• Bevestig dat de Location ID bij dat account hoort

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

• Dit is precies wat webhooks oplossen. Zonder webhook wordt de bestelling bijgewerkt zodra polling of de achtergrondopruimer de betaling verwerkt
• Bekijk de rij Webhooks — staat daar Not verified yet nadat er al betalingen zijn gedaan, volg dan Als webhooks niet meer worden geverifieerd
• De bestelling gaat nooit verloren: de opruimer verwerkt elke betaling die de polling mist

Betaling start niet

• Controleer of er een terminal is geselecteerd en of het apparaat gekoppeld en online is
• Controleer of het apparaat is aangemeld bij de geconfigureerde Location ID
• Bekijk het betalingslogboek en WooCommerce > Status > Logs voor Square API-meldingen

Er wordt gemeld dat opnieuw verbinden met Square nodig is

Square-autorisaties worden automatisch vernieuwd. Als een vernieuwing niet kan worden voltooid, beëindigt de plugin de autorisatie in plaats van die in een onbruikbare staat te laten, en vraagt het instellingenscherm u om opnieuw verbinding te maken. Klik op Reconnect to Square — er hoeft verder niets te worden gewijzigd.

Hulp krijgen

Voor technische ondersteuning:

• Bezoek de GitHub-opslagplaats om problemen te melden
• Raadpleeg de Square Terminal API-documentatie voor hardware- en API-richtlijnen
• Neem contact op met Square-support voor account- en hardwareproblemen

Logs worden geschreven naar WooCommerce > Status > Logs onder de handle sqtwc en registreren elke apparaatopzoeking en webhook-uitkomst.

Schermafbeeldingen

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

• De secties Square account, Terminal en Advanced settings
• Gateway-inschakeling in WCPOS-instellingen
• Betalingsverwerking in de POS-checkout