API

Reference for @capacitor-community/stripe-terminal v8.2.0. Platform support for connection types and Tap to Pay APIs is documented in Configuration.

Methods

method initialize(...)

initialize(options: { tokenProviderEndpoint?: string; isTest: boolean; }) => Promise<void>

method discoverReaders(...)

discoverReaders(options: DiscoverReadersOptions) => Promise<{ readers: ReaderInterface[]; }>

method setConnectionToken(...)

setConnectionToken(options: { token: string; }) => Promise<void>

method setSimulatorConfiguration(...)

Stripe docs reference
setSimulatorConfiguration(options: { update?: SimulateReaderUpdate; simulatedCard?: SimulatedCardType; simulatedTipAmount?: number; }) => Promise<void>

method connectReader(...)

connectReader(options: { reader: ReaderInterface; autoReconnectOnUnexpectedDisconnect?: boolean; merchantDisplayName?: string; onBehalfOf?: string; }) => Promise<void>

method getConnectedReader()

getConnectedReader() => Promise<{ reader: ReaderInterface | null; }>

method disconnectReader()

disconnectReader() => Promise<void>

method cancelDiscoverReaders()

cancelDiscoverReaders() => Promise<void>

method collectPaymentMethod(...)

collectPaymentMethod(options: { paymentIntent: string; }) => Promise<void>

method cancelCollectPaymentMethod()

cancelCollectPaymentMethod() => Promise<void>

method confirmPaymentIntent()

confirmPaymentIntent() => Promise<void>

method installAvailableUpdate()

installAvailableUpdate() => Promise<void>

method cancelInstallUpdate()

cancelInstallUpdate() => Promise<void>

method setReaderDisplay(...)

setReaderDisplay(options: Cart) => Promise<void>

method clearReaderDisplay()

clearReaderDisplay() => Promise<void>

method rebootReader()

rebootReader() => Promise<void>

method cancelReaderReconnection()

cancelReaderReconnection() => Promise<void>

method setTapToPayUxConfiguration(...)

Configure the Tap to Pay UX appearance (Android only).
Call this after initialize() but before connectReader().
Has no effect on iOS or web platforms.
setTapToPayUxConfiguration(options: TapToPayUxConfiguration) => Promise<void>

method isTapToPayAccountLinked(...)

Check whether the merchant has accepted Apple's Tap to Pay on iPhone
Terms and Conditions.

iOS only, and requires iOS 16.4 or later. initialize() must have been
called first because the SDK needs a connection token provider, but no
reader connection is required and the call does not activate the device.

The answer is read from Apple on every call. Apple's Tap to Pay on iPhone
requirements state that acceptance state must be retrieved from Apple
rather than from a local variable, so do not cache the result.

Stripe docs reference
isTapToPayAccountLinked(options?: IsTapToPayAccountLinkedOptions | undefined) => Promise<{ isLinked: boolean; }>

method addListener(TerminalEventsEnum.Loaded, ...)

addListener(eventName: TerminalEventsEnum.Loaded, listenerFunc: () => void) => Promise<PluginListenerHandle>

method addListener(TerminalEventsEnum.RequestedConnectionToken, ...)

addListener(eventName: TerminalEventsEnum.RequestedConnectionToken, listenerFunc: () => void) => Promise<PluginListenerHandle>

method addListener(TerminalEventsEnum.DiscoveredReaders, ...)

When searching for iOS Bluetooth, this will be executed multiple times.
https://docs.stripe.com/terminal/payments/connect-reader?terminal-sdk-platform=ios&reader-type=bluetoothhttps://docs.stripe.com/terminal/payments/connect-reader?terminal-sdk-platform=ios&reader-type=bluetooth
addListener(eventName: TerminalEventsEnum.DiscoveredReaders, listenerFunc: ({ readers }: { readers: ReaderInterface[]; }) => void) => Promise<PluginListenerHandle>

method addListener(TerminalEventsEnum.ConnectedReader, ...)

addListener(eventName: TerminalEventsEnum.ConnectedReader, listenerFunc: () => void) => Promise<PluginListenerHandle>

method addListener(TerminalEventsEnum.DisconnectedReader, ...)

Emitted when the reader is disconnected, either in response to disconnectReader()
or some connection error.

For all reader types, this is emitted in response to disconnectReader()
without a reason property.

For Bluetooth and USB readers, this is emitted with a reason property when the reader disconnects.

Note: For Bluetooth and USB readers, when you call disconnectReader(), this event
will be emitted twice: one without a reason in acknowledgement of your call, and again with a reason when the reader
finishes disconnecting.
addListener(eventName: TerminalEventsEnum.DisconnectedReader, listenerFunc: ({ reason }: { reason?: DisconnectReason | undefined; }) => void) => Promise<PluginListenerHandle>

method addListener(TerminalEventsEnum.ConnectionStatusChange, ...)

Emitted when the Terminal's connection status changed.

Note: You should not use this method to detect when a reader unexpectedly disconnects from your app,
as it cannot be used to accurately distinguish between expected and unexpected disconnect events.

To detect unexpected disconnects (e.g. to automatically notify your user), you should instead use
the UnexpectedReaderDisconnect event.

Stripe docs reference
addListener(eventName: TerminalEventsEnum.ConnectionStatusChange, listenerFunc: ({ status }: { status: ConnectionStatus; }) => void) => Promise<PluginListenerHandle>

method addListener(TerminalEventsEnum.UnexpectedReaderDisconnect, ...)

The Terminal disconnected unexpectedly from the reader.

In your implementation of this method, you may want to notify your user that the reader disconnected.
You may also call discoverReaders() to begin scanning for readers, and attempt
to automatically reconnect to the disconnected reader. Be sure to either set a timeout or make it
possible to cancel calls to discoverReaders()

When connected to a Bluetooth or USB reader, you can get more information about the disconnect by
implementing the DisconnectedReader event.

Stripe docs reference
addListener(eventName: TerminalEventsEnum.UnexpectedReaderDisconnect, listenerFunc: ({ reader }: { reader: ReaderInterface; }) => void) => Promise<PluginListenerHandle>

method addListener(TerminalEventsEnum.ConfirmedPaymentIntent, ...)

addListener(eventName: TerminalEventsEnum.ConfirmedPaymentIntent, listenerFunc: () => void) => Promise<PluginListenerHandle>

method addListener(TerminalEventsEnum.CollectedPaymentIntent, ...)

addListener(eventName: TerminalEventsEnum.CollectedPaymentIntent, listenerFunc: () => void) => Promise<PluginListenerHandle>

method addListener(TerminalEventsEnum.Canceled, ...)

Emitted when cancelCollectPaymentMethod() is called and succeeds.
The Promise returned by cancelCollectPaymentMethod() will also be resolved.
addListener(eventName: TerminalEventsEnum.Canceled, listenerFunc: () => void) => Promise<PluginListenerHandle>

method addListener(TerminalEventsEnum.Failed, ...)

Emitted when either collectPaymentMethod() or confirmPaymentIntent()
fails. The Promise returned by the relevant call will also be rejected.
addListener(eventName: TerminalEventsEnum.Failed, listenerFunc: (info: { message: string; code?: string; declineCode?: string; }) => void) => Promise<PluginListenerHandle>

method addListener(TerminalEventsEnum.ReportAvailableUpdate, ...)

Emitted when a software update is available for the connected reader.
addListener(eventName: TerminalEventsEnum.ReportAvailableUpdate, listenerFunc: ({ update }: { update: ReaderSoftwareUpdateInterface; }) => void) => Promise<PluginListenerHandle>

method addListener(TerminalEventsEnum.StartInstallingUpdate, ...)

Only applicable to Bluetooth and USB readers.

Emitted when the connected reader begins installing a software update.
If a mandatory software update is available when a reader first connects, that update is
automatically installed. The update will be installed before ConnectedReader is emitted and
before the Promise returned by connectReader() resolves.
In this case, you will receive this sequence of events:

1. StartInstallingUpdate
2. ReaderSoftwareUpdateProgress (repeatedly)
3. FinishInstallingUpdates
4. ConnectedReader
5. connectReader() Promise resolves

Your app should show UI to the user indiciating that a software update is being installed
to explain why connecting is taking longer than usual.

Stripe docs reference
addListener(eventName: TerminalEventsEnum.StartInstallingUpdate, listenerFunc: ({ update }: { update: ReaderSoftwareUpdateInterface; }) => void) => Promise<PluginListenerHandle>

method addListener(TerminalEventsEnum.ReaderSoftwareUpdateProgress, ...)

Only applicable to Bluetooth and USB readers.

Emitted periodically while reader software is updating to inform of the installation progress.
progress is a float between 0 and 1.

Stripe docs reference
addListener(eventName: TerminalEventsEnum.ReaderSoftwareUpdateProgress, listenerFunc: ({ progress }: { progress: number; }) => void) => Promise<PluginListenerHandle>

method addListener(TerminalEventsEnum.FinishInstallingUpdate, ...)

Only applicable to Bluetooth and USB readers.

Stripe docs reference
addListener(eventName: TerminalEventsEnum.FinishInstallingUpdate, listenerFunc: (args: { update: ReaderSoftwareUpdateInterface; } | { error: string; }) => void) => Promise<PluginListenerHandle>

method addListener(TerminalEventsEnum.BatteryLevel, ...)

Only applicable to Bluetooth and USB readers.

Emitted upon connection and every 10 minutes.

Stripe docs reference
addListener(eventName: TerminalEventsEnum.BatteryLevel, listenerFunc: ({ level, charging, status }: { level: number; charging: boolean; status: BatteryStatus; }) => void) => Promise<PluginListenerHandle>

method addListener(TerminalEventsEnum.ReaderEvent, ...)

Only applicable to Bluetooth and USB readers.

Stripe docs reference
addListener(eventName: TerminalEventsEnum.ReaderEvent, listenerFunc: ({ event }: { event: ReaderEvent; }) => void) => Promise<PluginListenerHandle>

method addListener(TerminalEventsEnum.RequestDisplayMessage, ...)

Only applicable to Bluetooth and USB readers.

Emitted when the Terminal requests that a message be displayed in your app.

Stripe docs reference
addListener(eventName: TerminalEventsEnum.RequestDisplayMessage, listenerFunc: ({ messageType, message }: { messageType: ReaderDisplayMessage; message: string; }) => void) => Promise<PluginListenerHandle>

method addListener(TerminalEventsEnum.RequestReaderInput, ...)

Only applicable to Bluetooth and USB readers.

Emitted when the reader begins waiting for input. Your app should prompt the customer
to present a source using one of the given input options. If the reader emits a message,
the RequestDisplayMessage event will be emitted.

Stripe docs reference
addListener(eventName: TerminalEventsEnum.RequestReaderInput, listenerFunc: ({ options, message }: { options: ReaderInputOption[]; message: string; }) => void) => Promise<PluginListenerHandle>

method addListener(TerminalEventsEnum.PaymentStatusChange, ...)

Stripe docs reference
addListener(eventName: TerminalEventsEnum.PaymentStatusChange, listenerFunc: ({ status }: { status: PaymentStatus; }) => void) => Promise<PluginListenerHandle>

method addListener(TerminalEventsEnum.ReaderReconnectStarted, ...)

addListener(eventName: TerminalEventsEnum.ReaderReconnectStarted, listenerFunc: ({ reader, reason }: { reader: ReaderInterface; reason: string; }) => void) => Promise<PluginListenerHandle>

method addListener(TerminalEventsEnum.ReaderReconnectSucceeded, ...)

addListener(eventName: TerminalEventsEnum.ReaderReconnectSucceeded, listenerFunc: ({ reader }: { reader: ReaderInterface; }) => void) => Promise<PluginListenerHandle>

method addListener(TerminalEventsEnum.ReaderReconnectFailed, ...)

addListener(eventName: TerminalEventsEnum.ReaderReconnectFailed, listenerFunc: ({ reader }: { reader: ReaderInterface; }) => void) => Promise<PluginListenerHandle>

Each addListener overload is a distinct method signature. The TerminalEventsEnum table below lists member names and string values only; it does not repeat those overloads.

DiscoveringReaders and CancelDiscoveredReaders appear on the enum and are emitted by native discovery, but they have no typed overload in this list.

Interfaces

interface DiscoverReadersOptions

Prop	Type	Description
type	TerminalConnectTypes
locationId	string
bluetoothScanWaitTime	number	Only applies to Bluetooth scan discovery (iOS only). During discovery, readers are reported via DiscoveryDelegate.didUpdateDiscoveredReaders. This timeout controls how long to wait before resolving the discoverReaders method with the current list. If this setting is not specified or is set to 0, the initial scan results will be returned.

interface TapToPayUxConfiguration

Configuration for the Tap to Pay UX (Android only).

Prop	Type	Description
colors	TapToPayColorScheme	Color scheme for the Tap to Pay screen
darkMode	TapToPayDarkMode	Dark mode setting
tapZone	TapToPayTapZone	Tap zone position configuration

interface TapToPayColorScheme

Color scheme for the Tap to Pay screen.

Prop	Type	Description
primary	TapToPayColor	Primary color (tap zone indicator). Hex string or 'default'.
success	TapToPayColor	Success state color. Hex string or 'default'.
error	TapToPayColor	Error state color. Hex string or 'default'.

interface IsTapToPayAccountLinkedOptions

Options for isTapToPayAccountLinked.

Prop	Type	Description
onBehalfOf	string	Connected account ID, for Stripe Connect platforms. Omit to check the account that owns the API key.

interface PluginListenerHandle

Prop	Type
remove	() => Promise<void>

Type aliases

type alias ReaderInterface

{ /** * The unique serial number is primary identifier inner plugin. */ serialNumber: string; label: string; batteryLevel: number; batteryStatus: BatteryStatus; simulated: boolean; id: number; availableUpdate: ReaderSoftwareUpdateInterface; locationId: string; ipAddress: string; status: NetworkStatus; location: LocationInterface; locationStatus: LocationStatus; deviceType: DeviceType; deviceSoftwareVersion: string | null; /** * iOS Only properties. These properties are not available on Android. */ isCharging: number; /** * Android Only properties. These properties are not available on iOS. */ baseUrl: string; bootloaderVersion: string; configVersion: string; emvKeyProfileId: string; firmwareVersion: string; hardwareVersion: string; macKeyProfileId: string; pinKeyProfileId: string; trackKeyProfileId: string; settingsVersion: string; pinKeysetId: string; }

type alias ReaderSoftwareUpdateInterface

{ deviceSoftwareVersion: string; estimatedUpdateTime: UpdateTimeEstimate; requiredAt: number; }

type alias LocationInterface

{ id: string; displayName: string; address: { city: string; country: string; postalCode: string; line1: string; line2: string; state: string; }; ipAddress: string; }

type alias Cart

{ currency: string; tax: number; total: number; lineItems: CartLineItem[]; }

type alias CartLineItem

{ displayName: string; quantity: number; amount: number; }

type alias TapToPayColor

'default' | string

type alias TapToPayTapZone

{ type: 'default' } | { type: 'front'; xBias: number; yBias: number } | { type: 'behind'; xBias: number; yBias: number } | { type: 'above'; bias?: number } | { type: 'below'; bias?: number } | { type: 'left'; bias?: number } | { type: 'right'; bias?: number }

TerminalResultInterface is a union of payment-result event names: TerminalEventsEnum.ConfirmedPaymentIntent, CollectedPaymentIntent, Canceled, and Failed. It is a convenience alias, not a return type of confirmPaymentIntent().

Enums

enum TerminalConnectTypes

Member	Value
Simulated	'simulated'
Internet	'internet'
Bluetooth	'bluetooth'
Usb	'usb'
TapToPay	'tap-to-pay'
HandOff	'hand-off'

enum TerminalEventsEnum

Member	Value
Loaded	'terminalLoaded'
DiscoveredReaders	'terminalDiscoveredReaders'
DiscoveringReaders	'terminalDiscoveringReaders'
CancelDiscoveredReaders	'terminalCancelDiscoveredReaders'
ConnectedReader	'terminalConnectedReader'
DisconnectedReader	'terminalDisconnectedReader'
ConnectionStatusChange	'terminalConnectionStatusChange'
UnexpectedReaderDisconnect	'terminalUnexpectedReaderDisconnect'
ConfirmedPaymentIntent	'terminalConfirmedPaymentIntent'
CollectedPaymentIntent	'terminalCollectedPaymentIntent'
Canceled	'terminalCanceled'
Failed	'terminalFailed'
RequestedConnectionToken	'terminalRequestedConnectionToken'
ReportAvailableUpdate	'terminalReportAvailableUpdate'
StartInstallingUpdate	'terminalStartInstallingUpdate'
ReaderSoftwareUpdateProgress	'terminalReaderSoftwareUpdateProgress'
FinishInstallingUpdate	'terminalFinishInstallingUpdate'
BatteryLevel	'terminalBatteryLevel'
ReaderEvent	'terminalReaderEvent'
RequestDisplayMessage	'terminalRequestDisplayMessage'
RequestReaderInput	'terminalRequestReaderInput'
PaymentStatusChange	'terminalPaymentStatusChange'
ReaderReconnectStarted	'terminalReaderReconnectStarted'
ReaderReconnectSucceeded	'terminalReaderReconnectSucceeded'
ReaderReconnectFailed	'terminalReaderReconnectFailed'

enum SimulateReaderUpdate

Member	Value
UpdateAvailable	'UPDATE_AVAILABLE'
None	'NONE'
Required	'REQUIRED'
Random	'RANDOM'
LowBattery	'LOW_BATTERY'
LowBatterySucceedConnect	'LOW_BATTERY_SUCCEED_CONNECT'

enum SimulatedCardType

Member	Value
Visa	'VISA'
VisaDebit	'VISA_DEBIT'
Mastercard	'MASTERCARD'
MastercardDebit	'MASTERCARD_DEBIT'
MastercardPrepaid	'MASTERCARD_PREPAID'
Amex	'AMEX'
Amex2	'AMEX_2'
Discover	'DISCOVER'
Discover2	'DISCOVER_2'
DinersClub	'DINERS'
DinersClulb14Digits	'DINERS_14_DIGITS'
JCB	'JCB'
UnionPay	'UNION_PAY'
Interac	'INTERAC'
EftposAustraliaDebit	'EFTPOS_AU_DEBIT'
VisaUsCommonDebit	'VISA_US_COMMON_DEBIT'
ChargeDeclined	'CHARGE_DECLINED'
ChargeDeclinedInsufficientFunds	'CHARGE_DECLINED_INSUFFICIENT_FUNDS'
ChargeDeclinedLostCard	'CHARGE_DECLINED_LOST_CARD'
ChargeDeclinedStolenCard	'CHARGE_DECLINED_STOLEN_CARD'
ChargeDeclinedExpiredCard	'CHARGE_DECLINED_EXPIRED_CARD'
ChargeDeclinedProcessingError	'CHARGE_DECLINED_PROCESSING_ERROR'
EftposAustraliaVisaDebit	'EFTPOS_AU_VISA_DEBIT'
EftposAustraliaMastercardDebit	'EFTPOS_AU_DEBIT_MASTERCARD'
OfflinePinCVM	'OFFLINE_PIN_CVM'
OfflinePinSCARetry	'OFFLINE_PIN_SCA_RETRY'
OnlinePinCVM	'ONLINE_PIN_CVM'
OnlinePinSCARetry	'ONLINE_PIN_SCA_RETRY'

enum BatteryStatus

Member	Value
Unknown	'UNKNOWN'
Critical	'CRITICAL'
Low	'LOW'
Nominal	'NOMINAL'

enum UpdateTimeEstimate

Member	Value
LessThanOneMinute	'LESS_THAN_ONE_MINUTE'
OneToTwoMinutes	'ONE_TO_TWO_MINUTES'
TwoToFiveMinutes	'TWO_TO_FIVE_MINUTES'
FiveToFifteenMinutes	'FIVE_TO_FIFTEEN_MINUTES'

enum NetworkStatus

Member	Value
Unknown	'UNKNOWN'
Online	'ONLINE'
Offline	'OFFLINE'

enum LocationStatus

Member	Value
NotSet	'NOT_SET'
Set	'SET'
Unknown	'UNKNOWN'

enum DeviceType

Member	Value
tapToPayDevice	'tapToPayDevice'
wisePad3s	'wisePad3s'
appleBuiltIn	'appleBuiltIn'
chipper1X	'chipper1X'
chipper2X	'chipper2X'
etna	'etna'
stripeM2	'stripeM2'
stripeS700	'stripeS700'
stripeS700DevKit	'stripeS700Devkit'
wiseCube	'wiseCube'
wisePad3	'wisePad3'
wisePosE	'wisePosE'
wisePosEDevKit	'wisePosEDevkit'
unknown	'unknown'

enum DisconnectReason

Member	Value
Unknown	'UNKNOWN'
DisconnectRequested	'DISCONNECT_REQUESTED'
RebootRequested	'REBOOT_REQUESTED'
SecurityReboot	'SECURITY_REBOOT'
CriticallyLowBattery	'CRITICALLY_LOW_BATTERY'
PoweredOff	'POWERED_OFF'
BluetoothDisabled	'BLUETOOTH_DISABLED'

enum ConnectionStatus

Member	Value
Unknown	'UNKNOWN'
NotConnected	'NOT_CONNECTED'
Connecting	'CONNECTING'
Connected	'CONNECTED'

enum ReaderEvent

Member	Value
Unknown	'UNKNOWN'
CardInserted	'CARD_INSERTED'
CardRemoved	'CARD_REMOVED'

enum ReaderDisplayMessage

Member	Value
CheckMobileDevice	'CHECK_MOBILE_DEVICE'
RetryCard	'RETRY_CARD'
InsertCard	'INSERT_CARD'
InsertOrSwipeCard	'INSERT_OR_SWIPE_CARD'
SwipeCard	'SWIPE_CARD'
RemoveCard	'REMOVE_CARD'
MultipleContactlessCardsDetected	'MULTIPLE_CONTACTLESS_CARDS_DETECTED'
TryAnotherReadMethod	'TRY_ANOTHER_READ_METHOD'
TryAnotherCard	'TRY_ANOTHER_CARD'
CardRemovedTooEarly	'CARD_REMOVED_TOO_EARLY'

enum ReaderInputOption

Member	Value
None	'NONE'
Insert	'INSERT'
Swipe	'SWIPE'
Tap	'TAP'
ManualEntry	'MANUAL_ENTRY'

enum PaymentStatus

Member	Value
Unknown	'UNKNOWN'
NotReady	'NOT_READY'
Ready	'READY'
WaitingForInput	'WAITING_FOR_INPUT'
Processing	'PROCESSING'

enum TapToPayDarkMode

Member	Value
System	'SYSTEM'
Dark	'DARK'
Light	'LIGHT'

DeviceGroup maps a DeviceType to a reader-image group (stripe_m2, chipper, wisepad, wisepose, s700, apple, tapToPayDevice, unknown). The enum is documented as reference-only for picking images; you do not pass it to discoverReaders or connectReader.