# Stripe Terminal Gateway

Stripe Terminal puts a Stripe card reader at your till. The till sends the amount to the reader, the customer taps, inserts or swipes their card on it, and the sale completes once Stripe captures the payment and nothing is left to pay. This page sets it up once, connects a reader on each till, and takes the first payment.

Already set up? [Connect a reader on this till](#card-readers) or [take a payment](#processing-payments).

Pro Feature

Stripe Terminal needs [WCPOS Pro](/de/getting-started/pro-license.md) 2.0.0 or newer. Without it the extension does nothing.

## Pick your readers[​](#readers "Direkter Link zu Pick your readers")

Stripe sells three kinds of reader. Which one a till can use depends on where the POS runs.

* **Smart reader** — works on every till: browser, desktop app, iPhone, iPad and Android. Stripe Reader S700 and S710, BBPOS WisePOS E. It sits on your network and your store sends it the payment.
* **Bluetooth reader** — the iOS and Android apps only. Stripe Reader M2, BBPOS WisePad 3. It pairs with the phone or tablet.
* **Tap to Pay** — coming to the iOS and Android apps in an app update. No reader: the customer taps their card on the phone itself.

A browser or the desktop app can't reach a Bluetooth reader or a phone's contactless chip, so those tills use a smart reader. Buy readers from the Terminal shop in your Stripe Dashboard.

Which Bluetooth reader

Stripe sells the **Stripe Reader M2** in the United States and the **BBPOS WisePad 3** outside it, in the UK, Europe, Canada, Australia and other countries. Check the Terminal shop for yours.

## Set up the gateway[​](#setup "Direkter Link zu Set up the gateway")

An administrator does this once per store, in WP Admin.

1. **Install the extension.** Download the plugin zip, `stripe-terminal-for-woocommerce.zip`, from the release assets on [GitHub](https://github.com/wcpos/stripe-terminal-for-woocommerce/releases) and upload it with `Plugins > Add Plugin`, then **Upload Plugin**. The GitHub "Source code" zip won't install.
2. **Add your keys.** Go to `WP Admin > WooCommerce > Settings > Payments`, open **Stripe Terminal**, and paste your **Live Secret Key**, plus the **Test Secret Key** if you want to try it first. Both come from your Stripe Dashboard. Once saved, a key shows as dots with *(saved; leave blank to keep)*.
3. **Choose a Terminal location** for Bluetooth readers and Tap to Pay. Create one in test mode and one in live mode in the Stripe Dashboard under **Terminal → Locations**, then pick them as **Terminal location (testing)** and **Terminal location (live)**.
4. **Tick the readers this store allows** under **POS connections**: **Smart readers**, **Bluetooth readers and Tap to Pay**, or both. For Bluetooth readers or Tap to Pay on the apps, tick **Bluetooth readers and Tap to Pay** and untick **Smart readers**. See [Smart readers, Bluetooth or both](#connections).
5. **Save the settings**, then check that the webhook row under them reads **Signing secret stored.**
6. **Turn it on for the POS.** Go to `WP Admin > POS > Settings > Checkout`, switch on **Stripe Terminal** and save. You don't need to enable it in WooCommerce's own payment list; see [Checkout Settings](/de/settings/checkout.md).

Choose a Terminal location before the first connection

Without one, a Bluetooth reader or Tap to Pay can't connect and the till shows *Select a Terminal location in the Stripe Terminal settings before connecting a mobile reader.*

Every setting on the gateway's page

* **Title** and **Description** — the name and line customers see. The till shows the title on the tile.
* **Live Secret Key** and **Test Secret Key** — from the Stripe Dashboard.
* **Default terminal** — the smart reader a till pays with until it picks another.
* **Enabled terminals** — limits tills to the smart readers you select. Leave it empty to allow every reader on the account.
* **Lock terminal selection** — *Cashiers cannot change the terminal at POS checkout.* Needs a **Default terminal**.
* **POS connections** — which kinds of reader tills may use: *Smart readers (the store drives the reader over the network)* and *Bluetooth readers and Tap to Pay (the POS app drives the reader)*. See [Smart readers, Bluetooth or both](#connections).
* **Terminal location (testing)** and **Terminal location (live)** — where Bluetooth readers and Tap to Pay register when the app connects them.
* **Test Mode** — *Enable Test Mode*. A site without HTTPS stays in test mode: Stripe Terminal needs HTTPS for live payments.
* **Phone Orders (MOTO)** — see [Take a phone order](#phone-orders-moto).
* **Reader Keep-Warm (Experimental)** — pings the reader so the first payment after a quiet spell isn't slow. Not recommended when several registers share one reader.

Below the fields, the page lists your **Stripe Terminal Locations** and the webhook row.

### Smart readers, Bluetooth or both[​](#connections "Direkter Link zu Smart readers, Bluetooth or both")

**POS connections** is a store setting: it decides which kind of reader every till uses.

* **Smart readers** only: every till pays with a smart reader.
* **Bluetooth readers and Tap to Pay** only: the iOS and Android apps pay with a Bluetooth reader or the phone. On a browser or desktop till, the Stripe tile is folded under **… not available right now**, with the line *Only the app's readers are allowed for this payment method. Allow smart readers on its WooCommerce settings page to pay from this till.*
* **Both**: tills use the smart readers.
  <!-- -->
  Bluetooth readers and Tap to Pay stay unused until you untick **Smart readers**.

Changing reader types or upgrading

Unticking a kind changes only what tills pay with next. Every payment refunds through the connection it was taken on, smart reader or app, and Stripe's webhook keeps working. An upgrade from an older version keeps the saved connection, or smart readers if only a **Default terminal** was saved. A new install has both ticked, so the apps use smart readers until you untick **Smart readers**.

## Connect a reader on this till[​](#card-readers "Direkter Link zu Connect a reader on this till")

Every till keeps its own reader. In the POS, tap **Settings** at the bottom of the side menu, then **Card readers**.

![Settings with Card readers chosen, on a till whose store has no card readers set up yet](/img/2.x/payment/gateways/stripe-terminal/en/tablet-light-regular--st-1-card-readers.png)1

1. **No card readers are set up for this store** — what the screen says until the gateway is [set up](#setup) with a reader kind this till can use. Once it is, the reader sections below that this till can use appear here instead (on a browser or desktop till, only **Smart readers**).

### Smart readers[​](#smart-readers "Direkter Link zu Smart readers")

Register each smart reader in the Stripe Dashboard with the code the reader shows. Until you do, it isn't listed under **Default terminal**, **Enabled terminals** or on the till.

The **Smart readers** section has one row per reader the store allows: the reader's name with the gateway's beside it, the Terminal location under it, and **Online** or **Offline**. The till pays with the row marked **Selected**. To switch, tap **Use this reader** on another online reader; checkout then pays with that one.

Which reader is used automatically?

* **Nothing chosen yet**: the till uses the **Default terminal** while it's online and free.
* **Only one smart reader in the store**: no choice is needed. While it's online and not busy with another sale, the till pays with it.
* **Set by the store**: the **Default terminal** under **Lock terminal selection**. While it's online it's **Selected** on every till, and no row offers **Use this reader**.

### Bluetooth readers[​](#bluetooth-readers "Direkter Link zu Bluetooth readers")

In the iOS or Android app:

1. Switch the reader on and keep it near the phone or tablet.
2. In **Settings → Card readers**, tap **Connect a reader**. A store with more than one reader gateway asks which: **Connect a reader with**, then **Stripe Terminal**.
3. The row reads *Looking for readers… Turn the reader on and keep it near this device.*, then *1 reader found. Is this yours?* or *3 readers found. Which one is yours?* Tap **Connect** beside yours.
4. **The first connection installs a reader software update.** The row reads **Installing reader software** with a progress bar, and *Keep the reader on and charged. The first update takes about 10 minutes.* Charge the reader above half before you start, and stay on the screen.
5. The row reads **Connected**, with the reader's battery, for example **Connected · 80%**.

Later connections take a few seconds, and the till reconnects to the same reader at the next sale. While no reader is connected, the **Bluetooth readers** section reads *No reader connected yet. Turn the reader on and keep it near this phone.*

### Tap to Pay[​](#tap-to-pay "Direkter Link zu Tap to Pay")

Tap to Pay is coming to the iOS and Android apps in an app update; this is how it works once your app has it.<!-- --> On a phone with the iOS or Android app, the **This phone** section has a **Tap to Pay on iPhone** or **Tap to Pay on Android** row. A shop manager or administrator taps **Set up Tap to Pay**. Anyone else sees **Not set up · ask an administrator**.

The first time, the phone asks you to accept the provider's terms: on an iPhone, Apple asks you to link an Apple ID and accept its Tap to Pay terms. Once set up, the row reads **Ready**. Tap to Pay needs a connection to take a payment.

What a reader row can say

Each reader row shows the reader's name, its serial number, the Terminal location and one line of state:

* **Connected · 80%** — ready to take payments, with the battery left. Tap to Pay reads **Ready**.
* **Not connected** — the till remembers this reader but isn't connected now. Tap **Connect**.
* **Connecting to …** — wait. The button reads **Connecting…**.
* **Installing reader software** — the update; see [Bluetooth readers](#bluetooth-readers), step 4.
* **No readers found. Turn the reader on and try again.** — tap **Try again**, or **Can't see your reader?** for the reader guide.
* **Could not connect: …** — Stripe's reason follows. Tap **Try again**, or **Help**.
* **Turn on Bluetooth to connect a reader.** — Bluetooth is off on this device.
* **Allow access to the reader in app settings.** — the app hasn't been given permission to use Bluetooth. Allow it in the phone's settings.

The **⋮** menu beside a row has **Forget**: the till stops reconnecting to that reader at the next sale. You can connect it again from this page. **Disconnect**, the button on a connected row, lets go of the reader for now. If a reader is stuck held by the app, the menu also offers **Release the reader**.

## Test before you go live[​](#testing "Direkter Link zu Test before you go live")

Tick **Test Mode** on the gateway's settings page (`WP Admin > WooCommerce > Settings > Payments > Stripe Terminal`) and save. Payments then go to Stripe's test account and no money moves. Run a test sale with the steps in [Take a payment](#processing-payments).

* **Smart readers**: a simulated reader registered on your Stripe test account is listed with your real ones, so you can run a sale without hardware.
* **Bluetooth readers** and real smart readers: pay with Stripe's physical test card, ordered from the Terminal shop in your Stripe Dashboard. The amount's last two digits decide the outcome: `.00` approves, `.05` declines, and `.02` asks for the PIN `1234`.

When you're done, untick **Test Mode** and save before you take a real payment.

## Take a payment[​](#processing-payments "Direkter Link zu Take a payment")

Open the register first

With **Open and close the register** switched on, the till won't record a payment while the register is closed, and a card you've already taken would have to be refunded. See [Open the Register](/de/sell/open-register.md).

1. Build the cart and press **Checkout**.

2. Tap the **Stripe Terminal** tile on the tender pane.

3. Check the reader. A smart reader reads **Terminal: …**, with **Change** to pick another when the store allows it. A Bluetooth reader reads **Connected · 80%**, or **No reader connected** with a link to **Settings → Card readers**.

4. Press **Send … to Stripe Terminal**, then let the customer pay:

   * **Smart reader**: the till reads **Waiting for the customer on the terminal** while the customer taps, inserts or swipes on the reader.
   * **Bluetooth reader**: the till reads **Present card on the reader**.
   * **Tap to Pay**: the phone shows its own Tap to Pay screen, and the customer taps their card or phone on yours.

   The till ticks off **Sent**, **On terminal**, **Approved** and **Captured**.

5. With nothing left to pay, the receipt screen opens: print or email the receipt, then press **New sale**. See [See it paid](/de/getting-started/make-sale.md#paid). If part of the total is left, take the rest another way; see [Split Payments](/de/sell/take-payment/split-payments.md).

To stop, press **Cancel on terminal**. A declined card shows **Payment failed: …** with **Try again** and **Choose another way**. See [On a Card Reader](/de/sell/take-payment.md#card-reader).

<!-- -->

Tips customers add on the reader land on the order as a **Tip** fee. The WisePad 3, WisePOS E, S700 and S710 can ask for a tip; the M2 can't. Turn on tipping for your readers in the Stripe Dashboard.

## Take a phone order (MOTO)[​](#phone-orders-moto "Direkter Link zu Take a phone order (MOTO)")

MOTO (mail order, telephone order) takes a card from a customer who isn't there: you key the card number into the reader's screen instead of tapping a card. It works on smart readers only, after Stripe turns it on for your account.

Set up and take a phone order

1. Ask [Stripe support](https://support.stripe.com/contact) to turn on MOTO for your account. It isn't on by default.
2. Tick **Phone Orders (MOTO)** on the gateway's settings page and save.
3. Use an S700, S710 or WisePOS E smart reader. Other readers, and simulated ones, don't offer it.

On the checkout's [**Legacy**](/de/sell/take-payment/legacy-tab.md) tab, Stripe Terminal normally shows a **Terminal** picker with **Send to terminal**, **Cancel** and **Try again**, recorded like a payment from the tender pane. While **Phone Orders (MOTO)** is ticked, the gateway's own payment page replaces that panel for every Stripe Terminal payment on the Legacy tab, not only phone orders.

A phone order runs on that payment page:

![The checkout's Legacy tab with Stripe Terminal chosen on the gateway's payment page, its Available Readers list starting below, and Process Payment](/img/2.x/payment/gateways/stripe-terminal/en/tablet-light-regular--st-2-legacy-stripe.png)123

1. **Legacy** — the tab that shows the store's own payment page inside the till.
2. **The store's payment page** — choose **Stripe Terminal** here, then scroll down to **Available Readers**, **Connect** and **Phone Order**.
3. **Process Payment** — the till's button under the page, as for any [Legacy](/de/sell/take-payment/legacy-tab.md) payment. A phone order starts with **Pay with Terminal** on the page.

1) On the **Legacy** tab, choose **Stripe Terminal**.
2) Under **Available Readers**, press **Connect** on your reader.
3) Switch on **Phone Order**.
4) Press **Pay with Terminal**. The reader shows a card entry screen instead of asking for a tap.
5) Key in the card number, expiry date and security code on the reader.

Tipp

Stripe treats a phone order as a card-not-present payment, so in-person card pricing and its fraud liability shift don't apply.

## If something goes wrong[​](#common-issues "Direkter Link zu If something goes wrong")

**The reader won't connect.** A smart reader must be on Wi-Fi or Ethernet, online in your Stripe Dashboard and registered there. A Bluetooth reader needs the iOS or Android app, Bluetooth on, and the app allowed to use Bluetooth.

**"Select a Terminal location…".** The gateway has no Terminal location for the mode it's in, test or live. See [Set up the gateway](#setup), step 3.

**The first connection is taking ages.** That's the reader's software update, about 10 minutes. Keep the reader on and charged, and stay on the screen. The next connection takes seconds.

**The Stripe tile says it's not available.** On a browser or desktop till, the store allows only the app's readers. See [Smart readers, Bluetooth or both](#connections). Offline, card readers wait for the connection; see [Offline Mode](/de/sell/offline-mode.md).

**Card readers says *Only the app's readers are allowed for this store.*** The same cause, on a browser or desktop till: allow **Smart readers** under **POS connections**, or use the iOS or Android app. See [Smart readers, Bluetooth or both](#connections).

**The card is declined.** Ask for another card or another way to pay. In test mode, check the amount's last two digits.

**No Phone Order switch.** Check that **Phone Orders (MOTO)** is ticked, that you're connected to an S700, S710 or WisePOS E, and that it isn't a simulated reader.

**A phone order fails.** Stripe hasn't turned on MOTO for your account yet, or the card details were keyed wrong.

**Still stuck?** Report a bug on [GitHub](https://github.com/wcpos/stripe-terminal-for-woocommerce/issues), check [Stripe's Terminal documentation](https://docs.stripe.com/terminal) for the reader, or contact Stripe support about your account.

## Related Documentation[​](#related-documentation "Direkter Link zu Related Documentation")

[Taking a PaymentHow a card reader payment runs on the tender pane](/de/sell/take-payment.md)

[Card ReadersChoose, connect, forget or release the reader on this till](/de/hardware/card-readers.md)

[The Legacy TabGateways that run on their own payment page](/de/sell/take-payment/legacy-tab.md)

[Payment GatewaysEvery gateway WCPOS works with](/de/settings/checkout/payment-gateways.md)