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:

    1. Install the SDK in your app
    2. Set up the connection token endpoint in your app and backend
    3. 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.

    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.

    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.

    On this page