Connect to a reader

Connect your application to a Stripe Terminal reader.

Note

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

Stripe Terminal SDKs and server-driven integration come with a built-in simulated card reader, so you can develop and test your app without connecting to physical hardware. Whether your integration is complete or you’re still building it, use the simulated reader to emulate all the Terminal flows in your app.

The simulated reader doesn’t provide a UI. After connecting to it in your app, you can see it working when calls to the Stripe SDK or API succeed.

Simulated readers for SDKs automatically simulate card presentment as needed. For the server-driven integration, update your integration to simulate card presentment.

To use the simulated reader, call discoverReaders to search for readers, with the simulated option set to true. When the onUpdateDiscoveredReaders callback is called with an array of the readers as an argument, call connectReader to connect to the simulated reader.

When connecting to a mobile reader or to a TapToPay reader, your integration must include the locationId in the connection configuration, even for the simulated reader. Because the simulated reader can’t be associated with a real location, provide the simulated reader’s mock locationId instead.

DiscoverReadersScreen.tsx
function DiscoverReadersScreen() {
  const { discoverReaders, connectReader, discoveredReaders } =
    useStripeTerminal({
      onUpdateDiscoveredReaders: (readers) => {
        // After the SDK discovers a reader, your app can connect to it.
        // Here, we're automatically connecting to the first discovered reader.
        handleConnectBluetoothReader();
      },
    });

  useEffect(() => {
    handleDiscoverReaders();
  }, []);

  const handleDiscoverReaders = async () => {
    // The list of discovered readers is reported in the `onUpdateDiscoveredReaders` method
    // within the `useStripeTerminal` hook.
    const { error } = await discoverReaders({
      discoveryMethod: 'bluetoothScan',
      simulated: true,
    });

    if (error) {
      Alert.alert(
        'Discover readers error: ',
        `${error.code}, ${error.message}`
      );
    }
  };

  const handleConnectBluetoothReader = async () => {
    const { reader, error } = await connectReader({
        reader: discoveredReaders[0],
        // Since the simulated reader is not associated with a real location, we recommend
        // specifying its existing mock location.
        locationId: discoveredReaders[0].locationId,
      },
      'bluetooth'
    );

    if (error) {
      console.log('connectReader error', error);
      return;
    }

    console.log('Reader connected successfully', reader);
  };

  return <View />;
}

Simulated Reader configuration

The simulated reader supports a small amount of configuration, enabling you to test different flows within your point of sale application such as different card brands or error scenarios like a declined charge. To enable this behavior, use the following code before you collect your payment method:

SimulatorSettingsScreen.tsx
const { error } = await setSimulatedCard('4242424242424242');

if (error) {
  // Placeholder for handling exception
}

// Placeholder for handling successful operation

Next steps

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

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.