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 begins discovering readers with the given DiscoveryOptions.

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

    • discoveredReaders: A list of discovered readers that can be displayed to the cashier.
    • error: An error, if one occurred.

    The discoveredReaders list contains Reader objects with 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.

    DiscoveryOptions

    Parameter Description
    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.startReaderDiscovery(config, discoveredCallback, errorCallback)

    This method begins discovering readers continuously, which you can use to display an auto-updating list of available devices and their statuses in your app.”

    Parameter Description
    config

    A DiscoveryOptions object.

    discoveredCallback

    A method that takes a single parameter, a DiscoverResult object.

    errorCallback A method that takes a single error parameter.

    terminal.getDiscoveredReaders()

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

    terminal.stopReaderDiscovery()

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

    terminal.connectReader(reader)

    This method attempts to connect to the given Reader object.

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

    • connection: Additional information about the connection, including the connected reader.
    • 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 method begins collecting a payment method for a PaymentIntent. It takes a single argument: the client_secret field from a PaymentIntent object created on your backend.

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

    • paymentIntent: The updated PaymentIntent object, now with a payment_method.
    • error: An error, if one occurred, or if the cashier canceled the collection action.

    terminal.cancelCollectPaymentMethod()

    This method cancels an outstanding request to collect a payment method. Be sure to call this method when you no longer collect a payment method. This ensures that the reader display stops prompting the customer for a card.

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

    terminal.confirmPaymentIntent(paymentIntent)

    This method confirms a PaymentIntent after a payment method has been collected. It takes a single parameter, a PaymentIntent object obtained from a successful call to collectPaymentMethod.

    The method returns a Promise that resolves to an object with the following fields: - paymentIntent: The confirmed PaymentIntent object. - error: An error, if one occurred, including information about the 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 method 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:

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

    terminal.cancelReadSource()

    This method cancels an outstanding request to read a source. Be sure to call this method when you no longer want to read a source. This ensures that the reader display 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 its display with the given DisplayInfo. Currently, only the cart DisplayInfo object is supported.

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

    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.

    terminal.clearReaderDisplay()

    This method clears the reader display and resets it to the splash screen.

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