リーダーに接続する

アプリケーションをスマートリーダーに接続するには、事前にリーダーをアカウントに登録しておく必要があります。

ダッシュボードで登録する

You can add your reader directly in the Dashboard.

登録コードで登録する

1. リーダーページで、リーダーを登録するをクリックします。
2. Verifone P400 をお持ちの場合は、0-7-1-3-9 の順にキーを入力すると、固有の登録コードが表示されます。BBPOS WisePOS E または Stripe リーダー S700 をお持ちの場合は、リーダー設定に移動し、ペアリングコードを生成をタップします。
3. 登録コードを入力して、次へをクリックします。
4. 任意でリーダーの名前を選択します。
5. すでに場所を作成している場合は、リーダーの新しい場所を選択します。まだ作成していない場合は、+ 新規追加をクリックして場所を作成します。
6. 登録するをクリックしてリーダーの登録を完了します。

シリアル番号で登録する

1. リーダーページで、リーダーを登録するをクリックします。
2. デバイスに記載されているシリアル番号を探し、そのシリアル番号を入力します。複数のデバイスを一度に登録するには、複数のシリアル番号をカンマで区切って入力します。
3. 任意でリーダーの名前を選択します。
4. すでに場所を作成している場合は、リーダーの新しい場所を選択します。まだ作成していない場合は、+ 新規追加をクリックして場所を作成します。
5. 登録するをクリックしてリーダーの登録を完了します。

ハードウェアの注文で登録する

1. ハードウェアの注文ページで、ステータスが「配送済み」または「配達済み」の注文を見つけます。行の最後にあるオーバーフローメニュー () をクリックし、次に登録するをクリックします。
2. リーダーを登録するページで、ハードウェアの注文から登録するリーダーを 1 つ以上選択して、登録するをクリックします。
3. 任意でリーダーの名前を選択します。複数のリーダーを選択した場合、名前はプレフィックスとして機能し、Stripe はリーダーに順番に名前を付けます (たとえば、「テストリーダー」と入力した場合、リーダーには「テストリーダー 1」、「テストリーダー 2」のように名前が付けられます)。
4. すでに場所を作成している場合は、リーダーの新しい場所を選択します。まだ作成していない場合は、+ 新規追加をクリックして場所を作成します。
5. 登録するをクリックしてリーダーの登録を完了します。

API を使用して登録する

大規模なデプロイでは、現場のユーザーがそれぞれ新しいリーダーを受け取って設定できるようにします。アプリで、Stripe API を使用してリーダーを登録するフローを構築します。

1. Verifone P400 をお持ちの場合は、0-7-1-3-9 の順にキーを入力すると、固有の登録コードが表示されます。BBPOS WisePOS E または Stripe リーダー S700 をお持ちの場合は、リーダー設定に移動し、ペアリングコードを生成をタップします。
2. ユーザーはアプリケーションにそのコードを入力します。
3. アプリケーションはそのコードを Stripe に送信します。

curl https://api.stripe.com/v1/terminal/readers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d registration_code={{READER_REGISTRATION_CODE}} \
  --data-urlencode label="Alice's reader" \
  -d location=
{{LOCATION_ID}}

リーダーが正しく登録されたことを確認するには、その場所で登録したリーダーをすべて一覧表示します。

curl https://api.stripe.com/v1/terminal/readers \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:

POS アプリケーションをリーダーに接続するには、選択したリーダーで connectReader を呼び出します。

You can scope your discovery using the location you registered the reader to in the previous step.

async function discoverReaders() {
  const config = {simulated: false, location: 
'{{LOCATION_ID}}'}
  const discoverResult = await terminal.discoverReaders(config);
  if (discoverResult.error) {
    console.log('Failed to discover: ', discoverResult.error);
  } else if (discoverResult.discoveredReaders.length === 0) {
    console.log('No available readers.');
  } else {
    // You should show the list of discoveredReaders to the
    // cashier here and let them select which to connect to (see below).
    connectReader(discoverResult);
  }
}

POS アプリケーションをリーダーに接続するには、選択したリーダーで connectReader を呼び出します。

async function connectReader(discoverResult) {
  // Just select the first reader here.
  const selectedReader = discoverResult.discoveredReaders[0];

  const connectResult = await terminal.connectReader(selectedReader);
  if (connectResult.error) {
    console.log('Failed to connect:', connectResult.error);
  } else {
    console.log('Connected to reader:', connectResult.reader.label);
  }
}

Multiple connections

Only one instance of the Stripe Terminal SDK can connect to a reader at a given time. By default, when you call connectReader from another application, the incoming connection replaces the existing SDK-to-reader connection, and the previously connected SDK disconnects from the reader. The connectReader method takes a configuration object with a fail_if_in_use property, whose default value is false. When your application sets fail_if_in_use to true, the connectReader call has an alternate behavior where the incoming connection fails when the reader is in the middle of a collectPaymentMethod or processPayment call initiated by another SDK. If the reader is connected to another SDK but is idle (displaying the splash screen before collectPaymentMethod is called), setting fail_if_in_use has no change to the connection behavior, and the incoming connection request can always break the existing SDK-to-reader connection.

const connectResult = await terminal.connectReader(reader, {fail_if_in_use: true});

For the least-disruptive connection experience in multi-reader environments, we recommend setting fail_if_in_use to true on your application’s initial connection attempt. Then, allow your users to retry the connection with fail_if_in_use set to false if the connection fails the first time.

With this setup, one of your users can’t accidentally interrupt a transaction by inadvertently connecting to an in-use reader, but can still connect if needed.

接続切断に対処する

Your app must implement the onUnexpectedReaderDisconnect callback to handle when a reader disconnects. When you implement this callback, display a UI that notifies your user of the disconnected reader. You can call discoverReaders to scan for readers and initiate reconnection.

Your app can attempt to automatically reconnect to the disconnected reader or display a UI that prompts your user to reconnect to a different reader.

リーダーでは、ネットワークへの接続が失われるとアプリとの接続が切断されることがあります。想定外の接続の切断をシミュレーションするには、リーダーの電源をオフにします。

const terminal = StripeTerminal.create({
  onFetchConnectionToken: fetchConnectionToken,
  onUnexpectedReaderDisconnect: unexpectedDisconnect,
});

function unexpectedDisconnect() {
  // Consider displaying a UI to notify the user and start rediscovering readers
}

自動再接続

Stripe Terminal は、アプリケーションの起動時にリーダーに自動的に再接続しません。代わりに、リーダー ID を保存し、起動時に既知のリーダーへの接続を行うことで、再接続フローを構築できます。

1. リーダーに正常に接続したら、シリアル番号を localStorage API などの永続的なデータ格納場所に保存します。
2. アプリが起動したら、その永続的な格納場所に保存されているシリアル番号を確認します。確認できた場合は、discoverReaders メソッドを呼び出して、アプリケーションがそのリーダーを再度見つけられるようにします。
3. 保存されたシリアル番号が検出されたリーダーのいずれかと一致する場合は、discoverReaders の呼び出しから返された一致するリーダーオブジェクトを使用して、そのリーダーへの接続を試してください。以前に接続したリーダーが見つからない場合は、検出プロセスを停止します。

検出および接続プロセス中に何らかの UI を表示して、自動再接続が実行されていることを示します。