Mit einem Lesegerät verbinden

Bevor Sie Ihre Anwendung mit einem intelligenten Lesegerät verbinden können, müssen Sie das Lesegerät in Ihrem Konto registrieren.

Im Dashboard registrieren

Sie können Ihr Lesegerät direkt im Dashboard hinzufügen.

Mit Registrierungscode registrieren

1. Klicken Sie auf der Seite Lesegeräte auf Lesegerät registrieren.
2. Wenn Sie ein Verifone P400 haben, geben Sie die Tastenfolge 0-7-1-3-9 ein, um einen einmaligen Registrierungscode anzuzeigen. Wenn Sie ein BBPOS WisePOS E oder einen Stripe Reader S700, haben, gehen Sie zu den Einstellungen des Lesegeräts und tippen Sie auf Kopplungscode generieren.
3. Geben Sie den Registrierungscode ein und klicken Sie auf Weiter.
4. Wählen Sie optional einen Namen für das Lesegerät aus.
5. Wenn Sie bereits einen Standort erstellt haben, wählen Sie den neuen Standort des Lesegeräts aus. Andernfalls erstellen Sie einen Standort, indem Sie auf + Neu hinzufügen klicken.
6. Klicken Sie auf Registrieren, um die Registrierung Ihres Lesegeräts abzuschließen.

Mit Seriennummer registrieren

1. Klicken Sie auf der Seite Lesegeräte auf Lesegerät registrieren.
2. Suchen Sie auf dem Gerät nach der Seriennummer und geben Sie diese ein. Um mehrere Geräte gleichzeitig zu registrieren, können Sie mehrere, durch Kommas getrennte Seriennummern eingeben.
3. Wählen Sie optional einen Namen für das Lesegerät aus.
4. Wenn Sie bereits einen Standort erstellt haben, wählen Sie den neuen Standort des Lesegeräts aus. Andernfalls erstellen Sie einen Standort, indem Sie auf + Neu hinzufügen klicken.
5. Klicken Sie auf Registrieren, um die Registrierung Ihres Lesegeräts abzuschließen.

Nach Hardware-Bestellung registrieren

1. Suchen Sie auf der Seite Hardware-Bestellungen nach einer Bestellung mit dem Status „Versendet“ oder „Geliefert“. Klicken Sie auf das Überlaufmenü () am Ende der Zeile und klicken Sie dann auf Registrieren.
2. Wählen Sie auf der Seite Lesegerät registrieren ein oder mehrere Lesegerät aus der Hardware-Reihenfolge aus, die Sie registrieren möchten, und klicken Sie dann auf Registrieren.
3. Wählen Sie optional einen Namen für das Lesegerät. Wenn Sie mehrere Lesegeräte ausgewählt haben, dient der Name als Präfix und wir benennen die Lesegeräte der Reihe nach (zum Beispiel legen wir für eine bestimmte Eingabe von „Testlesegerät“ die Bezeichnungen „Testlesegerät 1“, „Testlesegerät 2“ usw. fest).
4. Wenn Sie bereits einen Standort erstellt haben, wählen Sie den neuen Standort des Lesegeräts aus. Andernfalls erstellen Sie einen Standort, indem Sie auf + Neu hinzufügen klicken.
5. Klicken Sie auf Registrieren, um die Registrierung Ihrer Lesegeräte abzuschließen.

Mithilfe der API registrieren

Bei größeren Bereitstellungen sollten Sie es den Nutzerinnen/Nutzern vor Ort ermöglichen, neue Lesegeräte selbst zu empfangen und einzurichten. Erstellen Sie in Ihrer App einen Ablauf zum Registrieren eines Lesegeräts mit der Stripe API.

1. Wenn Sie ein Verifone P400 haben, geben Sie die Tastenfolge 0-7-1-3-9 ein, um einen einmaligen Registrierungscode anzuzeigen. Wenn Sie ein BBPOS WisePOS E oder einen Stripe Reader S700, haben, gehen Sie zu den Einstellungen des Lesegeräts und tippen Sie auf Kopplungscode generieren.
2. Der/die Nutzer/in gibt den Code in Ihre Anwendung ein.
3. Ihre Anwendung sendet den Code an 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}}

Um zu prüfen, ob Sie ein Lesegerät korrekt registriert haben, lassen Sie alle an diesem Standort registrierten Lesegeräte auflisten:

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

Um Ihre Point-of-Sale-Anwendung mit einem Lesegerät zu verbinden, rufen Sie mit dem gewünschten Lesegerät connectReader auf.

Sie können Ihre Erkennung anhand des location eingrenzen, bei dem Sie das Lesegerät im vorherigen Schritt registriert haben.

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

Um Ihre Point-of-Sale-Anwendung mit einem Lesegerät zu verbinden, rufen Sie mit dem gewünschten Lesegerät connectReader auf.

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

Mehrere Verbindungen

Es kann immer nur eine Instanz des Stripe Terminal SDK mit einem Lesegerät verbunden werden. Wenn Sie connectReader von einer anderen Anwendung aus aufrufen, ersetzt die eingehende Verbindung standardmäßig die bestehende Verbindung zwischen SDK und Lesegerät, und das zuvor verbundene SDK wird vom Lesegerät getrennt. Die Methode connectReader verwendet ein Konfigurationsobjekt mit der Eigenschaft fail_if_in_use, deren Standardwert false ist. Wenn Ihre Anwendung fail_if_in_use auf „true“ festlegt, weist der connectReader-Aufruf ein alternatives Verhalten auf, bei dem die eingehende Verbindung fehlschlägt, wenn sich das Lesegerät mitten in einem collectPaymentMethod- oder processPayment-Aufruf befindet, der von einem anderen SDK initiiert wurde. Wenn das Lesegerät mit einem anderen SDK verbunden ist, sich aber im Ruhezustand befindet (der Begrüßungsbildschirm wird angezeigt, bevor collectPaymentMethod aufgerufen wird), bewirkt die Einstellung von fail_if_in_use keine Änderung am Verbindungsverhalten und die eingehende Verbindungsanfrage kann die bestehende Verbindung vom SDK zum Lesegerät immer unterbrechen.

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

Für eine möglichst unterbrechungsfreie Verbindung in Umgebungen mit mehreren Lesegeräten empfehlen wir, fail_if_in_use beim ersten Verbindungsversuch Ihrer Anwendung auf true festzulegen. Erlauben Sie Ihren Nutzer/innen dann, den Verbindungsaufbau zu wiederholen, wobei fail_if_in_use auf false gesetzt wird, falls die Verbindung beim ersten Mal fehlschlägt.

Mit dieser Konfiguration kann eine/r Ihrer Nutzer/innen eine Transaktion nicht versehentlich durch eine versehentliche Verbindung zu einem verwendeten Lesegerät unterbrechen, kann aber bei Bedarf trotzdem eine Verbindung herstellen.

Mit Verbindungsabbrüchen umgehen

Ihre App muss den Rückruf onUnexpectedReaderDisconnect für Verbindungsabbrüche bei Lesegeräten implementieren. Wenn Sie diesen Rückruf implementieren, zeigen Sie eine Nutzeroberfläche an, die Ihre Nutzer/innen über das getrennte Lesegerät informiert. Sie können discoverReaders aufrufen, um nach Lesegeräten zu suchen und die erneute Verbindung zu initiieren.

Ihre App kann versuchen, die Verbindung zum getrennten Lesegerät automatisch wiederherzustellen, oder eine Nutzeroberfläche anzeigen, die Ihre Nutzer/innen auffordert, die Verbindung zu einem anderen Lesegerät wiederherzustellen.

Das Lesegerät kann die Verbindung zu Ihrer App trennen, wenn die Verbindung zum Netzwerk unterbrochen wird. Schalten Sie das Lesegerät aus, um eine unerwartete Unterbrechung zu simulieren.

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

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

Automatische Wiederverbindung

Stripe Terminal verbindet sich nicht automatisch erneut mit einem Lesegerät, wenn Ihre Anwendung gestartet wird. Stattdessen können Sie einen Wiederverbindungsablauf erstellen, indem Sie Lesegerät-IDs speichern und versuchen, beim Start eine Verbindung zu einem bekannten Lesegerät herzustellen.

1. Wenn Sie erfolgreich eine Verbindung zu einem Lesegerät hergestellt haben, speichern Sie dessen Seriennummer an einem dauerhaften Datenspeicherort wie beispielsweise der localStorage API.
2. Wenn Ihre App gestartet wird, suchen Sie an diesem dauerhaften Speicherort nach einer gespeicherten Seriennummer. Wird eine solche gefunden, rufen Sie die Methode discoverReaders auf, damit Ihre Anwendung erneut versuchen kann, das Lesegerät zu finden.
3. Wenn die gespeicherte Seriennummer einem der erkannten Lesegeräte entspricht, versuchen Sie, eine Verbindung zu diesem Lesegerät herzustellen, wobei Sie das übereinstimmende reader-Objekt aus dem Aufruf von discoverReaders verwenden. Wenn das zuvor verbundene Lesegerät nicht gefunden wird, brechen Sie den Erkennungsvorgang ab.

Zeigen Sie während des Erkennungs- und Verbindungsvorgangs eine Nutzeroberfläche an, um darauf hinzuweisen, dass eine automatische erneute Verbindung erfolgt.