Connect to a reader

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 discoverReaders returns a result, call connectReader to connect to the simulated reader.

// Handler for a "Connect Reader" button
async function connectReaderHandler() {
  const config = {simulated: true};
  const discoverResult = await terminal.discoverReaders(config);
  if (discoverResult.error) {
    console.log('Failed to discover: ', discoverResult.error);
  } else if (discoverResult.discoveredReaders.length === 0) {
    console.log('No available readers.');
  } else {
    // Just select the first reader here.
    const selectedReader = discoverResult.discoveredReaders[0];

    const connectResult = await terminal.connectReader(selectedReader);
    if (connectResult.error) {
      console.log('Failed to connect: ', connectResult.error);
    } else {
      console.log('Connected to reader: ', connectResult.reader.label);
    }
  }
}

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.

The simulator configuration accepts either a testCardNumber or a testPaymentMethod options. To enable this behavior, insert this line of code before you call collectPaymentMethod:

terminal.setSimulatorConfiguration({testCardNumber: '4242424242424242'});

For more details about the configuration options API, see the Stripe Terminal JavaScript API reference.