Sign in
An image of the Stripe logo
Create account
Sign in
Home
Payments
Business operations
Financial services
Developer tools
Security
All products
Home
Payments
Business operations
Home
Payments
Business operations
Financial services
Developer tools
Support
Overview
Overview
What is Terminal
Design an integration
Example applications
Quickstart
Accept an in-person payment
Set up your reader
Set up your integration
Connect to a reader
Collect payments
Regional considerations
Terminal payments features
Multiparty payments with Connect
Collect tips
Save cards for future use
Refund transactions
Provide receipts
Cart display
Incremental authorizations
Extended authorizations
Deploy at scale
Order hardware
Manage locations
Configure readers
References
API references
Bluetooth readers
Smart readers
SDK migration guide
Testing
Deployment checklist
Stripe Terminal reader product sheets
Testing
No-code options
terminal
·
HomePaymentsIn-person payments

Set up your integration

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

SDK Reference

If you’re looking for a more detailed reference with all available methods, objects, and errors, consult our full SDK reference.

Getting started with the JavaScript SDK requires three steps:

  1. Install the SDK and client library 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

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

Use the Terminal JS SDK as a module

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

For information on migrating from beta versions of the JavaScript SDK, see the Stripe Terminal Beta Migration Guide.

Server-side

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

Terminal
# Available as a gem sudo gem install stripe
Gemfile
# 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 from a ConnectionToken. Your backend should only create connection tokens for clients that it trusts.

Terminal
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

The ConnectionToken’s secret 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.

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(function(response) { return response.json(); }) .then(function(data) { 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 is unable to retrieve a new connection token from your backend, connecting to a reader fails with the error from your server.

Do not cache or hardcode the connection token. The SDK manages the connection token’s lifecycle.

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, }); function unexpectedDisconnect() { // You might want to display UI to notify the user and start re-discovering readers }

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’ve setup the Stripe Terminal SDK. Next, connect your application to the reader.

  • Connect to a reader

Supported browsers

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

  • Internet Explorer 11 and 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, please email 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, please wrap the native Stripe Terminal SDKs for Android and iOS by following the Android and iOS native modules guidelines.

Was this page helpful?
Questions? Contact us.
View developer tutorials on YouTube.
Check out our product changelog.
Powered by Markdoc
You can unsubscribe at any time. Read our privacy policy.
On this page
Install the SDK and client library
Set up the ConnectionToken endpoint
Initialize the SDK
SDK updates
Next steps
Supported browsers
Stripe Shell
Test mode
▗▄ ▄▟█ █▀▀ ▗▟████▙▖ ██████ ███▗▟█ ███ ███▗▟██▙▖ ▗▟█████▙▖ ███▖ ▀▀ ███ ███▀▀▀ ███ ███▀ ███ ███ ███ ▝▜████▙▖ ███ ███ ███ ███ ███ █████████ ▄▄ ▝███ ███ ▄ ███ ███ ███▄ ███ ███ ▄▄ ▝▜████▛▘ ▝▜███▛ ███ ███ ███▝▜██▛▘ ▝▜█████▛▘ ███ ▀▘
Welcome to the Stripe Shell! This is a graphical user interface of the Stripe CLI. You can use it to discover webhook events and manage your Stripe resources. By pressing ctrl + ` you can toggle it open from any page within the Stripe documentation. - View supported commands: - Listen for webhook events: - Trigger webhook events: - Call Stripe APIs: stripe [api resource] [api operation] (e.g. )
The Stripe Shell is best experienced on desktop.
$