# Stripe Terminal Gateway

The Stripe Terminal gateway allows you to accept in-person payments using Stripe Terminal hardware readers directly within WCPOS: internet-connected readers from any till, and Bluetooth readers from the iOS and Android apps. A simulator mode is available for testing.

## Features[​](#features "Direct link to Features")

### Hardware Integration

Internet-connected readers from any till; Bluetooth readers from the iOS and Android apps

### Simulator Mode

Test payments without hardware using Stripe's simulator

### Real-time Processing

Instant payment processing and confirmation

### Secure Transactions

PCI-compliant payment processing through Stripe

### Phone Orders (MOTO)

Accept card payments over the phone by keying details into the reader

## Installation[​](#installation "Direct link to Installation")

1

### Install Stripe Terminal for WooCommerce

Install from `WP Admin > POS > Settings > Extensions`, or download the latest **plugin zip asset** (not the GitHub source-code zip or tarball) from the [GitHub releases page](https://github.com/wcpos/stripe-terminal-for-woocommerce/releases) and upload it via `Plugins > Add New > Upload Plugin`.

2

### Configure Stripe Settings

1. Navigate to `WP Admin > WooCommerce > Settings > Payments`
2. Find **Stripe Terminal** in the payment methods list
3. Click on **Stripe Terminal** to access settings
4. Enter your **Live Secret Key**, and your **Test Secret Key** if you want to test first (you can get both from your Stripe Dashboard)
5. For a Bluetooth reader or Tap to Pay, choose a **Terminal location (testing)** and a **Terminal location (live)**. Create these first in the Stripe Dashboard under **Terminal → Locations**: one in test mode and one in live mode
6. Save the settings

Choose a Terminal location

Without one, Bluetooth readers and Tap to Pay cannot connect, and you see `stripe_location_missing`: *Select a Terminal location in the Stripe Terminal settings before connecting a mobile reader.*

note

You do not need to enable the Stripe Terminal gateway in WooCommerce settings. It will be enabled specifically for the POS in the next step.

3

### Enable in WCPOS

1. Go to `WP Admin > POS > Settings > Checkout`
2. Find the **Stripe Terminal** gateway in the list
3. Enable the gateway for use in the POS
4. Save your settings

## Usage[​](#usage "Direct link to Usage")

### Connecting a Reader[​](#connecting-a-reader "Direct link to Connecting a Reader")

Choose **POS connection** on the gateway's settings page. One gateway drives one kind of reader:

* **Bluetooth reader or Tap to Pay** (the default on a new setup): the app drives the reader. Connect a Bluetooth reader in the app under **Settings → Card readers** with **Connect a reader** (see [Bluetooth readers](#bluetooth-readers)). For Tap to Pay, an administrator taps **Set up Tap to Pay** on the same page; other users see *Ask an administrator to set this up*.
* **Smart reader** (already selected if you saved a **Default terminal** before): the store drives the reader. Choose readers with **Default terminal** and **Enabled terminals** on the gateway's settings page. The tender pane shows the terminal the payment goes to, with **Change** to pick another unless **Lock terminal selection** is on.

Tap to Pay on iPhone

The first time you set up Tap to Pay on an iPhone, the app asks you to link an Apple ID and accept Apple's terms. You do this once per Stripe account. There is nothing extra to turn on at Stripe.

On the checkout's **Legacy** tab, the payment page shows a **Terminal** picker with **Send to terminal**, **Cancel** and **Try again**. While **Phone Orders (MOTO)** is enabled, the gateway keeps its own payment page there instead, as older versions of the extension do. That page offers:

1. **Choose Connection Method**: You can either connect a physical reader or use the simulator
2. **Physical Reader**: Follow the on-screen instructions to connect your Stripe Terminal device
3. **Simulator**: Select simulator mode to test various payment scenarios without hardware

### Processing Payments[​](#processing-payments "Direct link to Processing Payments")

1. **Add Items**: Add products to your cart in the POS and press **Checkout**
2. **Select Gateway**: Tap the Stripe Terminal tile on the tender pane. A version of the extension without a tender-pane tile is on the **Legacy** tab instead
3. **Check the Reader**: The tender pane shows which reader the payment goes to. When a Bluetooth reader isn't connected it shows **No reader connected**; connect one in **Settings → Card readers**
4. **Send Payment**: Press **Send** to send the amount to the reader, and the customer pays on it. The till shows each step
5. **Confirmation**: The sale completes when the reader approves the payment

### Testing with Simulator[​](#testing-with-simulator "Direct link to Testing with Simulator")

The simulator allows you to test various payment methods and scenarios:

* **Card Payments**: Test different card types (Visa, Mastercard, etc.)
* **Contactless Payments**: Simulate tap-to-pay transactions
* **Error Scenarios**: Test declined payments and other error conditions
* **Different Amounts**: Test various transaction amounts

### Phone Orders (MOTO)[​](#phone-orders-moto "Direct link to Phone Orders (MOTO)")

MOTO (Mail Order/Telephone Order) lets you process card payments for customers who aren't physically present — for example, when taking an order over the phone. Instead of tapping or inserting a card, the merchant keys the card details directly into the terminal reader's screen.

#### Setup[​](#setup "Direct link to Setup")

1

### Request MOTO access from Stripe

MOTO is not enabled by default. Contact [Stripe support](https://support.stripe.com/contact) and ask them to enable MOTO permissions for your account. This is a quick process but requires manual approval from Stripe.

2

### Enable in plugin settings

1. Navigate to `WP Admin > WooCommerce > Settings > Payments > Stripe Terminal`
2. Check the **Phone Orders (MOTO)** checkbox
3. Save the settings

3

### Connect a compatible reader

MOTO only works with compatible internet-connected readers listed in [Supported Terminals](#supported-terminals-internet-connected). The toggle will not appear for other reader types.

#### Taking a Phone Order[​](#taking-a-phone-order "Direct link to Taking a Phone Order")

1. Connect a compatible reader (see [Supported Terminals](#supported-terminals-internet-connected))
2. At the payment screen, toggle **Phone Order** on
3. Click **Collect Card Payment** — the reader will display a card number entry screen instead of prompting for a tap/insert
4. Key in the customer's card number, expiry, and CVV on the reader
5. The payment processes as normal from there

tip

MOTO payments use `card` as the payment method type rather than `card_present`. This means they are treated more like online transactions from Stripe's perspective, so standard online card processing fees apply rather than in-person rates.

caution

The Phone Order toggle only appears when all three conditions are met: the MOTO setting is enabled in plugin settings, a compatible reader is connected, and the reader is not a simulator. If you don't see the toggle, check these conditions.

## Requirements[​](#requirements "Direct link to Requirements")

Stripe Account

<!-- -->

: Active Stripe account with Terminal enabled

API Keys

<!-- -->

: Stripe secret key from your dashboard

WCPOS

<!-- -->

: Pro version required for POS checkout

HTTPS

<!-- -->

: Your site must use SSL/HTTPS for security

## Hardware Compatibility[​](#hardware-compatibility "Direct link to Hardware Compatibility")

Two kinds of reader work, and which one you can use depends on where the till runs:

* **Internet-connected readers** (smart readers) are driven by your store's server, so they work from every till — web browser, desktop app, iPhone, iPad and Android.
* **Bluetooth readers** are driven by the till itself, so they work from the **iOS and Android apps only**. A browser or the desktop app cannot talk to a Bluetooth reader.

Buy readers from the [Stripe Terminal shop](https://dashboard.stripe.com/terminal/shop) in your Stripe Dashboard.

### Internet-connected readers[​](#supported-terminals-internet-connected "Direct link to Internet-connected readers")

* **Stripe Reader S700/S710** ✅ - Ethernet/WiFi-connected terminal
* **WisePOS E** ✅ - WiFi-connected terminal

Register each smart reader in your Stripe Dashboard with the registration code from the reader. Until then it is not on the list under **Default terminal** and **Enabled terminals** on the gateway's settings page.

### Bluetooth readers (iOS and Android apps)[​](#bluetooth-readers "Direct link to Bluetooth readers (iOS and Android apps)")

* **BBPOS WisePad 3** ✅ - UK, Europe, Canada, Australia and other non-US regions
* **Stripe Reader M2** ✅ - United States
* **BBPOS Chipper 2X BT** ✅ - where Stripe still sells it

What to expect the first time you connect one:

1. In the app, go to **Settings → Card readers**, tap **Connect a reader**, switch the reader on and pick it from the list (it shows by serial number).
2. **The first connection installs a reader software update. Allow 8–10 minutes.** The till shows the percentage and the reader restarts partway through — that is part of the update. Keep the reader switched on and charged; do not leave the screen.
3. Later connections take a few seconds.

Reader location

Stripe registers a Bluetooth reader to a **Terminal Location** when it connects, and a reader can only be used in the country of its location: a WisePad 3 registered to a US location is refused with *"not supported in the United States"*. Create a Location for your country under **Stripe Dashboard → Terminal → Locations** and choose it on the gateway's settings page before the first connection.

Test mode

In test mode a Bluetooth reader accepts **only Stripe's physical test card** (ordered from the Dashboard's Terminal shop) — not a real card. Test cards decide the outcome by the amount's last two digits: `.00` approves, `.05` declines, `.02` asks for the PIN 1234.

### Common Issues[​](#common-issues "Direct link to Common Issues")

Reader won't connect

* Internet-connected readers: verify the terminal is on WiFi/Ethernet and online, that your Stripe account has Terminal enabled, and that the terminal is registered in your Stripe Dashboard
* Bluetooth readers: you need the iOS or Android app (not a browser or the desktop app), Bluetooth switched on, and on Android **Location** switched on as well — Android needs it to scan for Bluetooth devices
* *"not supported in the United States …"* (or another country): the gateway's Terminal Location is in the wrong country for that reader — see [Reader location](#bluetooth-readers)

The first connection is taking a long time

That is the reader's software update: 8–10 minutes on a WisePad 3, with a restart partway through. Keep the reader on and charged and stay on the screen; the next connection takes seconds.

Payment declined

* Check that your Stripe account is active and in good standing
* Verify the card being used is valid
* Ensure sufficient funds are available

Phone Order toggle not showing

* Verify the **Phone Orders (MOTO)** setting is enabled in `WooCommerce > Settings > Payments > Stripe Terminal`
* Make sure you're connected to a compatible reader (see [Supported Terminals](#supported-terminals-internet-connected)) — the toggle is hidden for other reader types
* The toggle does not appear when using the simulator

MOTO payment fails with an error

* Confirm that Stripe has enabled MOTO permissions on your account — contact [Stripe support](https://support.stripe.com/contact) if you haven't already
* Double-check that the card details were entered correctly on the reader
* MOTO payments may have stricter fraud checks — ensure the card is valid and has sufficient funds

SSL certificate errors

* Stripe Terminal requires HTTPS - ensure your site has a valid SSL certificate
* Check that your SSL certificate is properly configured

### Getting Help[​](#getting-help "Direct link to Getting Help")

For technical support:

* Visit the [GitHub repository](https://github.com/wcpos/stripe-terminal-for-woocommerce) to report issues
* Check the [Stripe Terminal documentation](https://stripe.com/docs/terminal) for hardware-specific guidance
* Contact Stripe support for account-related issues

## Screenshots[​](#screenshots "Direct link to Screenshots")

Screenshots will be added in a future update to show:

* Gateway configuration in WooCommerce payment settings
* POS checkout interface with Stripe Terminal selection
* Simulator testing interface with various payment methods
