JavaScript API reference
Use our API reference to navigate the Stripe Terminal JavaScript SDK.
API methods
- StripeTerminal.create()
- discoverReaders()
- connectReader()
- disconnectReader()
- getConnectionStatus()
- getPaymentStatus()
- clearCachedCredentials()
- collectPaymentMethod()
- cancelCollectPaymentMethod()
- processPayment()
- collectSetupIntentPaymentMethod()
- cancelCollectSetupIntentPaymentMethod()
- confirmSetupIntent()
- readReusableCard()
- cancelReadReusableCard()
- setReaderDisplay()
- clearReaderDisplay()
- setSimulatorConfiguration()
- getSimulatorConfiguration()
- collectRefundPaymentMethod()
- processRefund()
- cancelCollectRefundPaymentMethod()
- collectInputs()
- cancelCollectInputs()
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. |
readerBehavior optional | An object that sets the behavior on the reader throughout the lifecycle of the SDK. See below for readerBehavior configuration options. |
Reader Behavior Configuration
Today, there is only one behavior configuration option:
Behavior | Description |
---|---|
allowCustomerCancel | A Boolean that determines whether the customer can cancel Note: This property isn’t broadly available, and we’re not accepting users at this time. |
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 For more information on using locations to filter discovered readers, see Manage locations. |
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.
Note
Before you can discover the Verifone P400 in your application, you must register the reader to your account.
connectReader(reader, connectOptions)
Attempts to connect to the given reader with the given options:
Option | Description |
---|---|
fail_if_in_use optional | A Boolean value indicating that the connection fails if the reader is currently connected to a Terminal SDK. If left empty, this value defaults to false . |
Returns a Promise
that resolves to an object with the following fields:
Note
Don’t cache the Reader
object in your application. Connecting to a stale Reader
can fail if the reader’s IP address has changed.
disconnectReader()
Disconnects from the connected reader.
getConnectionStatus()
Returns the current connection status.
ConnectionStatus can be one of connecting
, connected
, or not_
.
getPaymentStatus()
Returns the reader’s payment status.
PaymentStatus can be one of not_
, ready
, waiting_
, or processing
.
clearCachedCredentials()
Clears the current ConnectionToken, and any other cached credentials.
Use this method to switch accounts in your application (for example, to switch between live and test Stripe API keys on your backend). To switch accounts, follow these steps:
- If a reader is connected, call
disconnectReader
. - Configure your
onFetchConnectionToken
handler to return connection tokens for the new account. - Call
clearCachedCredentials
. - Reconnect to a reader. The SDK requests a new connection token from your
onFetchConnectionToken
handler.
collectPaymentMethod(request, options)
Begins collecting a payment method for a PaymentIntent. This method takes one required parameter, request
:
request
: TheclientSecret
field from aPaymentIntent
object created on your backend. Learn how to create a PaymentIntent and pass its client secret.options
: An object containing additional payment parameters.
Option | Description |
---|---|
config_override optional | An object that allows you to specify configuration overrides per transaction. This object defaults to null.
|
The following option is available for the tipping
object:
Option | Description |
---|---|
eligible_amount optional | A number that allows you to specify the amount of a transaction that percentage-based tips are calculated against. Set this value to 0 or higher. If it’s equal to 0, tipping is skipped regardless of the value of If it’s equal to the PaymentIntent amount, the parameter is ignored and the tip is calculated based on the specified amount.
|
Returns a Promise
that resolves to an object with the following fields:
paymentIntent
: The updated PaymentIntent object, if the command succeeded.error
: An error, if the command failed.
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 when command has been successfully canceled. If cancellation fails, the Promise
resolves to an object with an error
processPayment(paymentIntent, options)
Processes a payment after a payment method has been collected.
This method takes one required parameter, paymentIntent
:
paymentIntent
: APaymentIntent
object obtained from a successful call tocollectPaymentMethod
.options
: An object containing additional payment parameters.
Returns a Promise
that resolves to an object with the following fields:
paymentIntent
: The confirmed PaymentIntent object, if the command succeeded.error
: An error, if the command failed. For more information, see Handling processing failures.
collectSetupIntentPaymentMethod(clientSecret, customerConsentCollected, config)
Begins collecting a payment method for online reuse for a SetupIntent.
The method takes two required parameters:
clientSecret
: TheclientSecret
field from aSetupIntent
object created on your backend.customerConsentCollected
: A Boolean value indicating whether you have collected a customer’s consent to save their cards.config
: an optional object containing collection configuration.
Option | Description |
---|---|
enable_customer_cancellation | Optional, defaults to false. If true, Android-based smart readers show a cancel button. |
Returns a Promise
that resolves to an object with the following fields:
setupIntent
: The updated SetupIntent object, if the command succeeded.error
: An error, if the command failed.
For more information on saving cards, see our Saving cards for online payments guide.
cancelCollectSetupIntentPaymentMethod()
Cancels an outstanding collectSetupIntentPaymentMethod command.
Returns a Promise
that resolves to an empty object when the command has been successfully canceled. If cancellation fails, the Promise
resolves to an object with an error
confirmSetupIntent(setupIntent)
Confirms a SetupIntent after a payment method has been collected.
This method takes a single parameter, a SetupIntent
object obtained from a successful call to collectSetupIntentPaymentMethod
.
Returns a Promise
that resolves to an object with the following fields:
setupIntent
: The confirmed SetupIntent object, if the command succeeded.error
: An error, if the command failed.
readReusableCard()
Reads a card for online reuse.
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 only collect an in-person payment from a customer, use the standard flow.
Returns a Promise
that resolves to an object with the following fields:
payment_
: The PaymentMethod object, if the command succeeded.method error
: An error, if the command failed.
Note
Currently, you can’t use Stripe Terminal to save contactless cards and mobile wallets (for example, Apple Pay, Google Pay) for later reuse.
cancelReadReusableCard()
Cancels an outstanding readReusableCard command.
Returns a Promise
that resolves to an empty object when the command has been successfully canceled. If cancellation 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()
If the reader is displaying cart details set with setReaderDisplay
, this method clears the screen 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.
setSimulatorConfiguration(configuration)
Sets the configuration object for the simulated card reader.
This method only takes effect when connected to the simulated reader; it performs no action otherwise.
The simulated reader will follow the specified configuration only until processPayment
is complete. At that point, the simulated reader will revert to its default behavior.
Note that this method overwrites any currently active configuration object; to add specific key-value pairs to the object, make sure to use a combination of this method and getSimulatorConfiguration
.
The configuration options available are:
Field | Values | Description |
---|---|---|
testCardNumber | Refer to the Simulated test cards list. | Configures the simulated reader to use a test card number as the payment method presented by the user. Use it to test different scenarios in your integration, such as payments with different card brands or processing errors like a declined charge. |
testPaymentMethod | Refer to the Simulated test cards list. | Serves the same purpose as testCardNumber , but relies on test payment methods instead. |
tipAmount | Any amount or null. | Configures the simulated reader to simulate an on-reader tip amount selected by the customer. |
paymentMethodType deprecated |
| Determine the type of payment method created by the simulated reader when collectPaymentMethod is called. |
getSimulatorConfiguration()
Returns the currently active configuration object.
The Stripe Terminal JavaScript SDK may overwrite this value as necessary, including (but not limited to) resetting the value after processPayment is complete, and removing unknown key-value pairs.
collectRefundPaymentMethod(charge_id, amount, currency, options, config)
Begins collecting a payment method to be refunded. The method takes two required parameters:
charge_
, the ID of the charge that will be refunded.id amount
: a number that represents the amount, in cents, that will be refunded from the charge. This number must be less than or equal to the amount that was charged in the original payment.currency
: Three-letter ISO code for the currency, in lowercase. Must be a supported currency.options
: an optional object containing additional refund parameters.
Option | Description |
---|---|
refund_application_fee | Optional, defaults to false. Connect only. Boolean indicating whether the application fee should be refunded when refunding this charge. If a full charge refund is given, the full application fee will be refunded. Otherwise, the application fee will be refunded in an amount proportional to the amount of the charge refunded. An application fee can be refunded only by the application that created the charge. |
reverse_transfer | Optional, defaults to false. Connect only. Boolean indicating whether the transfer should be reversed when refunding this charge. The transfer will be reversed proportionally to the amount being refunded (either the entire or partial amount). A transfer can be reversed only by the application that created the charge. |
config
: an optional object containing collection configuration.
Option | Description |
---|---|
enable_customer_cancellation | Optional, defaults to false. If true, Android-based smart readers show a cancel button. |
Returns a Promise
that resolves to either:
- an empty object if the payment method collection was successful, or
- an object with an error field if there was an error while collecting the refund payment method.
processRefund()
Processes an in-progress refund. This method can only be successfully called after collectRefundPaymentMethod
has returned successfully.
Returns a Promise
that resolves to either:
- a refund object if the refund was successful, or
- an object with an error field if there was an error while processing the refund.
cancelCollectRefundPaymentMethod()
Cancels an outstanding collectRefundPaymentMethod
command.
Returns a Promise
that resolves to an empty object if the cancellation was successful. If the cancellation fails, the Promise
resolves to an object with an error
field.
collectInputs(collectInputsParameters)
Note
To request access to the Collect Inputs beta, email us at stripe-terminal-betas@stripe.com.
Start displaying forms and collecting information from customers using collect inputs.
This method takes a ICollectInputsParameters
object as input.
Returns a Promise
that resolves to the collected results if the command succeeds. If the command fails, the Promise
resolves to an object with an error.
cancelCollectInputs()
Note
To request access to the Collect Inputs beta, email us at stripe-terminal-betas@stripe.com.
Cancels an outstanding collectInputs
command.
Returns a Promise
that resolves to an empty object if the cancellation 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_
object.
Error codes
Code | Description |
---|---|
no_ | The command failed because no reader is connected. |
no_ | cancelCollectPaymentMethod can only be called when collectPaymentMethod is in progress. |
no_ | cancelCollectReusableCard can only be called when readReusableCard is in progress. |
canceled | The command was canceled. |
cancelable_ | Cancellation failed because the operation has already completed. |
cancelable_ | Cancellation failed because the operation has already been canceled. |
network_ | An unknown error occurred when communicating with the server or reader over the network. Refer to the error message for more information. |
network_ | 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_ | connectReader failed because a reader is already connected. |
failed_ | Failed to fetch a connection token. Make sure your connection token handler returns a promise that resolves to the connection token. |
discovery_ | discoverReaders returned too many readers. Use Locations to filter discovered readers by location. |
invalid_ | The reader is running an unsupported software version. Please allow the reader to update and try again. |
reader_ | The reader returned an error while processing the request. Refer to the error message for more information. |
command_ | The action can’t be performed, because an in-progress action is preventing it. |
Changelog
If you’re 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
toprocessPayment
. - Renamed the values for PaymentStatus. PaymentStatus can be one of
not_
,ready ready
,waiting_
, orfor_ input processing
. - Removed card details from the response to
collectPaymentMethod
, previously available inresponse.
.paymentIntent. payment_ method. card_ payment - Receipt information is now located in the
payment_
hash.intent. charges[0]. payment_ method_ details. card_ present - Changed the API for discovering a simulated reader to
discoverReaders({ simulated: true })
. - Renamed
readSource
toreadReusableCard
. A successful call toreadReusableCard
returns a PaymentMethod instead of a Source. Payment Methods must be used with PaymentIntents. For more information, see the Payment Methods API overview. - Changed the response of
connectReader
to{ reader: Reader }
, removing the wrapperConnection
object. - Removed the
startReaderDiscovery
andstopReaderDiscovery
methods. To repeatedly discover readers, you can use the JavaScriptsetInterval
method. - Renamed
clearConnectionToken
toclearCachedCredentials
.