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
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
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 and upload it via Plugins > Add New > Upload Plugin.
Configure Stripe Settings
- Navigate to
WP Admin > WooCommerce > Settings > Payments - Find Stripe Terminal in the payment methods list
- Click on Stripe Terminal to access settings
- Enter your Live Secret Key, and your Test Secret Key if you want to test first (you can get both from your Stripe Dashboard)
- 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
- Save the settings
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.
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.
Enable in WCPOS
- Go to
WP Admin > POS > Settings > Checkout - Find the Stripe Terminal gateway in the list
- Enable the gateway for use in the POS
- Save your settings
Usage
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). 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.
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:
- Choose Connection Method: You can either connect a physical reader or use the simulator
- Physical Reader: Follow the on-screen instructions to connect your Stripe Terminal device
- Simulator: Select simulator mode to test various payment scenarios without hardware
Processing Payments
- Add Items: Add products to your cart in the POS and press Checkout
- 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
- 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
- Send Payment: Press Send to send the amount to the reader, and the customer pays on it. The till shows each step
- Confirmation: The sale completes when the reader approves the payment
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)
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
Request MOTO access from Stripe
MOTO is not enabled by default. Contact Stripe support and ask them to enable MOTO permissions for your account. This is a quick process but requires manual approval from Stripe.
Enable in plugin settings
- Navigate to
WP Admin > WooCommerce > Settings > Payments > Stripe Terminal - Check the Phone Orders (MOTO) checkbox
- Save the settings
Connect a compatible reader
MOTO only works with compatible internet-connected readers listed in Supported Terminals. The toggle will not appear for other reader types.
Taking a Phone Order
- Connect a compatible reader (see Supported Terminals)
- At the payment screen, toggle Phone Order on
- Click Collect Card Payment — the reader will display a card number entry screen instead of prompting for a tap/insert
- Key in the customer's card number, expiry, and CVV on the reader
- The payment processes as normal from there
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.
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
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 in your Stripe Dashboard.
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)
- 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:
- 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).
- 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.
- Later connections take a few seconds.
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.
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
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
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) — 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 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
For technical support:
- Visit the GitHub repository to report issues
- Check the Stripe Terminal documentation for hardware-specific guidance
- Contact Stripe support for account-related issues
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