Sign in
An image of the Stripe logo
Create account
Sign in
Home
Payments
Business operations
Financial services
Developer tools
All products
Home
Payments
Business operations
Home
Payments
Business operations
Financial services
Developer tools
Support
Overview
Overview
What is Terminal
Design an integration
Example applications
Quickstart
Accept an in-person payment
Set up your reader
Set up your integration
Connect to a reader
Collect payments
Regional considerations
Terminal payments features
Multiparty payments with Connect
Collect tips
Save cards for future use
Refund transactions
Provide receipts
Cart display
Incremental authorizations
Extended authorizations
Operate offline
Deploy at scale
Order hardware
Manage locations
Configure readers
References
API references
Bluetooth readers
Smart readers
SDK migration guide
Testing
Deployment checklist
Stripe Terminal reader product sheets
Testing
No-code options
Terminal
·
HomePaymentsIn-person payments

Connect to a reader

Connect your application to a Stripe Terminal reader.

If you haven’t chosen a reader yet, compare the available Terminal readers and choose one that best suits your needs.

Smart readers run Stripe reader software to communicate directly with Stripe over the internet. Connecting your app to a smart reader requires three steps:

  • Register a reader to your Stripe account
  • Discover readers with the SDK
  • Connect to a reader with the SDK

Register a reader
Server-side

Before you can connect your application to a smart reader, you must register the reader to your account.

Register in the Dashboard

The simplest way is to add your reader in the Dashboard.

  1. If you’ve already created a Location, click on it. Otherwise, create one by clicking + New.
  2. Under the Readers section, click + New.
  3. If you have a Verifone P400, enter the key sequence 0-7-1-3-9 to display a unique registration code. If you have a BBPOS WisePOS E, go to the settings then tap Generate pairing code.
  4. Enter the code when prompted.

Register using the API

For larger deployments, enable users in the field to receive and set up new readers on their own. In your app, build a flow to register a reader with the Stripe API.

  1. If you have a Verifone P400, enter the key sequence 0-7-1-3-9 to display a unique registration code. If you have a BBPOS WisePOS E, go to the settings then tap Generate pairing code.
  2. The user enters the code in your application.
  3. Your application sends the code to Stripe:
Terminal
curl https://api.stripe.com/v1/terminal/readers \ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \ -d "registration_code"="{{READER_REGISTRATION_CODE}}" \ -d "label"="Alice's Reader" \ -d "location"=
"{{LOCATION_ID}}"

To confirm that you’ve registered a reader correctly, list all the readers you’ve registered at that location:

Terminal
curl https://api.stripe.com/v1/terminal/readers \ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:

Discover readers
Client-side

SDK Reference

- discoverReaders (JavaScript)

After registering the reader to your account, search for previously registered readers to connect to your point of sale application using the discoverReaders method. You can scope your discovery using the location you registered the reader to in the previous step.

function discoverReaders() { const config = {simulated: false, location:
'{{LOCATION_ID}}'
} terminal.discoverReaders(config).then(function(discoverResult) { if (discoverResult.error) { console.log('Failed to discover: ', discoverResult.error); } else if (discoverResult.discoveredReaders.length === 0) { console.log('No available readers.'); } else { // You should show the list of discoveredReaders to the // cashier here and let them select which to connect to (see below). connectReader(discoverResult); } }); }

Connect to a reader
Client-side

To connect your point of sale application to a reader, call connectReader with the selected reader.

function connectReader(discoverResult) { // Just select the first reader here. var selectedReader = discoverResult.discoveredReaders[0]; terminal.connectReader(selectedReader).then(function(connectResult) { if (connectResult.error) { console.log('Failed to connect: ', connectResult.error); } else { console.log('Connected to reader: ', connectResult.reader.label); } }); }

Multiple connections

Only one instance of the Stripe Terminal SDK can be connected to a reader at a given time. By default, when you call connectReader from your app in a different browser tab or device, the incoming connection replaces the existing SDK-to-reader connection, and the previously connected SDK disconnects from the reader.

The connectReader method takes an optional configuration object with a fail_if_in_use property, whose default value is false. When your application sets fail_if_in_use to true, the connectReader call has an alternate behavior where the incoming connection fails when the reader is in the middle of a collectPaymentMethod or processPayment call initiated by another SDK.

If the reader is connected to another SDK but is idle (displaying the splash screen or displaying cart details before collectPaymentMethod is called), setting fail_if_in_use has no change to the connection behavior, and the incoming connection request can always break the existing SDK-to-reader connection.

terminal.connectReader(reader, {fail_if_in_use: true}).then(function(connectResult) { // ... });
fail_if_in_use is false (default)fail_if_in_use is true
connectReader called from a new SDK when the reader is idleThe existing SDK-to-reader connection breaks, and the new SDK connects to the reader. The next command from the previously-connected SDK fails with a reader error, and that app’s onUnexpectedReaderDisconnect method is called.The existing SDK-to-reader connection breaks, and the new SDK connects to the reader. The next command from the previously-connected SDK fails with a reader error, and that app’s onUnexpectedReaderDisconnect method is called.
connectReader called from a new SDK when the reader is mid-transactionThe existing SDK-to-reader connection breaks, and the new SDK connects to the reader. The next command from the previously-connected SDK fails with a reader error, and that app’s onUnexpectedReaderDisconnect method is called.The incoming connection fails with a reader error. The existing SDK-to-reader connection does not break and the command in progress continues.

For the least-disruptive connection experience in multi-reader environments, we recommend setting fail_if_in_use to true on your application’s initial connection attempt. Then, allow your users to retry the connection with fail_if_in_use set to false if the connection fails the first time. With this setup, one of your users can’t accidentally interrupt a transaction by inadvertently connecting to an in-use reader, but can still connect if needed.

Handle disconnects

SDK Reference

StripeTerminal.create (JavaScript)

Your app must implement the UnexpectedReaderDisconnect callback to handle when a reader is disconnected.

In your implementation of this callback, display a UI to notify the user that the reader disconnected. You may also want to call discoverReaders to begin scanning for readers and reconnect. Your app can attempt to automatically reconnect to the reader that was disconnected, or display a UI for your user to reconnect to another reader.

The reader can disconnect from your app if it loses connection to the internet. To simulate an unexpected disconnect, power off the reader.

var terminal = StripeTerminal.create({ onFetchConnectionToken: fetchConnectionToken, onUnexpectedReaderDisconnect: unexpectedDisconnect, }); function unexpectedDisconnect() { // You might want to display UI to notify the user and start re-discovering readers }

Automatic reconnection

Stripe Terminal doesn’t automatically reconnect to a reader when your application starts. Instead, you can build a reconnection flow by storing reader IDs and attempting to connect to a known reader on startup.

  1. When you successfully connect to a reader, save its serial number in a persistent data storage location, such as the localStorage API.
  2. When your app launches, check that persistent store for a saved serial number. If one is found, call the discoverReaders method so your application can try to find that reader again.
  3. If the saved serial number matches any of the discovered readers, try connecting to that reader with the matching reader object returned from the call to discoverReaders. If the previously connected reader isn’t found, stop the discovery process.

You should display some UI during the discovery and connection process indicating that an automatic reconnection is taking place.

Next steps

You’ve connected your application to the reader. Next, collect your first Stripe Terminal payment.

  • Collect payments

The BBPOS and Chipper™ name and logo are trademarks or registered trademarks of BBPOS Limited in the United States and/or other countries. The Verifone® name and logo are either trademarks or registered trademarks of Verifone in the United States and/or other countries. Use of the trademarks does not imply any endorsement by BBPOS or Verifone.

Was this page helpful?
Questions? Contact us.
View developer tutorials on YouTube.
Check out our product changelog.
Powered by Markdoc
You can unsubscribe at any time. Read our privacy policy.
On this page
Register a reader
Discover readers
Connect to a reader
Next steps
Stripe Shell
Test mode
▗▄ ▄▟█ █▀▀ ▗▟████▙▖ ██████ ███▗▟█ ███ ███▗▟██▙▖ ▗▟█████▙▖ ███▖ ▀▀ ███ ███▀▀▀ ███ ███▀ ███ ███ ███ ▝▜████▙▖ ███ ███ ███ ███ ███ █████████ ▄▄ ▝███ ███ ▄ ███ ███ ███▄ ███ ███ ▄▄ ▝▜████▛▘ ▝▜███▛ ███ ███ ███▝▜██▛▘ ▝▜█████▛▘ ███ ▀▘
Welcome to the Stripe Shell! Stripe Shell is a browser-based shell with the Stripe CLI pre-installed. Login to Stripe docs and press Control + Backtick on your keyboard to start managing your Stripe resources in test mode. - View supported commands: - Find webhook events: - Listen for webhook events: - Call Stripe APIs: stripe [api resource] [operation] (e.g. )
The Stripe Shell is best experienced on desktop.
$