Connect to a reader

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:

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:

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

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);
    }
  });
}

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

terminal.connectReader(reader, {fail_if_in_use: true}).then(function(connectResult) {
  // ...
});

Handle disconnects

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.