— No Results

    Getting Started with the JavaScript SDK

    Set up the Stripe Terminal JavaScript SDK so you can begin accepting in-person payments with a Verifone P400 reader and your website.

    Getting started with the JavaScript SDK requires four steps:

    1. Install the SDK on your checkout page
    2. Set up the connection token endpoint on your backend and web application
    3. Initialize the SDK in your web application
    4. Connect to the simulated reader

    Step 1: Install the SDK Client-side

    To get started, include this script on your checkout page. This script must always load directly from https://js.stripe.com for compatibility with the latest reader software. Do not include the script in a bundle or host a copy yourself; this could break your integration without warning. 

    <script src="https://js.stripe.com/terminal/v1/"></script>

    Step 2: Set up the ConnectionToken endpoint Server-side Client-side

    Server-side

    To connect to a reader, your backend needs to give the SDK permission to use the reader with your Stripe account, by providing it with the secret from a ConnectionToken. Your backend should only create connection tokens for clients that it trusts.

    curl https://api.stripe.com/v1/terminal/connection_tokens \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -X POST


    # Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

# In a new endpoint on your server, create a ConnectionToken and return the
# `secret` to your app. The SDK needs the `secret` to connect to a reader.
Stripe::Terminal::ConnectionToken.create

    # Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

# In a new endpoint on your server, create a ConnectionToken and return the
# `secret` to your app. The SDK needs the `secret` to connect to a reader.
stripe.terminal.ConnectionToken.create()

    // Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

// In a new endpoint on your server, create a ConnectionToken and return the
// `secret` to your app. The SDK needs the `secret` to connect to a reader.
stripe.terminal.connectionTokens.create();

    // Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

// In a new endpoint on your server, create a ConnectionToken and return the
// `secret` to your app. The SDK needs the `secret` to connect to a reader.
\Stripe\Terminal\ConnectionToken::create();

    // Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

// In a new endpoint on your server, create a ConnectionToken and return the
// `secret` to your app. The SDK needs the `secret` to connect to a reader.
Map<String, Object> params = new HashMap<String, Object>();
ConnectionToken.create(params);

    // Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"

// In a new endpoint on your server, create a ConnectionToken and return the
// `secret` to your app. The SDK needs the `secret` to connect to a reader.
params := &stripe.TerminalConnectionTokenParams{}
connectiontoken, err := connectiontoken.New(params)

    // Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

// In a new endpoint on your server, create a ConnectionToken and return the
// `secret` to your app. The SDK needs the `secret` to connect to a reader.
var options = new ConnectionTokenCreateOptions{};
var service = new ConnectionTokenService();
ConnectionToken connectionToken = service.Create(options);

    Client-side

    To give the SDK access to this endpoint, create a function in your web application that requests a ConnectionToken from your backend and returns the secret from the ConnectionToken object.

    function fetchConnectionToken() {
  // Your backend should call /v1/terminal/connection_tokens and return the JSON response from Stripe
  return fetch('https://{YOUR_BACKEND_URL}/connection_token', { method: "POST" })
    .then(response => response.json())
    .then(data => data.secret);
}
    async function fetchConnectionToken() {
  // Your backend should call /v1/terminal/connection_tokens and return the JSON response from Stripe
  const response = await fetch('https://{YOUR_BACKEND_URL}/connection_token', { method: "POST" });
  const data = await response.json();
  return data.secret;
}

    This function is called whenever the SDK is initialized. It’s also called when a new ConnectionToken is needed to connect to a reader (for example, when your app disconnects from a reader). If the SDK is unable to retrieve a new ConnectionToken from your backend, connecting to a reader fails with the error from your server.

    Step 3: Initialize the SDK Client-side

    The StripeTerminal object made available by the SDK exposes a generic interface for discovering readers, connecting to a reader, and creating payments. To initialize a StripeTerminal instance in your JavaScript application, provide the ConnectionToken function implemented in Step 2.

    You must also provide a function to handle unexpected disconnects from the reader, onUnexpectedReaderDisconnect. In this function, your app should notify the user that the reader disconnected. You can also include a way to attempt to reconnect to a reader. For more information, see Handling disconnects.

    var terminal = StripeTerminal.create({
  onFetchConnectionToken: fetchConnectionToken,
  onUnexpectedReaderDisconnect: unexpectedDisconnect,
});
    const terminal = StripeTerminal.create({
  onFetchConnectionToken: fetchConnectionToken,
  onUnexpectedReaderDisconnect: unexpectedDisconnect,
});

    Step 4: Connect to the simulated reader Client-side

    The Stripe Terminal SDK comes 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 just starting out, use the simulated reader to emulate all the Terminal flows in your app: connecting to a reader, updating reader software, and collecting payments.

    Note that the simulated reader does not provide a UI. After connecting to it in your app, you can see it working when calls to the Stripe SDK succeed.

    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
function connectReaderHandler() {
  const config = {simulated: true};
  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 {
      // 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);
        }
      });
    }
  });
}
    // 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);
    }
  }
}

    SDK updates

    Stripe periodically releases updates to the Stripe Terminal JavaScript SDK, the Stripe Terminal iOS SDK, and the Stripe Terminal Android SDK, which can include new functionality, bug fixes, and security updates. Update your integrated version of the Stripe Terminal JavaScript, iOS, or Android SDK as soon as a new version is available.

    Next steps

    Congratulations! You integrated the Stripe Terminal SDK into your app and connected to a simulated reader. Next, either continue your integration using the simulated reader to collect payments, or learn about physical reader types.

    Was this page helpful? Yes No

    Send

    Thank you for helping improve Stripe's documentation. If you need help or have any questions, please consider contacting support.

    Questions?

    We're always happy to help with code or other questions you might have. Search our documentation, contact support, or connect with our sales team. You can also chat live with other developers in #stripe on freenode.

    On this page