# Square Terminal Gateway

The till sends the amount to a [Square Terminal](https://squareup.com/hardware/terminal), the customer pays on the Terminal, and the sale moves on by itself when Square approves it. This page is in two parts: [taking a payment](#take-payment) at the till, and [setting it up](#setup) in WP Admin.

Pro Feature

Square Terminal needs [WCPOS Pro](/ja/getting-started/pro-license.md) 2.0 or newer.

<!-- -->

## Take a payment[​](#take-payment "Take a paymentへの直接リンク")

Before you start

* The till is online, and the Terminal is switched on. If the **Square Terminal** tile is missing, ask whoever runs WP Admin to [set it up](#setup).
* With **Open and close the register** switched on, the register is open. The till won't record a payment while it's closed, and a card already charged on the Terminal would have to be refunded. See [Open the Register](/ja/sell/open-register.md).

1. Build the cart and press **Checkout**.
2. On the **Payments** tab, tap the **Square Terminal** tile.
3. Check the terminal line, **Terminal:** and the Terminal's name. With more than one Terminal, press **Change** and tap the one at your till. Until you pick one, the pane says **Choose a terminal**.
4. Leave the amount as the balance due, or type a smaller amount to take part of it on the card. See [Split Payments](/ja/sell/take-payment/split-payments.md).
5. Press **Send $45.00 to Square Terminal** (the button names your amount). The pane shows **Starting the terminal…**, then **Waiting for the customer on the terminal**.
6. The customer taps, inserts or swipes their card on the Terminal.
7. When Square approves, the steps run through **Approved** and **Captured**. If that clears the balance, the sale completes and the receipt is shown; if not, take the rest the same way or another way.

While the payment runs, the pane shows:

* **ON THE TERMINAL** and the amount sent.
* One status line, such as **Waiting for the customer on the terminal**.
* The method and the Terminal's name.
* Four steps: **Sent**, **On terminal**, **Approved**, **Captured**.
* **Details**: each step Square reported, with the time, and the **Reader**, **Action** and **Payment** IDs. **Copy** (**Share** on some devices) hands the log to whoever helps you.

Payment status messages and what to do

* **Approved**, then **Captured**: the money is in. If that clears the balance, the receipt shows; if not, take the rest.
* **Payment cancelled**: the Terminal confirmed your cancel. Press **Try again** or **Choose another way**.
* **Timed out — payment cancelled**: nobody paid within 5 minutes. Press **Try again** or **Choose another way**.
* **Cancelling — waiting for the terminal to confirm**: the Terminal hasn't answered your cancel. Wait, or press **Release this payment**. See [Stop a payment](#stop).
* **Payment released**: the order is free to be paid another way, but the card may still have been charged on the Terminal. Look at the Terminal's screen first.

### Stop a payment[​](#stop "Stop a paymentへの直接リンク")

**Cancel on terminal** asks Square to cancel the payment on the Terminal. The pane says **Cancelling…**, and then **Payment cancelled** when the Terminal confirms. Press **Try again** to send it again, or **Choose another way** to go back to the tiles.

If the Terminal doesn't confirm (it's switched off, out of signal or stuck), the pane says **Cancelling — waiting for the terminal to confirm** and offers **Release this payment**, with the line *Frees the order to be paid another way. The store keeps checking the terminal.*

Check the Terminal before you charge again

Releasing doesn't cancel the payment at Square. The store keeps checking it in the background, about every 10 minutes. Look at the Terminal's screen before you take the money another way. If it shows the payment went through, don't take the money again: the store records that payment on the order at one of its next checks. See [If something goes wrong](#goes-wrong).

**Release this payment** frees the order; it doesn't confirm the payment was cancelled. The pane says **Payment released**. Before you press **Choose another way**, check the Terminal: if it shows the payment went through, don't charge again, and wait for the order to update. If it shows the payment was cancelled, **Choose another way** takes you back to the tiles to take the money another way. If you can't tell (the Terminal is off, has no signal or shows nothing), the result is unknown: if you take the money another way and the store's check later finds the Terminal payment, it records that payment on the order too, and you refund one of the two from the order. See [Refunds](/ja/manage-store/orders/refund-rules.md).

If nobody pays on the Terminal within 5 minutes, the payment is cancelled and the pane says **Timed out — payment cancelled**.

## If something goes wrong[​](#goes-wrong "If something goes wrongへの直接リンク")

**No terminals set up for Square Terminal.** No Terminal is paired with the extension yet. Ask whoever runs WP Admin to [pair one](#pairing).

**In use by order #…** That Terminal is running another order's payment. Finish or cancel that payment first, or pick another Terminal.

**Payment failed** and a reason. Press **Try again**, or **Choose another way**. **Details** shows what Square said.

**Cancelling — waiting for the terminal to confirm.** The Terminal hasn't answered the cancel. Wait, or press **Release this payment**. See [Stop a payment](#stop).

**The Terminal paid but the till is still waiting.** The till keeps asking Square while it waits and moves on when Square answers; with a [webhook](#webhooks) the store hears sooner. If the till stops waiting (it's closed, or you release the payment), the store's background check, about every 10 minutes, records a payment the till missed. Don't take the money another way while you wait: look at the Terminal's screen first.

**The tile isn't there.** The gateway isn't switched on for the POS. See [Turn it on for the POS](#enable).

Setup problems, for whoever runs WP Admin

The Terminal isn't in the list

It has to be paired with this extension: use **Create Device Code** and enter the code on the Terminal. A Terminal paired through the Square Dashboard or the Square app doesn't show until it's paired here. If **Check for readers** lists it under *Other devices Square can see at this location*, it exists but belongs to another application. Also check the **Location ID** matches the location the Terminal is signed in to.

The Terminal won't pair

The code lasts 5 minutes: create a fresh one. The Terminal must be online and signed out of the Square app or any other integration, because the code signs it in to the account and **Location ID** set here. The **Environment** must match that account.

Validate Settings fails

If you connected, check the **Square account** row still says **Connected to Square**. With your own access token, check it's for the selected **Environment**: a sandbox token doesn't work in **Live**, and the other way round. Check the **Location ID** belongs to that account.

Reconnect to Square required

Square authorizations renew by themselves. When a renewal can't finish, the extension ends the authorization and asks you to reconnect. Press **Reconnect to Square**; nothing else needs changing.

Where to find the logs

`WooCommerce > Status > Logs`, source `square-terminal-for-woocommerce`. Key steps are also written to the order's notes, starting `Square Terminal:`.

## Set it up[​](#setup "Set it upへの直接リンク")

This part is for whoever runs the store's WP Admin. Your store sends each payment to Square, and Square sends it to the paired Terminal, so the till needs a connection to the store. Do these four in order:

1. [Install the extension](#install) from the extension directory.
2. [Connect to Square](#connect) and choose the location.
3. [Pair your Terminal](#pair-your-terminal), or use Square's test devices in sandbox.
4. [Turn it on for the POS](#enable).

### Install the extension[​](#install "Install the extensionへの直接リンク")

Open `WP Admin > POS > Settings > Extensions`, find **Square Terminal**, click **Install**, then **Activate**. See [Installing an Extension](/ja/manage-store/add-ons.md#installing-an-extension).

Without the directory, download the **plugin zip** (not the source-code zip) from the [GitHub releases page](https://github.com/wcpos/square-terminal-for-woocommerce/releases) and upload it with `Plugins > Add Plugin`, then **Upload Plugin**. Without WCPOS Pro 2.0 the extension does nothing and says it needs it.

### Connect to Square[​](#connect "Connect to Squareへの直接リンク")

1. Go to `WP Admin > WooCommerce > Settings > Payments` and open **Square Terminal**.
2. Under **Square account**, choose the **Environment**: **Test mode (sandbox)** (the default) to try it out, or **Live** for real payments. Choose it **before** you connect: a connection covers one environment only.
3. Click **Connect to Square** and approve what Square asks for.
4. Choose the **Location ID**: the Square location the Terminal takes payments for.
5. Under **Which Square device do you use?**, leave **Square Terminal**.

Already using the official WooCommerce Square plugin? **Environment** and **Location ID** are pre-filled from it. Save to apply. No credentials are shared between the two plugins, so you still connect here.

Prefer your own access token? Open **Advanced settings** and paste a **Sandbox Access Token** or **Production Access Token** instead of connecting.

### Pair your Terminal[​](#pair-your-terminal "Pair your Terminalへの直接リンク")

Under **Terminal**, click **Create Device Code** and enter the code on the Terminal within 5 minutes. Then click **Check for readers**. The full steps, what the list shows and the sandbox test devices are in [Paired Terminals and test devices](#pairing).

### Turn it on for the POS[​](#enable "Turn it on for the POSへの直接リンク")

Go to `WP Admin > POS > Settings > Checkout`, find **Square Terminal** and switch **Enabled** on. See [Enabling a Gateway](/ja/settings/checkout.md#enabling-a-gateway).

ノート

Square Terminal is for staff at the till only; it's never offered at your online shop's checkout. The **Enabled** toggle on the WooCommerce **Payments** list has no effect on it.

## Paired Terminals and test devices[​](#pairing "Paired Terminals and test devicesへの直接リンク")

A Terminal has to be paired with **this extension** before a cashier can pick it. Pairing makes a Square *device code*, and that's the only way the extension can reach the Terminal.

1. Under **Terminal**, click **Create Device Code**. The screen shows *Pairing code: … — enter it on the Terminal within 5 minutes.*
2. On the Terminal, open the device-code sign-in screen and enter the code. If the Terminal is signed in to the Square app or another integration, sign it out of that first: the device-code screen isn't reachable while it's in use elsewhere.
3. Click **Check for readers**. The Terminal now shows under **Paired with this plugin — selectable at checkout**.

**Check for readers** lists what Square can see, in two groups:

* **Paired with this plugin — selectable at checkout**: the Terminals cashiers can pick.
* **Other devices Square can see at this location**: Terminals set up by another application. They can't be picked here until you pair them with a fresh code.

**Validate Settings** asks Square whether your connection (or access token) and the location work. When they do, it says *Square credentials and location verified.*

An empty list before pairing is normal

Square only lists Terminals paired with a device code. A Terminal running the Square app doesn't appear at all until a device code is entered on it.

Test mode: Square's test devices instead of a Terminal

In **Test mode (sandbox)** there are no device codes and nothing to pair. The till lists Square's test devices instead, where a paired Terminal would be. Each one plays out one result without hardware:

| Test device                                   | What it plays out                                                                                                               |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **Sandbox: Success (charge $25 or less)**     | An approved card payment. Keep the amount at $25 or less.                                                                       |
| **Sandbox: Success with 20% tip**             | A payment with a tip. Square takes no tips here, so it ends in a failed payment: **The terminal confirmed a different amount**. |
| **Sandbox: Buyer cancels on terminal**        | The customer cancels on the Terminal.                                                                                           |
| **Sandbox: Immediate timeout**                | Nobody pays, and the payment times out straight away.                                                                           |
| **Sandbox: Offline terminal (stays pending)** | A Terminal that never answers. Use it to try [Stop a payment](#stop) without hardware.                                          |

## Webhooks[​](#webhooks "Webhooksへの直接リンク")

A webhook is **optional**. It lets Square tell your store the moment a payment changes, so the till moves on sooner. Without one, the till asks Square for the result while it waits, and the store's background check, about every 10 minutes, records any result the till missed. Either way, the store records a payment only when Square confirms the payment itself; a checkout Square marks finished isn't enough on its own.

Add a webhook

This only works if you set the extension up with your own access token, under **Advanced settings**. If you used **Connect to Square**, you authorized the WCPOS application, not one of your own, so you have no application to add a subscription to and no signature key to copy. Payments still confirm through the till's own checks and the background check.

With your own access token, use your application in the [Square Developer Dashboard](https://developer.squareup.com/apps):

1. On the settings screen, in the **Webhooks** row under **Terminal**, click **Copy** to copy the webhook URL.
2. In the Square Developer Dashboard, open your application and go to **Webhooks**.
3. Add a subscription for the **`terminal.checkout.updated`** event, with that URL as the notification URL.
4. Copy the subscription's **Signature Key** into **Webhook Signature Key** under **Advanced settings**, and save.

The **Webhooks** row then says **Verified … ago** once a signed webhook has arrived.

The URL must match exactly

Square signs each webhook with the notification URL it was given. If the URL in Square differs from the one on the settings screen by a single character, every delivery fails. Use **Copy** rather than typing it.

Upgrading from version 0.x

Version 1.0.0 shows a new webhook URL. If you already have a subscription, edit its notification URL in Square to the one the settings screen shows now; editing keeps its signature key. **Webhook URL override** doesn't change this URL; it only applies to the extension's own payment page. If your site's public address differs from the one shown, its webhooks won't verify: payments still confirm through the till's own checks and the background check.

Square's webhook subscriptions belong to a Square application and can't be added with a seller's access token, so the extension can't add the subscription for you.

### If webhooks stop verifying[​](#webhook-troubleshooting "If webhooks stop verifyingへの直接リンク")

The **Webhooks** row says **Not verified yet** until a webhook arrives and verifies under the **current** settings.

Payments have run and it still says Not verified yet

Check:

1. **Webhook Signature Key** matches the subscription's key in Square.
2. The notification URL in Square matches the settings screen exactly.
3. The subscription includes `terminal.checkout.updated`.
4. Your site is reachable from the internet over HTTPS. Square's dashboard shows each delivery attempt.

Changing the environment, the webhook URL or the signature key resets the row until the next webhook arrives. That's on purpose: a webhook verified under the old settings says nothing about the new ones.

## Settings reference[​](#settings "Settings referenceへの直接リンク")

On `WP Admin > WooCommerce > Settings > Payments > Square Terminal`, in the order setup runs. Open a group to see its settings.

Square account

* **Environment**: **Test mode (sandbox)** (default) or **Live**. A connection covers one environment.
* **Connect to Square**: authorizes this site with Square. Shows **Connected to Square**, the merchant and **Disconnect** once done.
* **Location ID**: the Square location the Terminal takes payments for.
* **Which Square device do you use?**: **Square Terminal** (this page, the default) or **Square Reader**.

Terminal

* **Create Device Code**, **Check for readers**, **Validate Settings**: pair a Terminal, list what Square can see, check the setup. See [Paired Terminals and test devices](#pairing).
* **Webhooks**: whether a signed webhook has arrived, and the URL to **Copy**. See [Webhooks](#webhooks).

Checkout behaviour

* **Skip receipt screen**: the Terminal goes back to idle without showing its own receipt screen.
* **Collect signature**: asks the customer to sign on the Terminal, where the payment supports it.
* **Checkout debug logs**: a copyable log panel on the extension's own payment page. For support; safe to leave off.

Advanced settings

* **Sandbox Access Token**, **Production Access Token**: only needed if you don't connect above.
* **Webhook Signature Key**: optional. Lets the store verify webhooks; payments confirm without it.
* **Webhook URL override**: for the extension's own payment page only. See [Webhooks](#webhooks).

**Advanced settings** is closed by default on the settings screen too.

## Square Reader instead of a Terminal[​](#square-reader "Square Reader instead of a Terminalへの直接リンク")

Set **Which Square device do you use?** to **Square Reader** to take the payment in the Square Point of Sale app, with a Square Reader paired to that phone or tablet. The settings screen then shows a five-step checklist, **Set up your Square Reader**.

The five Square Reader setup steps

1. Connect your Square account.
2. Choose your location.
3. Register your store with Square: paste your **Application ID**.
4. Give Square your store's return address.
5. Set up the phone or tablet.

At the till, the payment runs on the extension's own payment page, on the [Legacy tab](/ja/sell/take-payment/legacy-tab.md): press **Open Square Point of Sale** and finish the payment in the Square app. It works only:

* in **Live**, not in test mode;
* on an Android or iOS phone or tablet with the Square Point of Sale app installed. Anywhere else the button is turned off and says why.

## Refunds[​](#refunds "Refundsへの直接リンク")

Refund a Square Terminal payment from the order, and the money goes back to the customer's card through Square. Part refunds work too. See [Refunds](/ja/manage-store/orders/refund-rules.md).

A payment taken on the extension's own payment page, such as one from a version before 1.0.0, is refunded from the Square Dashboard instead.

## Requirements[​](#requirements "Requirementsへの直接リンク")

WCPOS Pro

<!-- -->

: Version 2.0.0 or newer

Square account

<!-- -->

: An active Square seller account and a Square location

Square Terminal

<!-- -->

: Online, and paired with this extension by a device code for your Square account and location (see Paired Terminals and test devices above)

Connection

<!-- -->

: The till and the store must be online. The store sends each payment to the paired Terminal, so any till can use any paired Terminal

Public HTTPS site

<!-- -->

: Only for webhooks; payments confirm without them

## Related Documentation[​](#related-documentation "Related Documentationへの直接リンク")

* [Taking a Payment: On a Card Reader](/ja/sell/take-payment.md#card-reader)
* [The Tender Pane](/ja/sell/take-payment/payment-screen.md)
* [Cancelling a Payment](/ja/sell/take-payment/cancel-payment.md)
* [Square Terminal API documentation](https://developer.squareup.com/docs/terminal-api/overview), for hardware and API questions
* Report a problem with the extension on [GitHub](https://github.com/wcpos/square-terminal-for-woocommerce). Square support handles account and hardware questions.

[CheckoutRing up a sale from start to finish](/ja/getting-started/make-sale.md)

[Payment GatewaysEvery gateway you can use at the till](/ja/settings/checkout/payment-gateways.md)

[RefundsGive money back on a finished sale](/ja/manage-store/orders/refund-rules.md)