JavaScript API Reference

    Use our API reference to navigate the Stripe Terminal JavaScript SDK.

    API methods

    StripeTerminal.create([options])

    Creates an instance of StripeTerminal with the given options:

    Option Description
    onFetchConnectionToken

    An event handler that fetches a connection token from your backend.

    onUnexpectedReaderDisconnect

    An event handler called when a reader disconnects from your app.

    onConnectionStatusChange optional

    An event handler called when the SDK’s ConnectionStatus changes.

    onPaymentStatusChange optional

    An event handler called when the SDK’s PaymentStatus changes.

    discoverReaders([options])

    Begins discovering readers with the given options:

    Option Description
    simulated optional

    A boolean value indicating whether to discover a simulated reader. If left empty, this value defaults to false.

    location optional

    Return only readers assigned to the given location. This parameter is ignored when discovering a simulated reader.

    For more information on using locations to filter discovered readers, see Fleet Management.

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

    • discoveredReaders: A list of discovered Reader objects, if the command succeeded.
    • error: An error, if the command failed.

    connectReader(Reader)

    Attempts to connect to the given reader.

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

    • reader: The connected Reader, if the command succeeded.
    • error: An error, if the command failed.

    disconnectReader()

    Disconnects from the connected reader.

    getConnectionStatus()

    Returns the current connection status.

    ConnectionStatus can be one of connecting, connected, or not_connected.

    getPaymentStatus()

    Returns the reader’s payment status.

    PaymentStatus can be one of not_ready, ready, waiting_for_input, or processing.

    clearCachedCredentials()

    Clears the current ConnectionToken, and any other cached credentials.

    Use this method to switch accounts in your application (e.g., to switch between live and test Stripe API keys on your backend). To switch accounts, follow these steps:

    1. If a reader is connected, call disconnectReader.
    2. Configure your onFetchConnectionToken handler to return connection tokens for the new account.
    3. Call clearCachedCredentials.
    4. Reconnect to a reader. The SDK will request a new connection token from your onFetchConnectionToken handler.

    collectPaymentMethod(client_secret)

    Begins collecting a payment method for a PaymentIntent.

    This method takes a single argument, the client_secret field from a PaymentIntent object created on your backend. For more information on passing the client secret to the client side, see our Payment Intents Quickstart.

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

    For more information on collecting payments, see our Collecting Payments guide.

    cancelCollectPaymentMethod()

    Cancels an outstanding collectPaymentMethod command.

    Returns a Promise that resolves to an empty object once the command has been successfully canceled. If cancelation fails, the Promise resolves to an object with an error

    processPayment(PaymentIntent)

    Processes a payment after a payment method has been collected.

    This method takes a single parameter, a PaymentIntent object obtained from a successful call to collectPaymentMethod.

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

    readReusableCard()

    Reads a card for reuse online.

    Online payments initiated from Terminal do not benefit from the lower pricing and liability shift given to standard Terminal payments. Most integrations do not need to use readReusableCard. To simply collect an in-person payment from a customer, use the standard flow.

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

    cancelReadReusableCard()

    Cancels an outstanding readReusableCard command.

    Returns a Promise that resolves to an empty object once the command has been successfully canceled. If cancelation fails, the Promise resolves to an object with an error.

    setReaderDisplay(DisplayInfo)

    Updates the reader display with cart details.

    This method takes a DisplayInfo object as input.

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

    Returns a Promise that resolves to an empty object if the command succeeds. If the command fails, the Promise resolves to an object with an error.

    clearReaderDisplay()

    Clears the reader display and resets it to the splash screen.

    Returns a Promise that resolves to an empty object if the command succeeds. If the command fails, the Promise resolves to an object with an error.

    Errors

    Errors returned by the JavaScript SDK include an error code, as well as a human-readable message.

    For methods involving a PaymentIntent like processPayment, the error may also include a payment_intent object.

    Error codes

    Code Description
    no_established_connection The command failed because no reader is connected.
    no_active_collect_payment_method_attempt cancelCollectPaymentMethod can only be called when collectPaymentMethod is in progress.
    no_active_read_reusable_card_attempt cancelCollectReusableCard can only be called when readReusableCard is in progress.
    canceled The command was canceled
    cancelable_already_completed Cancelation failed because the operation has already completed.
    cancelable_already_canceled Cancelation failed because the operation has already been canceled.
    network_error An unknown error occurred when communicating with the server or reader over the network. Refer to the error message for more information.
    network_timeout The request timed out when communicating with the server or reader over the network. Make sure both your device and the reader are connected to the network with stable connections.
    already_connected connectReader failed because a reader is already connected.
    failed_fetch_connection_token Failed to fetch a connection token. Make sure your connection token handler returns a promise that resolves to the connection token.
    discovery_too_many_readers discoverReaders returned too many readers. Use Locations to filter discovered readers by location.
    invalid_reader_version The reader is running an unsupported software version. Please allow the reader to update and try again.
    reader_error The reader returned an error while processing the request. Refer to the error message for more information.

    Changelog

    If you are using an earlier version of the JavaScript SDK (before June 7, 2019), update to the latest release by changing the URL of the script your integration includes.

    <script src="https://js.stripe.com/terminal/v1/"></script>
    

    For more information on migrating from the Stripe Terminal beta, see the Terminal Beta Migration Guide.

    v1

    • Renamed confirmPaymentIntent to processPayment.
    • Renamed the values for PaymentStatus. PaymentStatus can be one of not_ready, ready, waiting_for_input, or processing.
    • Removed card details from the response to collectPaymentMethod, previously available in response.paymentIntent.payment_method.card_payment.
    • Receipt information is now located in the paymentIntent.charges[0].payment_method_details.card_present hash.
    • Changed the API for discovering a simulated reader to discoverReaders({ simulated: true }).
    • Renamed readSource to readReusableCard. A successful call to readReusableCard returns a PaymentMethod instead of a Source. Payment Methods must be used with Payment Intents. For more information, see the Payment Methods API overview.
    • Changed the response of connectReader to { reader: Reader }, removing the wrapper Connection object.
    • Removed the startReaderDiscovery and stopReaderDiscovery methods. To repeatedly discover readers, you can use the JavaScript setInterval method.
    • Renamed clearConnectionToken to clearCachedCredentials.

    Was this page helpful?

    Thank you for helping improve Stripe's documentation. If you need help or have any questions, please consider contacting support.

    On this page