JavaScript API Reference Beta

    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

    A required event handler that fetches a connection token from your backend.

    onUnexpectedReaderDisconnect

    A required event handler called when a reader disconnects from your app. Use this handler to alert your user when a reader disconnects, and (optionally) begin rediscovering and connecting to a reader.

    onConnectionStatusChange optional

    An optional event handler called when the status of the connection to the reader changes. A connection status can be one of connecting, connected, or not_connected. Use this handler to update your app’s UI with the reader’s status connection status.

    onPaymentStatusChange optional

    An optional event handler called when the status of a payment changes. A payment status can be one of not_ready, ready, waiting_for_input, or processing. Use this handler to update your app’s UI as a payment proceeds.

    discoverReaders([DiscoveryOptions])

    Begins discovering readers with the given DiscoveryOptions. Returns a Promise that resolves to a DiscoverResult object.

    DiscoveryOptions

    Parameter Description
    simulated optional

    A boolean value indicating whether to simulate discovery. If left empty, this value defaults to false. For more information on using the simulator, see our Reader Simulator guide.

    location optional

    Return only readers assigned to the given location. This parameter is ignored for simulated discovery. For more information on using locations to manage readers, see our Fleet Management guide.

    DiscoverResult

    Field Description
    discoveredReaders optional

    A list of discovered Reader objects.

    error optional

    An error, if discovering readers failed.

    connectReader(reader)

    Attempts to connect to the given Reader object. Be sure to connect to a Reader object that has been recently discovered. Connecting to a stale Reader object can fail if the reader’s IP address has changed.

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

    • reader: The connected reader, if connecting succeeded.
    • error: An error, if connecting failed.

    For more information on connecting to a reader, see our Connecting to a Reader guide.

    disconnectReader()

    Disconnects from the connected reader.

    For more information on connecting to a reader, see our Connecting to a Reader guide.

    getConnectionStatus()

    Returns the current connection status. A connection status can be one of connecting, connected, or not_connected.

    getPaymentStatus()

    Returns the reader’s payment status. A payment status can be one of not_ready, ready, waiting_for_input, or processing.

    clearCachedCredentials()

    Clears the current connection token, and any other cached credentials. Use this method to switch accounts in your app (e.g., to switch between live and test Stripe API keys on your backend).

    Follow these steps to switch accounts in your app:

    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(paymentIntentClientSecret)

    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.

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

    • paymentIntent: The updated PaymentIntent object.
    • error: An error, if one occurred.

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

    cancelCollectPaymentMethod()

    Cancels an outstanding request to collect a payment method.

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

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

    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.

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

    • paymentIntent: The confirmed PaymentIntent object, if processing succeeded.
    • error: An error, if one occurred.

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

    readReusableCard()

    Begins reading a card for use 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:

    • paymentMethod: The PaymentMethod object.
    • error: An error, if one occurred.

    For more information on saving cards, see our Saving Cards guide.

    cancelReadReusableCard()

    Cancels an outstanding request to read a reusable card. Returns a Promise that resolves to an empty object once the action has been successfully canceled.

    setReaderDisplay(displayInfo)

    Instructs the reader to update its display with the given DisplayInfo. Currently, only the cart DisplayInfo object is supported.

    {
      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 once the action has been successfully completed. If updating the reader display fails, the Promise resolves to an object with the error field present.

    For more information on configuring the reader’s cart display, see our Cart Display guide.

    clearReaderDisplay()

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

    Returns a Promise that resolves to an empty object once the action has been successfully canceled. If canceling fails, the Promise resolves to an object with the error field present.

    Error codes

    Error 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, update to the latest release by changing URL of the script your integration includes.

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

    2019-04-18 – v1 Release Candidate

    • Renamed confirmPaymentIntent to processPayment.
    • Renamed the values for payment status. Payment status can be one of not_ready, ready, waiting_for_input, or processing.
    • Changed the response of connectReader to { reader: Reader }, removing the wrapper Connection object.
    • Removed the startReaderDiscover and stopReaderDiscovery methods. To repeatedly discover readers, you can use the JavaScript setInterval method.
    • Changed the API for discovering a simulated reader to discoverReaders({ simulated: true}).
    • Switched from Sources to PaymentMethods. Receipt information is now in paymentIntent.charges[0].payment_method_details.card_present.
    • Renamed clearConnectionToken to clearCachedCredentials.
    • Removed details in the response to collectPaymentMethod under response.paymentIntent.payment_method.card_payment.
    • Renamed readSource to readReusableCard. A successful readReusableCard returns a PaymentMethod instead of a Source.

    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