# Set up your integration

Set up a Stripe Terminal SDK or server-driven integration to accept in-person payments.

# JavaScript


> #### Recommendation for smart readers
> 
> For smart readers, such as the [BBPOS WisePOS E reader](https://docs.stripe.com/terminal/payments/setup-reader/bbpos-wisepos-e.md), [Stripe Reader S700/S710](https://docs.stripe.com/terminal/readers/stripe-reader-s700-s710.md), and [Verifone readers](https://docs.stripe.com/terminal/payments/setup-reader/verifone.md), we recommend using the [server-driven integration](https://docs.stripe.com/terminal/payments/setup-integration.md?terminal-sdk-platform=server-driven) instead of the JavaScript SDK.
> 
> The JavaScript SDK requires your POS and reader on the same local network with working local DNS. The server-driven integration uses the Stripe API instead, which can be simpler in complex network environments. See our [platform comparison](https://docs.stripe.com/terminal/payments/setup-reader.md#sdk) to help you choose the best platform for your needs.

If you’re looking for a more detailed reference with all available methods, objects, and errors, consult our [full SDK reference](https://docs.stripe.com/terminal/references/api/js-sdk.md).

### Terminal JavaScript SDK requirements

When you integrate with [smart readers](https://docs.stripe.com/terminal/smart-readers.md) using the JavaScript SDK, make sure your network meets [our network requirements](https://docs.stripe.com/terminal/network-requirements.md).

Getting started with the JavaScript SDK requires three steps:

1. [Install the SDK and client library](https://docs.stripe.com/terminal/payments/setup-integration.md#install) on your checkout page.
2. [Set up the connection token endpoint](https://docs.stripe.com/terminal/payments/setup-integration.md#connection-token) on your web application app and backend.
3. [Initialize the SDK](https://docs.stripe.com/terminal/payments/setup-integration.md#initialize) in your web application.

> If you integrate your web application with the JavaScript SDK, you can run it in a mobile browser as long as the mobile device is connected to the same local network as the reader, and devices on that network can communicate directly with one another.

## Install the SDK and client library [Client-side] [Server-side]

#### 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.

```html
<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](https://github.com/stripe/terminal-js).

> For information on migrating from beta versions of the JavaScript SDK, see the [Stripe Terminal Beta Migration Guide](https://docs.stripe.com/terminal/references/sdk-migration-guide.md).

#### Server-side 

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

#### Ruby

```bash
# Available as a gem
sudo gem install stripe
```

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

## 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](https://docs.stripe.com/api/terminal/connection_tokens/object.md#terminal_connection_token_object-secret) from a [ConnectionToken](https://docs.stripe.com/api/terminal/connection_tokens.md). Your backend needs to only create connection tokens for clients that it trusts.

#### curl

```bash
curl https://api.stripe.com/v1/terminal/connection_tokens \
  -u <<YOUR_SECRET_KEY>>: \
  -X "POST"
```

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

#### Ruby

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

> The `secret` from the `ConnectionToken` lets you connect to any Stripe Terminal reader and take payments with your Stripe account. Be sure to authenticate the endpoint for creating connection tokens and protect it from cross-site request forgery (CSRF).

#### 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.

```javascript
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.

> Don’t cache or hardcode the connection token. The SDK manages the connection token’s lifecycle.

## Initialize the SDK [Client-side]

> Chrome 142 (released October 28, 2025) and later versions require explicit permission before websites can access local network devices (like Terminal readers) when using the Stripe Terminal JavaScript SDK. For setup steps and troubleshooting, see [Chrome 142+ instructions](https://support.stripe.com/questions/ensuring-stripe-terminal-javascript-sdk-functionality-on-chrome-142).

The [StripeTerminal](https://docs.stripe.com/terminal/references/api/js-sdk.md#stripeterminal-create) 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](https://docs.stripe.com/terminal/payments/setup-integration.md#connection-token).

You must also provide a function to handle unexpected disconnects from the reader, [onUnexpectedReaderDisconnect](https://docs.stripe.com/terminal/references/api/js-sdk.md#stripeterminal-create). 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](https://docs.stripe.com/terminal/payments/connect-reader.md?terminal-sdk-platform=js&reader-type=internet#handling-disconnects).

```javascript
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
}
```

## SDK updates

Stripe periodically releases updates which can include new functionality, bug fixes, and security updates. Update your SDK as soon as a new version is available. The currently available SDKs are:

- [Stripe Terminal Android SDK](https://github.com/stripe/stripe-terminal-android/releases)
- [Stripe Terminal iOS SDK](https://github.com/stripe/stripe-terminal-ios/releases)
- [Stripe Terminal JavaScript SDK](https://docs.stripe.com/terminal/references/api/js-sdk.md#changelog)
- [Stripe Terminal React Native SDK](https://github.com/stripe/stripe-terminal-react-native)

## Supported browsers

The Stripe Terminal JavaScript SDK strives to support all recent versions of major browsers. We support:

- Edge on Windows.
- Firefox on desktop platforms.
- Chrome and Safari on all platforms.
- The Android native browser on Android 4.4 and later.

If you have issues with the Stripe Terminal JavaScript SDK on a specific browser, email [support-terminal@stripe.com](mailto:support-terminal@stripe.com).

> Note: Using the Stripe Terminal JavaScript SDK with React Native isn’t supported. To build Stripe Terminal into your mobile app with React Native, use the [Stripe Terminal React Native SDK](https://github.com/stripe/stripe-terminal-react-native).

## Next steps

- [Connect to a reader](https://docs.stripe.com/terminal/payments/connect-reader.md?terminal-sdk-platform=js&reader-type=internet)