Stripe Terminal: JS SDK Reference Invite Only

    Learn about additional JS SDK features

    This is the API reference for the Stripe Terminal JS SDK.

    The StripeTerminal object

    StripeTerminal.create([options])

    This method creates an instance of StripeTerminal, which facilitates communication between the browser and a reader options object. Available options are documented below:

    Option Description
    onFetchConnectionToken

    This is an event handler that fetches a connection token from your backend. It will be called when the SDK must begin discovery or must connect to readers.

    onUnexpectedReaderDisconnect optional

    This is an event handler that gets called when the terminal loses connection to its reader. Your application should respond by alerting the cashier to notice the lost connection, and to begin re-establishing connection.

    onConnectionStatusChange optional

    This is an event handler that gets called when a reader has a change in connection status. The method takes a single parameter, an event object. That object’s status key has a value set to one of connecting, connected, or not_connected. You can use onConnectionStatusChange to update the UI with visual indicators for the reader status.

    onPaymentStatusChange optional

    This is an event handler that gets called when a payment status change occurs during payment. The method takes a single parameter, an event object. That object’s status key has a value set to one of ready, attaching_source, or confirming_payment_intent. You can use onPaymentStatusChange to update the UI with a payment’s progress.

    Connecting to a reader

    terminal.discoverReaders([DiscoveryOptions])

    This method searches for registered readers. It returns a Promise, which resolves to a DiscoverResult object containing the following:

    • discoveredReaders: A list of discovered readers that can be displayed to the cashier.

    If an error occurred, the error field will be populated as follows.

    • error: The error, which contains a message field.

    Each Reader returned within the discoveredReaders and its fields is an object, containing the following fields:

    • id: The ID of the Reader object.
    • label: The reader’s label.
    • ip_address: The reader’s IP address, e.g., 127.0.0.1.
    • serial_number: The reader’s serial number.
    • device_type: The reader’s device type, e.g., verifone_P400.
    • status: The reader’s presumed state (online or offline).
    • location: The location to which this reader is registered.

    Additionally, each Reader object takes a DiscoveryOptions object as a parameter, to allow for better filtering of the readers.

    DiscoveryOptions

    Key in DiscoveryOptions Expected Value
    method optional

    Can be registered or simulated. If left empty, this value defaults to registered. With this default, discoverReaders returns physical readers that have been registered to your account. You can set this to simulated to discover a reader simulator, which you can use to test your integration without a physical reader.

    location optional

    Return only readers assigned to the given location. (Ignored if the discovery method is simulated.)

    terminal.startDiscovery(config, discoveredCallback, errorCallback)

    This method starts continuous discovery of devices, for cases where you want to display a continually updating list of available devices and their statuses.

    Parameter Description
    config

    This is a DiscoveryOptions object.

    discoveredCallback

    This is a method that takes a single parameter, of type DiscoverResult.

    errorCallback This is a method that takes a single parameter: the error that occurred during discovery.

    terminal.getDiscoveredReaders()

    This method should be called only after calling startDiscovery. It returns the most recent DiscoverResult object.

    terminal.stopDiscovery()

    This method should be called only after calling startDiscovery. It stops the continuous discovery.

    terminal.connectReader(reader)

    This is a method that takes a single parameter of type Reader, obtained from the discoverReaders call.

    It returns a Promise that resolves to an object with the following fields:

    • result.connection: Additional information about the connection, including the connected reader.
    • result.error: An error, if one occurred during connection.

    terminal.disconnectReader()

    This method should be called only after first establishing connection to a reader. It disconnects from the connected reader.

    terminal.getConnectionStatus()

    This method returns the reader’s current connection status, as one of: connecting, connected, or not_connected.

    terminal.clearConnectionToken()

    This method ensures that the cached connection token has been cleared, so that on the next attempt to connect to a reader, a new connection token will be fetched. This must be done in order to switch accounts.

    Payment Collection Methods

    terminal.collectPaymentMethod(paymentIntentClientSecret)

    This is a method that takes a single parameter of type string. This parameter’s value should be the client_secret field from a PaymentIntent object created on the backend.

    It returns a Promise that resolves to an object with the following fields:

    • result.paymentIntent: The updated paymentIntent object, with the payment_method field set.
    • result.error: An error, if one occurred, or if the cashier cancelled the collection action.

    terminal.cancelCollectPaymentMethod()

    This is a method that cancels an outstanding request (started via the readSource method) to read a source. Be sure to call this when you no longer want to collect a payment method. This ensures that the reader UI stops prompting the customer for a card.

    It returns a Promise that resolves to an empty object once the action has been successfully canceled.

    terminal.confirmPaymentIntent(paymentIntent)

    This is a method that takes a single parameter, of type PaymentIntent, obtained from the collectPaymentMethod call.

    It returns a Promise that resolves to an object with the following fields:

    • result.paymentIntent: The updated paymentIntent object, with the successful payment.
    • result.error: An error, if one occurred, including possible information about the payment decline.

    terminal.getPaymentStatus()

    This method returns the reader’s payment status, as one of: ready, collecting_payment_method, or confirming_payment_intent. This enum reflects which payment action the reader is performing, and can be useful for alerting the cashier that the reader is busy and currently performing an action.

    Reading a source without charging

    terminal.readSource()

    This is a method that prompts the customer to present a card to create a Source object on the Stripe backend. You should send the ID of the source to your backend for further processing. For example, you can use source’s fingerprint to look up a charge created using the same card.

    Note that sources created using this method cannot be charged. So, use this method to read payment details without charging the customer. If you are collecting a payment from a customer, instead use collectPaymentMethod and confirmPaymentIntent.

    The method returns a Promise that resolves to an object with the following fields:

    • result.source: The newly created source object.
    • result.error: An error, if one occurred.

    terminal.cancelReadSource()

    This is a method that cancels an outstanding request to read a source, started via the readSource method. Be sure to call this when you no longer want to read a source. This ensures that the reader UI stops prompting the customer for a card.

    It returns a Promise that resolves to an empty object once the action has been successfully canceled.

    Controlling the reader display

    terminal.setReaderDisplay(displayInfo)

    This is a method that instructs the reader to update the selected display. Currently, only the cart display can be updated. The displayInfo parameter is expected to be an object of the form shown below:

    {
      type: 'cart',
      cart: {
        lineItems: [
          {
            description: string,
            amount: number,
            quantity: number,
          },
        ],
        tax: number,
        total: number,
        currency: string,
      }
    }

    The setReaderDisplay method returns a Promise that resolves to an empty object once the action has been successfully completed.

    If the action fails, the Promise will resolve to an object with the error field present.

    terminal.clearReaderDisplay()

    This is a method that clears the reader display, and resets it to the splash screen. Be sure to call this when you no longer want to read a source. Doing so ensures that the reader UI stops prompting the customer for a card.

    This method returns a Promise that resolves to an empty object once the action has been successfully completed.

    If the action fails, the Promise will resolve to an object with the error field present.

    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.