Set up your integration

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. Don’t include the script in a bundle or host a copy yourself; this might break your integration without warning.

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

Use the Terminal JS SDK as a module

We also provide an npm package to load and use the Terminal JS SDK as a module. For more information, check out the project on GitHub.

Server-side

Use our official libraries for access to the Stripe API from your application:

# Available as a gem
sudo gem install stripe

# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

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 needs to only create connection tokens for clients that it trusts.

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

Obtain the secret from the ConnectionToken on your server and pass it to the client side.

post '/connection_token' do
  token = # ... Create or retrieve the ConnectionToken
  {secret: token.secret}.to_json
end

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.

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 needs to authenticate with Stripe or the Reader. It’s also called when a new connection token is needed to connect to a reader (for example, when your app disconnects from a reader). If the SDK can’t retrieve a new connection token from your backend, connecting to a reader fails with the error from your server.

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 needs to 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.

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

function unexpectedDisconnect() {
  // You might want to display UI to notify the user and start re-discovering readers
}