@capgo/capacitor-stripe-terminal

中文文档
8.0.9发布于 2026/10/15MPL-2.0TypeScriptESM + CJS构建来源已验证近 30 天下载 2.1万

Capacitor plugin for Stripe Terminal in-person payments.

原始使用文档
文档目录61 节
  1. ➡️ Get started for free
  2. Key features
  3. Why this plugin
  4. Documentation
  5. Compatibility
  6. Install
  7. Platform setup
  8. Web
  9. iOS
  10. Android
  11. Usage
  12. Simple collect payment
  13. Listen device update
  14. Get terminal processing information
  15. More details on the leader screen
  16. Simulate reader status changes for testing
  17. API
  18. initialize(...)
  19. discoverReaders(...)
  20. setConnectionToken(...)
  21. setSimulatorConfiguration(...)
  22. connectReader(...)
  23. getConnectedReader()
  24. disconnectReader()
  25. cancelDiscoverReaders()
  26. collectPaymentMethod(...)
  27. cancelCollectPaymentMethod()
  28. confirmPaymentIntent()
  29. installAvailableUpdate()
  30. cancelInstallUpdate()
  31. setReaderDisplay(...)
  32. clearReaderDisplay()
  33. rebootReader()
  34. cancelReaderReconnection()
  35. setTapToPayUxConfiguration(...)
  36. addListener(TerminalEventsEnum.Loaded, ...)
  37. addListener(TerminalEventsEnum.RequestedConnectionToken, ..…
  38. addListener(TerminalEventsEnum.DiscoveredReaders, ...)
  39. addListener(TerminalEventsEnum.ConnectedReader, ...)
  40. addListener(TerminalEventsEnum.DisconnectedReader, ...)
  41. addListener(TerminalEventsEnum.ConnectionStatusChange, ...)
  42. addListener(TerminalEventsEnum.UnexpectedReaderDisconnect, …
  43. addListener(TerminalEventsEnum.ConfirmedPaymentIntent, ...)
  44. addListener(TerminalEventsEnum.CollectedPaymentIntent, ...)
  45. addListener(TerminalEventsEnum.Canceled, ...)
  46. addListener(TerminalEventsEnum.Failed, ...)
  47. addListener(TerminalEventsEnum.ReportAvailableUpdate, ...)
  48. addListener(TerminalEventsEnum.StartInstallingUpdate, ...)
  49. addListener(TerminalEventsEnum.ReaderSoftwareUpdateProgress…
  50. addListener(TerminalEventsEnum.FinishInstallingUpdate, ...)
  51. addListener(TerminalEventsEnum.BatteryLevel, ...)
  52. addListener(TerminalEventsEnum.ReaderEvent, ...)
  53. addListener(TerminalEventsEnum.RequestDisplayMessage, ...)
  54. addListener(TerminalEventsEnum.RequestReaderInput, ...)
  55. addListener(TerminalEventsEnum.PaymentStatusChange, ...)
  56. addListener(TerminalEventsEnum.ReaderReconnectStarted, ...)
  57. addListener(TerminalEventsEnum.ReaderReconnectSucceeded, ..…
  58. addListener(TerminalEventsEnum.ReaderReconnectFailed, ...)
  59. Interfaces
  60. Type Aliases
  61. Enums

@capgo/capacitor-stripe-terminal

Accept in-person payments in your Capacitor app with Stripe Terminal: Tap to Pay on the phone, plus Bluetooth, USB and internet card readers on iOS and Android.

Capgo - Build Capacitor apps with AI, ship updates instantly

Capgo: push fixes to your Capacitor users in minutes, build signed iOS and Android apps without a Mac, and roll back in one click.

➡️ Get started for free

14-day unlimited free trial. No credit card required

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-stripe-terminal in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-stripe-terminal to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

@capgo/capacitor-stripe-terminal for Capacitor apps

Key features

  • Setup: initialize() with a connection token endpoint or setConnectionToken().
  • Readers: discoverReaders(), connectReader(), getConnectedReader() and disconnectReader().
  • Payments: collectPaymentMethod(), confirmPaymentIntent() and cancelCollectPaymentMethod().
  • Reader display and updates: setReaderDisplay() shows a cart, plus installAvailableUpdate() for reader software.
  • Testing: setSimulatorConfiguration() for simulated readers and cards.
  • Tap to Pay UX on Android: setTapToPayUxConfiguration() customizes the Tap to Pay screen.
  • Platforms: iOS, Android and Web. Web uses Stripe Terminal JS and supports internet readers only.

Why this plugin

This plugin is a maintained fork of @capacitor-community/stripe. Capgo split the community project into focused packages, each with its own docs, example app, and CI.

We track open issues and pull requests in the community repository, merge relevant fixes into our repos, and ship them on current Stripe SDKs. Our goal is to be more reactive than the community maintainers when bugs land or platforms change.

This package covers Stripe Terminal, Tap to Pay, Bluetooth, USB, and internet readers.

If you use the community package today, this is the maintained upgrade path from the community package.

Documentation

The most complete documentation is available here: https://capgo.app/docs/plugins/stripe-terminal/

Compatibility

Plugin versionCapacitor compatibilityMaintained
v8..v8..✅
v7..v7..On demand

Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.

Install

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-stripe-terminal` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

# Install (choose one)
npm install @capgo/capacitor-stripe-terminal
pnpm add @capgo/capacitor-stripe-terminal
yarn add @capgo/capacitor-stripe-terminal
bun add @capgo/capacitor-stripe-terminal

# Then sync Capacitor (choose one)
npx cap sync
pnpm exec cap sync
yarn cap sync
bunx cap sync

Platform setup

We have confirmed that it works well in the demo project. Refer to:

Web

No additional steps are necessary.

iOS

No additional steps are necessary.

Android

Add permissions to your android/app/src/main/AndroidManifest.xml file:

+ <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+ <uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
+ <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />
+ <uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
+ <uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />
+ <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

And update minSdkVersion to 26 in your android/app/build.gradle file:

  ext {
-    minSdkVersion = 23
+    minSdkVersion = 26

If you are developing apps for Stripe Android devices (e.g. Stripe Reader S700), follow the Stripe's documentation for the client-side setup.

Usage

Simple collect payment

Use plugin client

(async ()=> {
  /**
   * tokenProviderEndpoint: The URL of your backend to provide a token. Use Post request to get a token.
   */
  await StripeTerminal.initialize({ tokenProviderEndpoint: 'https://example.com/token', isTest: true })
  const { readers } = await StripeTerminal.discoverReaders({
    type: TerminalConnectTypes.TapToPay,
    locationId: "**************",
  });
  await StripeTerminal.connectReader({
    reader: readers[0],
  });
  // Collect payment intent
  await StripeTerminal.collectPaymentMethod({ paymentIntent: "**************" });
  // Process and confirm payment intent
  await StripeTerminal.confirmPaymentIntent();
  // disconnect reader
  await StripeTerminal.disconnectReader();
});

set string token

(async ()=> {
  // run before StripeTerminal.initialize
  StripeTerminal.addListener(TerminalEventsEnum.RequestedConnectionToken, async () => {
    const { token } = (await fetch("https://example.com/token")).json();
    StripeTerminal.setConnectionToken({ token });
  });
});
(async ()=> {
  await StripeTerminal.initialize({ isTest: true })
  const { readers } = await StripeTerminal.discoverReaders({
    type: TerminalConnectTypes.TapToPay,
    locationId: "**************",
  });
  await StripeTerminal.connectReader({
    reader: readers[0],
  });
  // Collect payment intent
  await StripeTerminal.collectPaymentMethod({ paymentIntent: "**************" });
  // Process and confirm payment intent
  await StripeTerminal.confirmPaymentIntent();
  // disconnect reader
  await StripeTerminal.disconnectReader();
});

Listen device update

The device will if necessary automatically start updating itself. It is important to handle them as needed so as not to disrupt business operations.

(async ()=> {
  StripeTerminal.addListener(TerminalEventsEnum.ReportAvailableUpdate, async ({ update }) => {
    if (window.confirm("Will you update the device?")) {
      await StripeTerminal.installAvailableUpdate();
    }
  });
  StripeTerminal.addListener(TerminalEventsEnum.StartInstallingUpdate, async ({ update }) => {
    console.log(update);
    if (window.confirm("Will you interrupt the update?")) {
      StripeTerminal.cancelInstallUpdate();
    }
  });
  StripeTerminal.addListener(TerminalEventsEnum.ReaderSoftwareUpdateProgress, async ({ progress }) => {
    // be able to use this value to create a progress bar.
  });
  StripeTerminal.addListener(TerminalEventsEnum.FinishInstallingUpdate, async ({ update }) => {
    console.log(update);
  });
});

Get terminal processing information

For devices without leader screen, processing information must be retrieved and displayed on the mobile device. Get it with a listener.

/**
 * Listen battery level. If the battery level is low, you can notify the user to charge the device.
 */
StripeTerminal.addListener(TerminalEventsEnum.BatteryLevel, async ({ level, charging, status }) => {
  console.log(level, charging, status);
});

/**
 * Listen reader event. You can get the reader's status and display it on the mobile device.
 */
StripeTerminal.addListener(TerminalEventsEnum.ReaderEvent, async ({ event }) => {
  console.log(event);
});

/**
 * Listen display message. You can get the message to be displayed on the mobile device.
 */
StripeTerminal.addListener(TerminalEventsEnum.RequestDisplayMessage, async ({ messageType, message }) => {
  console.log(messageType, message);
});

/**
 * Listen reader input. You can get the message what can be used for payment.
 */
StripeTerminal.addListener(TerminalEventsEnum.RequestReaderInput, async ({ options, message }) => {
  console.log(options, message);
});

More details on the leader screen

The contents of the payment can be shown on the display. This requires a leader screen on the device. This should be run before collectPaymentMethod.

await StripeTerminal.setReaderDisplay({
  currency: 'usd',
  tax: 0,
  total: 1000,
  lineItems: [{
    displayName: 'winecode',
    quantity: 2,
    amount: 500
  }] as CartLineItem[],
})

// Of course, erasure is also possible.
await StripeTerminal.clearReaderDisplay();

Simulate reader status changes for testing

To implement updates, etc., we are facilitating an API to change the state of the simulator. This should be done before discoverReaders.

await StripeTerminal.setSimulatorConfiguration({ update: SimulateReaderUpdate.UpdateAvailable })

API

initialize(...)

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

discoverReaders(...)

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

Returns: Promise<{ readers: ReaderInterface[]; }>


setConnectionToken(...)

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

setSimulatorConfiguration(...)

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

Stripe docs reference

ParamType
options{ update?: SimulateReaderUpdate; simulatedCard?: SimulatedCardType; simulatedTipAmount?: number; }

connectReader(...)

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

getConnectedReader()

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

Returns: Promise<{ reader: ReaderInterface | null; }>


disconnectReader()

disconnectReader() => Promise<void>

cancelDiscoverReaders()

cancelDiscoverReaders() => Promise<void>

collectPaymentMethod(...)

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

cancelCollectPaymentMethod()

cancelCollectPaymentMethod() => Promise<void>

confirmPaymentIntent()

confirmPaymentIntent() => Promise<void>

installAvailableUpdate()

installAvailableUpdate() => Promise<void>

cancelInstallUpdate()

cancelInstallUpdate() => Promise<void>

setReaderDisplay(...)

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

clearReaderDisplay()

clearReaderDisplay() => Promise<void>

rebootReader()

rebootReader() => Promise<void>

cancelReaderReconnection()

cancelReaderReconnection() => Promise<void>

setTapToPayUxConfiguration(...)

setTapToPayUxConfiguration(options: TapToPayUxConfiguration) => Promise<void>

Configure the Tap to Pay UX appearance (Android only). Call this after initialize() but before connectReader(). Has no effect on iOS or web platforms.

ParamType
optionsTapToPayUxConfiguration

addListener(TerminalEventsEnum.Loaded, ...)

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

Returns: Promise<PluginListenerHandle>


addListener(TerminalEventsEnum.RequestedConnectionToken, ...)

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

Returns: Promise<PluginListenerHandle>


addListener(TerminalEventsEnum.DiscoveredReaders, ...)

addListener(eventName: TerminalEventsEnum.DiscoveredReaders, listenerFunc: ({ readers }: { readers: ReaderInterface[]; }) => void) => Promise<PluginListenerHandle>

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=bluetooth

ParamType
eventNameTerminalEventsEnum.DiscoveredReaders
listenerFunc({ readers }: { readers: ReaderInterface[]; }) => void

Returns: Promise<PluginListenerHandle>


addListener(TerminalEventsEnum.ConnectedReader, ...)

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

Returns: Promise<PluginListenerHandle>


addListener(TerminalEventsEnum.DisconnectedReader, ...)

addListener(eventName: TerminalEventsEnum.DisconnectedReader, listenerFunc: ({ reason }: { reason?: DisconnectReason | undefined; }) => void) => Promise<PluginListenerHandle>

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.

ParamType
eventNameTerminalEventsEnum.DisconnectedReader
listenerFunc({ reason }: { reason?: DisconnectReason; }) => void

Returns: Promise<PluginListenerHandle>


addListener(TerminalEventsEnum.ConnectionStatusChange, ...)

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

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

ParamType
eventNameTerminalEventsEnum.ConnectionStatusChange
listenerFunc({ status }: { status: ConnectionStatus; }) => void

Returns: Promise<PluginListenerHandle>


addListener(TerminalEventsEnum.UnexpectedReaderDisconnect, ...)

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

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

ParamType
eventNameTerminalEventsEnum.UnexpectedReaderDisconnect
listenerFunc({ reader }: { reader: ReaderInterface; }) => void

Returns: Promise<PluginListenerHandle>


addListener(TerminalEventsEnum.ConfirmedPaymentIntent, ...)

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

Returns: Promise<PluginListenerHandle>


addListener(TerminalEventsEnum.CollectedPaymentIntent, ...)

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

Returns: Promise<PluginListenerHandle>


addListener(TerminalEventsEnum.Canceled, ...)

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

Emitted when cancelCollectPaymentMethod() is called and succeeds. The Promise returned by cancelCollectPaymentMethod() will also be resolved.

ParamType
eventNameTerminalEventsEnum.Canceled
listenerFunc() => void

Returns: Promise<PluginListenerHandle>


addListener(TerminalEventsEnum.Failed, ...)

addListener(eventName: TerminalEventsEnum.Failed, listenerFunc: (info: { message: string; code?: string; declineCode?: string; }) => void) => Promise<PluginListenerHandle>

Emitted when either collectPaymentMethod() or confirmPaymentIntent() fails. The Promise returned by the relevant call will also be rejected.

ParamType
eventNameTerminalEventsEnum.Failed
listenerFunc(info: { message: string; code?: string; declineCode?: string; }) => void

Returns: Promise<PluginListenerHandle>


addListener(TerminalEventsEnum.ReportAvailableUpdate, ...)

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

Emitted when a software update is available for the connected reader.

ParamType
eventNameTerminalEventsEnum.ReportAvailableUpdate
listenerFunc({ update }: { update: ReaderSoftwareUpdateInterface; }) => void

Returns: Promise<PluginListenerHandle>


addListener(TerminalEventsEnum.StartInstallingUpdate, ...)

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

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

ParamType
eventNameTerminalEventsEnum.StartInstallingUpdate
listenerFunc({ update }: { update: ReaderSoftwareUpdateInterface; }) => void

Returns: Promise<PluginListenerHandle>


addListener(TerminalEventsEnum.ReaderSoftwareUpdateProgress, ...)

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

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

ParamType
eventNameTerminalEventsEnum.ReaderSoftwareUpdateProgress
listenerFunc({ progress }: { progress: number; }) => void

Returns: Promise<PluginListenerHandle>


addListener(TerminalEventsEnum.FinishInstallingUpdate, ...)

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

Only applicable to Bluetooth and USB readers.

Stripe docs reference

ParamType
eventNameTerminalEventsEnum.FinishInstallingUpdate
listenerFunc(args: { update: ReaderSoftwareUpdateInterface; } | { error: string; }) => void

Returns: Promise<PluginListenerHandle>


addListener(TerminalEventsEnum.BatteryLevel, ...)

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

Only applicable to Bluetooth and USB readers.

Emitted upon connection and every 10 minutes.

Stripe docs reference

ParamType
eventNameTerminalEventsEnum.BatteryLevel
listenerFunc({ level, charging, status }: { level: number; charging: boolean; status: BatteryStatus; }) => void

Returns: Promise<PluginListenerHandle>


addListener(TerminalEventsEnum.ReaderEvent, ...)

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

Only applicable to Bluetooth and USB readers.

Stripe docs reference

ParamType
eventNameTerminalEventsEnum.ReaderEvent
listenerFunc({ event }: { event: ReaderEvent; }) => void

Returns: Promise<PluginListenerHandle>


addListener(TerminalEventsEnum.RequestDisplayMessage, ...)

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

Only applicable to Bluetooth and USB readers.

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

Stripe docs reference

ParamType
eventNameTerminalEventsEnum.RequestDisplayMessage
listenerFunc({ messageType, message }: { messageType: ReaderDisplayMessage; message: string; }) => void

Returns: Promise<PluginListenerHandle>


addListener(TerminalEventsEnum.RequestReaderInput, ...)

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

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

ParamType
eventNameTerminalEventsEnum.RequestReaderInput
listenerFunc({ options, message }: { options: ReaderInputOption[]; message: string; }) => void

Returns: Promise<PluginListenerHandle>


addListener(TerminalEventsEnum.PaymentStatusChange, ...)

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

Stripe docs reference

ParamType
eventNameTerminalEventsEnum.PaymentStatusChange
listenerFunc({ status }: { status: PaymentStatus; }) => void

Returns: Promise<PluginListenerHandle>


addListener(TerminalEventsEnum.ReaderReconnectStarted, ...)

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

Returns: Promise<PluginListenerHandle>


addListener(TerminalEventsEnum.ReaderReconnectSucceeded, ...)

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

Returns: Promise<PluginListenerHandle>


addListener(TerminalEventsEnum.ReaderReconnectFailed, ...)

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

Returns: Promise<PluginListenerHandle>


Interfaces

DiscoverReadersOptions

PropTypeDescription
typeTerminalConnectTypes
locationIdstring
bluetoothScanWaitTimenumberOnly 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.

TapToPayUxConfiguration

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

PropTypeDescription
colorsTapToPayColorSchemeColor scheme for the Tap to Pay screen
darkModeTapToPayDarkModeDark mode setting
tapZoneTapToPayTapZoneTap zone position configuration

TapToPayColorScheme

Color scheme for the Tap to Pay screen.

PropTypeDescription
primaryTapToPayColorPrimary color (tap zone indicator). Hex string or 'default'.
successTapToPayColorSuccess state color. Hex string or 'default'.
errorTapToPayColorError state color. Hex string or 'default'.

PluginListenerHandle

PropType
remove() => Promise<void>

Type Aliases

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; }

ReaderSoftwareUpdateInterface

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

LocationInterface

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

DeviceType

Stripe.Terminal.Reader.DeviceType

Cart

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

CartLineItem

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

TapToPayColor

Color value for TapToPayUxConfiguration. Use 'default' to use Stripe's default color, or a hex string like '#965D35'.

'default' | string

TapToPayTapZone

Tap zone position configuration. Controls where the tap indicator appears on screen.

{ 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 }

Enums

BatteryStatus

MembersValue
Unknown'UNKNOWN'
Critical'CRITICAL'
Low'LOW'
Nominal'NOMINAL'

UpdateTimeEstimate

MembersValue
LessThanOneMinute'LESS_THAN_ONE_MINUTE'
OneToTwoMinutes'ONE_TO_TWO_MINUTES'
TwoToFiveMinutes'TWO_TO_FIVE_MINUTES'
FiveToFifteenMinutes'FIVE_TO_FIFTEEN_MINUTES'

NetworkStatus

MembersValue
Unknown'UNKNOWN'
Online'ONLINE'
Offline'OFFLINE'

LocationStatus

MembersValue
NotSet'NOT_SET'
Set'SET'
Unknown'UNKNOWN'

DeviceType

MembersValue
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'

TerminalConnectTypes

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

SimulateReaderUpdate

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

SimulatedCardType

MembersValue
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'

TapToPayDarkMode

MembersValue
System'SYSTEM'
Dark'DARK'
Light'LIGHT'

TerminalEventsEnum

MembersValue
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'

DisconnectReason

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

ConnectionStatus

MembersValue
Unknown'UNKNOWN'
NotConnected'NOT_CONNECTED'
Connecting'CONNECTING'
Connected'CONNECTED'

ReaderEvent

MembersValue
Unknown'UNKNOWN'
CardInserted'CARD_INSERTED'
CardRemoved'CARD_REMOVED'

ReaderDisplayMessage

MembersValue
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'

ReaderInputOption

MembersValue
None'NONE'
Insert'INSERT'
Swipe'SWIPE'
Tap'TAP'
ManualEntry'MANUAL_ENTRY'

PaymentStatus

MembersValue
Unknown'UNKNOWN'
NotReady'NOT_READY'
Ready'READY'
WaitingForInput'WAITING_FOR_INPUT'
Processing'PROCESSING'

版本与发布记录

@capgo/capacitor-stripe-terminal 共发布 9 个版本,首次发布于 2026/06/24;过去 12 个月发布了 9 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
8.0.9latest2026/10/1525 天前
8.0.82026/10/1327 天前
8.0.72026/10/091 个月前
8.0.52026/10/081 个月前
8.0.62026/10/081 个月前
8.0.42026/09/161 个月前

关于 @capgo/capacitor-stripe-terminal 的常见问题

@capgo/capacitor-stripe-terminal 是什么?

Capacitor plugin for Stripe Terminal in-person payments.

如何安装 @capgo/capacitor-stripe-terminal?

在项目目录运行 npm install @capgo/capacitor-stripe-terminal,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:@capacitor/core(>=8.0.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@capgo/capacitor-stripe-terminal 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@capgo/capacitor-stripe-terminal 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@capgo/capacitor-stripe-terminal 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=22.0.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@capgo/capacitor-stripe-terminal 可以商用吗?

@capgo/capacitor-stripe-terminal 使用 MPL-2.0 许可。弱 Copyleft:可以商用,也可以和闭源代码一起使用;但如果分发时修改了 MPL 授权的文件,这些文件的修改需以 MPL 开源。以上为概括,不构成法律意见,请以许可原文为准。

@capgo/capacitor-stripe-terminal 的下载量有多少?

根据 npm 官方下载统计,@capgo/capacitor-stripe-terminal 在 2026/10/09 – 2026/11/07 这 30 天内被下载 20,713 次,日均约 690 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@capgo/capacitor-stripe-terminal 还在维护吗?

最新版本 8.0.9 发布于 2026/10/15(25 天前);至今共发布 9 个版本,其中过去 12 个月发布了 9 个;首次发布于 2026/06/24。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。