Getting Started with the JavaScript SDK Beta
Set up the Stripe Terminal JavaScript SDK so you can begin accepting in-person payments with a Verifone P400 reader and your browser app.
Setting up the JavaScript SDK requires just three steps:
- Install the SDK in your app
- Set up the connection token endpoint in your app and backend
- Initialize the SDK in your app
Step 1: Install the SDK
To get started, include this script on your checkout page. This script must always load directly from https://js.stripe.com in order for your integration to stay compatible with the latest reader software. You can’t include it in a bundle or host a copy of it yourself.
<script src="https://js.stripe.com/terminal/v1/sdk-rc1.js"></script>Step 2: Set up the connection token endpoint
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 a connection token. 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'
# Using Sinatra
post 'terminal_connection_token' do
token = Stripe::Terminal::ConnectionToken.create
token.to_json
end
# 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"
# Flask
from flask import Flask, jsonify, request
@app.route('terminal_connection_token', methods=['POST'])
def terminal_connection_token():
token = stripe.terminal.ConnectionToken.create()
return jsonify(token)
// 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
var stripe = require("stripe")("sk_test_4eC39HqLyjWDarjtT1zdp7dc");
// Using Express
app.post('terminal_connection_token', async (req, res) => {
try{
const token = await stripe.terminal.connectionTokens.create();
res.status(200).json(token);
}catch(err){
res.status(500).end();
};
});
// 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";
// Using Spark framework (http://sparkjava.com)
post(new Route("terminal_connection_token") {
@Override
public Object handle(final Request request,
final Response response) {
try {
Map<String, Object> params = new HashMap<String, Object>();
ConnectionToken token = ConnectionToken.create(params);
return token.getRawJson();
} catch (StripeException e) {
response.status(500);
return e;
}
}
});
// 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"
// net/http
func terminalConnectionTokenHandler(w http.ResponseWriter, r *http.Request, customerId string) {
token, err := New(&stripe.TerminalConnectionTokenParams{})
if err != nil {
log.Printf("Stripe bindings call failed, %v\n", err)
w.WriteHeader(500)
return
}
w.Write(token.RawJSON)
}
To give the SDK access to this endpoint, create a function in your application that requests a connection token from your backend.
/**
* fetchConnectionToken() returns a connection token as a string
* e.g., "pst_test_xxxx"
*/
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;
}/**
* fetchConnectionToken() returns a Promise that asynchronously returns
* a connection token as a string, e.g., "pst_test_xxxx"
*/
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);
}This function is called whenever the SDK is initialized. It's also called when a new 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 token from your backend, connecting to a reader fails with that error.
Step 3: Initialize the SDK
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 client, provide the connection token 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.
const terminal = StripeTerminal.create({
onFetchConnectionToken: fetchConnectionToken,
onUnexpectedReaderDisconnect: unexpectedDisconnect,
});var terminal = StripeTerminal.create({
onFetchConnectionToken: fetchConnectionToken,
onUnexpectedReaderDisconnect: unexpectedDisconnect,
});Next steps
Congratulations! You integrated the Stripe Terminal SDK into your app. Next, either continue your software integration by using the simulated reader, or learn about physical readers and connecting to one.