リーダーのライフサイクル

Terminal の操作が会計を妨げないよう、リーダーのソフトウェア更新、状態、画面表示を管理します。

ソフトウェア更新を監視する

必要に応じてリーダーが更新を開始します。利用可能な更新、インストール、キャンセル、進捗をイベントで監視してください。

更新をシミュレーションする場合、discoverReaders より前に setSimulatorConfiguration を呼びます。Web では no-op です。
初回接続時の必須更新は ConnectedReader より前に自動インストールされます。順序は開始 → 進捗（複数回）→ 完了 → 接続 → connectReader() 解決です。長い接続を停止と誤認しないUIを表示してください。
ReportAvailableUpdate は任意更新です。会計中に開始せず、加盟店が待てるときに installAvailableUpdate を呼びます。
progress は 0 から 1 の値です。
cancelInstallUpdate はSDKが許可する場合に進行中の更新を止めます。Web の更新メソッドは no-op です。
iOS Tap to Pay も開始・進捗・完了を通知します。

 method installAvailableUpdate()Installs the software update reported by ReportAvailableUpdate.
installAvailableUpdate() => Promise<void>

 method cancelInstallUpdate()Cancels an in-progress optional reader software update.
cancelInstallUpdate() => Promise<void>

 method setSimulatorConfiguration(...)Configures the simulated reader used in test mode. Call before the

operation whose behavior you want to simulate.
Stripe docs reference
setSimulatorConfiguration(options: SimulatorConfigurationOptions) => Promise<void>

状態と入力を監視する

画面を持たないリーダーでは、バッテリー残量、リーダーイベント、表示メッセージ、入力要求をリスナーで取得し、モバイル端末に表示します。Bluetooth と USB で利用でき、バッテリーは接続時と約10分ごとに通知されます。

リーダーの画面を設定する

画面を持つ端末では collectPaymentMethod より前にカート内容を表示し、完了後に消去します。Web の Internet リーダーも対応します。

 method setReaderDisplay(...)Displays cart details on a reader with a customer-facing display.
setReaderDisplay(options: Cart) => Promise<void>

 method clearReaderDisplay()Clears cart details from the reader's customer-facing display.
clearReaderDisplay() => Promise<void>

 interface Cart<a href="#cart">Cart</a> totals displayed on a reader's customer-facing screen.


Prop
Type
Description
Since


currency
string
Three-letter ISO 4217 currency code.
6.2.0

tax
number
Tax amount in the currency's smallest unit.
6.2.0

total
number
Cart total in the currency's smallest unit.
6.2.0

lineItems
CartLineItem[]
Items displayed in the cart.
6.2.0

Prop	Type	Description	Since
`currency`	`string`	Three-letter ISO 4217 currency code.	6.2.0
`tax`	`number`	Tax amount in the currency's smallest unit.	6.2.0
`total`	`number`	Cart total in the currency's smallest unit.	6.2.0
`lineItems`	`CartLineItem[]`	Items displayed in the cart.	6.2.0

 interface CartLineItemLine item displayed on a reader's customer-facing screen.


Prop
Type
Description
Since


displayName
string
Item name shown on the reader.
6.2.0

quantity
number
Number of units in the cart.
6.2.0

amount
number
Line-item amount in the currency's smallest unit.
6.2.0

Prop	Type	Description	Since
`displayName`	`string`	Item name shown on the reader.	6.2.0
`quantity`	`number`	Number of units in the cart.	6.2.0
`amount`	`number`	Line-item amount in the currency's smallest unit.	6.2.0

探索をキャンセルする

利用者がスキャン画面を離れたとき、またはタイムアウト時に cancelDiscoverReaders を呼びます。ネイティブは成功時に CancelDiscoveredReaders を通知し、処理中でなくても Promise は解決します。Web では no-op です。

 method cancelDiscoverReaders()Cancels the active reader-discovery operation.
cancelDiscoverReaders() => Promise<void>

切断と再接続

disconnectReader は現在のリーダーを切断し、未接続ならそのまま解決します。手動切断時の DisconnectedReader は、理由なしの受付通知と、Bluetooth／USB の理由付き切断通知の2回届く場合があります。

予期しない切断の検出に ConnectionStatusChange を使わず、UnexpectedReaderDisconnect を使用します。再探索には必ずタイムアウトまたはキャンセル手段を用意してください。

Tap to Pay と Bluetooth で自動再接続するには、connectReader に autoReconnectOnUnexpectedDisconnect: true を設定し、ReaderReconnectStarted、ReaderReconnectSucceeded、ReaderReconnectFailed を監視します。cancelReaderReconnection で進行中の再接続を止められます。

 method getConnectedReader()Returns the currently connected reader, or null when disconnected.
getConnectedReader() => Promise<{ reader: ReaderInterface | null; }>

 method rebootReader()Reboots the connected reader. Supported reader types are platform dependent.
rebootReader() => Promise<void>

 method cancelReaderReconnection()Cancels an automatic reader reconnection attempt.
cancelReaderReconnection() => Promise<void>

エラー処理

収集または確定が失敗すると Failed が発生し、Promise も同じ message、code、declineCode で拒否されます。UnexpectedReaderDisconnect は明示的な切断以外でリーダーを失ったことを示します。Bluetooth と USB では DisconnectedReader の DisconnectReason も確認してください。

reader-lifecycle.ts

import { StripeTerminal, TerminalEventsEnum } from '@capacitor-community/stripe-terminal';

await StripeTerminal.addListener(
  TerminalEventsEnum.ReportAvailableUpdate,
  async ({ update }) => {
    if (window.confirm('Will you update the device?')) {
      await StripeTerminal.installAvailableUpdate();
    }
  },
);

await StripeTerminal.addListener(
  TerminalEventsEnum.StartInstallingUpdate,
  async ({ update }) => {
    console.log(update);
    if (window.confirm('Will you interrupt the update?')) {
      await StripeTerminal.cancelInstallUpdate();
    }
  },
);

await StripeTerminal.addListener(
  TerminalEventsEnum.ReaderSoftwareUpdateProgress,
  async ({ progress }) => {
    console.log(progress);
  },
);

await StripeTerminal.addListener(
  TerminalEventsEnum.FinishInstallingUpdate,
  async (args) => {
    console.log(args);
  },
);

await StripeTerminal.addListener(
  TerminalEventsEnum.BatteryLevel,
  async ({ level, charging, status }) => {
    console.log(level, charging, status);
  },
);

await StripeTerminal.addListener(
  TerminalEventsEnum.ReaderEvent,
  async ({ event }) => {
    console.log(event);
  },
);

await StripeTerminal.addListener(
  TerminalEventsEnum.RequestDisplayMessage,
  async ({ messageType, message }) => {
    console.log(messageType, message);
  },
);

await StripeTerminal.addListener(
  TerminalEventsEnum.RequestReaderInput,
  async ({ options, message }) => {
    console.log(options, message);
  },
);

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

await StripeTerminal.clearReaderDisplay();

await StripeTerminal.cancelDiscoverReaders();

await StripeTerminal.addListener(
  TerminalEventsEnum.UnexpectedReaderDisconnect,
  async ({ reader }) => {
    console.log(reader);
  },
);

await StripeTerminal.addListener(
  TerminalEventsEnum.ReaderReconnectStarted,
  async ({ reader, reason }) => {
    console.log(reader, reason);
  },
);

await StripeTerminal.addListener(
  TerminalEventsEnum.ReaderReconnectSucceeded,
  async ({ reader }) => {
    console.log(reader);
  },
);

await StripeTerminal.addListener(
  TerminalEventsEnum.ReaderReconnectFailed,
  async ({ reader }) => {
    console.log(reader);
  },
);

await StripeTerminal.cancelReaderReconnection();

await StripeTerminal.rebootReader();

await StripeTerminal.addListener(
  TerminalEventsEnum.Failed,
  (info) => {
    console.log(info.message, info.code, info.declineCode);
  },
);

import { StripeTerminal, TerminalEventsEnum } from '@capacitor-community/stripe-terminal';

await StripeTerminal.addListener(
  TerminalEventsEnum.ReportAvailableUpdate,
  async ({ update }) => {
    if (window.confirm('Will you update the device?')) {
      await StripeTerminal.installAvailableUpdate();
    }
  },
);

await StripeTerminal.addListener(
  TerminalEventsEnum.StartInstallingUpdate,
  async ({ update }) => {
    console.log(update);
    if (window.confirm('Will you interrupt the update?')) {
      await StripeTerminal.cancelInstallUpdate();
    }
  },
);

await StripeTerminal.addListener(
  TerminalEventsEnum.ReaderSoftwareUpdateProgress,
  async ({ progress }) => {
    console.log(progress);
  },
);

await StripeTerminal.addListener(
  TerminalEventsEnum.FinishInstallingUpdate,
  async (args) => {
    console.log(args);
  },
);

await StripeTerminal.addListener(
  TerminalEventsEnum.BatteryLevel,
  async ({ level, charging, status }) => {
    console.log(level, charging, status);
  },
);

await StripeTerminal.addListener(
  TerminalEventsEnum.ReaderEvent,
  async ({ event }) => {
    console.log(event);
  },
);

await StripeTerminal.addListener(
  TerminalEventsEnum.RequestDisplayMessage,
  async ({ messageType, message }) => {
    console.log(messageType, message);
  },
);

await StripeTerminal.addListener(
  TerminalEventsEnum.RequestReaderInput,
  async ({ options, message }) => {
    console.log(options, message);
  },
);

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

await StripeTerminal.clearReaderDisplay();

await StripeTerminal.cancelDiscoverReaders();

await StripeTerminal.addListener(
  TerminalEventsEnum.UnexpectedReaderDisconnect,
  async ({ reader }) => {
    console.log(reader);
  },
);

await StripeTerminal.addListener(
  TerminalEventsEnum.ReaderReconnectStarted,
  async ({ reader, reason }) => {
    console.log(reader, reason);
  },
);

await StripeTerminal.addListener(
  TerminalEventsEnum.ReaderReconnectSucceeded,
  async ({ reader }) => {
    console.log(reader);
  },
);

await StripeTerminal.addListener(
  TerminalEventsEnum.ReaderReconnectFailed,
  async ({ reader }) => {
    console.log(reader);
  },
);

await StripeTerminal.cancelReaderReconnection();

await StripeTerminal.rebootReader();

await StripeTerminal.addListener(
  TerminalEventsEnum.Failed,
  (info) => {
    console.log(info.message, info.code, info.declineCode);
  },
);

リーダーのライフサイクル

ソフトウェア更新を監視する

`method` installAvailableUpdate()

`method` cancelInstallUpdate()

`method` setSimulatorConfiguration(...)

状態と入力を監視する

リーダーの画面を設定する

`method` setReaderDisplay(...)

`method` clearReaderDisplay()

`interface` Cart

`interface` CartLineItem

探索をキャンセルする

`method` cancelDiscoverReaders()

切断と再接続

`method` getConnectedReader()

`method` rebootReader()

`method` cancelReaderReconnection()

エラー処理