Tap to Pay

Tap to Pay erfasst kontaktlose Zahlungen auf einem kompatiblen Telefon oder Tablet ohne separates Kartenlesegerät. Verwenden Sie TerminalConnectTypes.TapToPay nach der Konfiguration und der Einrichtung eines funktionierenden Verbindungstokens.

Die offizielle Demo zeigt Tap to Pay, Internet und Bluetooth in demo/angular.

Plattformvoraussetzungen

Plattform	Unterstützt	Hinweise
Android	Ja	NFC-fähiges Gerät, Standortberechtigung und Erfüllung der Voraussetzungen für Stripe Tap to Pay auf Android. minSdkVersion 26.
iOS	Ja	Tap to Pay auf dem iPhone; iOS 16.4+ für die Prüfung der Kontoverknüpfung. setTapToPayUxConfiguration ist nicht implementiert.
Web	Nein	discoverReaders({ type: TapToPay }) ist nicht verfügbar.

Schließen Sie die Terminal-Einrichtung im Stripe-Dashboard ab und erstellen Sie einen Standort. Übergeben Sie dessen locationId an discoverReaders; das Plugin verwendet sie beim Verbinden des Tap-to-Pay-Lesegeräts.

Unter Android fordert initialize die unter Konfiguration angegebene Standortberechtigung an. Bluetooth-Berechtigungen werden nur bei der Suche nach Bluetooth- oder Simulated-Lesegeräten angefordert; die Tap-to-Pay-Suche selbst fordert sie nicht an.

Einrichtungsreihenfolge

1. Registrieren Sie Listener auf Anwendungsebene.
2. Registrieren Sie einen authentifizierten Verbindungstoken-Anbieter mit RequestedConnectionToken + setConnectionToken und rufen Sie anschließend initialize auf.
3. Rufen Sie unter iOS isTapToPayAccountLinked auf und speichern Sie das Ergebnis nicht zwischen.
4. Rufen Sie unter Android bei Bedarf setTapToPayUxConfiguration auf.
5. Rufen Sie discoverReaders mit type: TerminalConnectTypes.TapToPay und locationId auf.
6. Rufen Sie connectReader mit dem gefundenen Lesegerät auf.
7. Erfassen Sie die Zahlungsmethode und bestätigen Sie einen card_present-PaymentIntent wie unter Eine Zahlung abwickeln beschrieben.

method initialize(...)

Initialisiert das Stripe Terminal SDK und seinen Anbieter für Verbindungstoken.
Vor der Lesegerätesuche einmal aufrufen.

Wenn tokenProviderEndpoint angegeben ist, sendet das Plugin eine POST-Anfrage
und erwartet { secret: string }. Wenn der Wert fehlt, stattdessen
RequestedConnectionToken behandeln und setConnectionToken() aufrufen.

initialize(options: StripeTerminalInitializationOptions) => Promise<void>

Die Kontoverknüpfung prüfen

isTapToPayAccountLinked ist nur unter iOS verfügbar und erfordert iOS 16.4 oder neuer. initialize() muss ausgeführt worden sein, damit dem SDK ein Verbindungstoken-Anbieter zur Verfügung steht. Eine Verbindung zu einem Lesegerät ist nicht erforderlich, und der Aufruf aktiviert NFC nicht.

Die Antwort wird bei jedem Aufruf von Apple abgerufen. Speichern Sie isLinked nicht zwischen. Übergeben Sie bei Stripe Connect die ID des verbundenen Kontos als onBehalfOf; lassen Sie den Wert weg, um das Konto zu prüfen, dem der API-Schlüssel gehört.

Android und Web weisen den Aufruf ab (unimplemented / unavailable). Sichern Sie ihn durch eine Plattformprüfung oder .catch() ab, wie die offizielle Demo es für die Android-spezifische Oberflächenkonfiguration tut.

method isTapToPayAccountLinked(...)

Prüfen, ob der Händler die Geschäftsbedingungen von Apple für Tap to Pay auf dem iPhone
akzeptiert hat.

Nur iOS; erfordert iOS 16.4 oder neuer. initialize() muss zuvor
aufgerufen worden sein, da das SDK einen Anbieter für Verbindungstoken benötigt. Eine
Lesegeräteverbindung ist jedoch nicht erforderlich, und der Aufruf aktiviert das Gerät nicht.

Die Antwort wird bei jedem Aufruf von Apple abgerufen. Die Anforderungen von Apple für Tap to Pay auf dem iPhone
schreiben vor, dass der Zustimmungsstatus von Apple abgefragt werden muss
statt aus einer lokalen Variable. Speichern Sie das Ergebnis daher nicht im Cache.

Referenz in der Stripe-Dokumentation

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

interface IsTapToPayAccountLinkedOptions

Optionen für isTapToPayAccountLinked.

Eigenschaft	Typ	Beschreibung	Seit
onBehalfOf	string	Kennung des verbundenen Kontos für Stripe-Connect-Plattformen. Weglassen, um das Konto zu prüfen, dem der API-Schlüssel gehört.	8.2.0

Oberflächenkonfiguration

setTapToPayUxConfiguration ist nur unter Android verfügbar. Rufen Sie es nach initialize() und vor connectReader() auf. iOS meldet, dass die Methode nicht implementiert ist; im Web wird der Aufruf protokolliert und beendet.

Die installierte Android-Implementierung wendet colors (primary, success, error jeweils als 'default' oder Hex-Zeichenfolge wie '#FF5733') und darkMode (SYSTEM, DARK, LIGHT) an. Das TypeScript-Feld tapZone ist deklariert, wird aber im aktuellen Android Terminal SDK von v8.2.1 nicht angewendet.

method setTapToPayUxConfiguration(...)

Die Darstellung der Tap-to-Pay-Bedienoberfläche konfigurieren (nur Android).
Nach initialize(), aber vor connectReader() aufrufen.
Hat auf iOS- und Webplattformen keine Wirkung.

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

interface TapToPayUxConfiguration

Konfiguration für die Tap-to-Pay-Bedienoberfläche (nur Android).

Eigenschaft	Typ	Beschreibung	Seit
colors	TapToPayColorScheme	Farbschema für die Tap-to-Pay-Oberfläche.	8.1.0
darkMode	TapToPayDarkMode	Dark-Mode-Einstellung für die Tap-to-Pay-Oberfläche.	8.1.0
tapZone	TapToPayTapZone	Position des Berührungsindikators auf dem Bildschirm.	8.1.0

interface TapToPayColorScheme

Farbschema für die Tap-to-Pay-Oberfläche.

Eigenschaft	Typ	Beschreibung	Seit
primary	TapToPayColor	Primärfarbe für den Berührungsbereichsindikator. Einen Hexadezimalwert oder default verwenden.	8.1.0
success	TapToPayColor	Farbe des Erfolgszustands. Einen Hexadezimalwert oder default verwenden.	8.1.0
error	TapToPayColor	Farbe des Fehlerzustands. Einen Hexadezimalwert oder default verwenden.	8.1.0

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 }

enum TapToPayDarkMode

Mitglied	Wert
System	'SYSTEM'
Dark	'DARK'
Light	'LIGHT'

Suchen und verbinden

Suchen Sie mit TerminalConnectTypes.TapToPay und einer locationId. Simuliertes Tap to Pay verwendet isTest: true in initialize, nicht TerminalConnectTypes.Simulated.

Verbinden Sie das Lesegerät aus dem Suchergebnis. autoReconnectOnUnexpectedDisconnect ist standardmäßig false und wird für Tap to Pay unterstützt. Unter iOS werden merchantDisplayName und onBehalfOf an die Tap-to-Pay-Verbindungskonfiguration übergeben. Unter Android setzen Sie diese Werte stattdessen am PaymentIntent.

method discoverReaders(...)

Sucht Lesegeräte mit der gewünschten Verbindungsart. Die zurückgegebenen Lesegeräte sind
Momentaufnahmen; auf DiscoveredReaders reagieren, wenn die fortlaufende Suche
weitere Ergebnisse liefern kann.

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

method connectReader(...)

Verbindet ein von discoverReaders() zurückgegebenes Lesegerät.

connectReader(options: ConnectReaderOptions) => Promise<void>

Verwenden Sie nach dem Verbinden collectPaymentMethod und confirmPaymentIntent mit einem auf dem Server erstellten card_present-PaymentIntent.

Einschränkungen

• Im Web können Tap-to-Pay-Lesegeräte weder gesucht noch verbunden werden.
• Oberflächenfarben und Dunkelmodus sind nur unter Android verfügbar; iOS verwendet die Systemoberfläche für Tap to Pay auf dem iPhone.
• Der Status der Kontoverknüpfung ist nur unter iOS verfügbar und muss jedes Mal erneut von Apple abgerufen werden.
• tapZone gehört zur TypeScript-API, ist aber nicht an das installierte Android SDK angebunden.
• Optionale Softwareupdates für Lesegeräte folgen weiterhin den Regeln unter Lebenszyklus des Lesegeräts: Installieren Sie sie nicht während des Bezahlvorgangs.
• Belassen Sie geheime Stripe-Schlüssel und die Erstellung von Verbindungstoken im Backend.

import {
  StripeTerminal,
  TapToPayDarkMode,
  TerminalConnectTypes,
} from '@capacitor-community/stripe-terminal';
import { Capacitor } from '@capacitor/core';

// Register the authenticated RequestedConnectionToken provider first.
await StripeTerminal.initialize({ isTest: true });

if (Capacitor.getPlatform() === 'ios') {
  const { isLinked } = await StripeTerminal.isTapToPayAccountLinked();
  console.log(isLinked);
}

if (Capacitor.getPlatform() === 'android') {
  await StripeTerminal.setTapToPayUxConfiguration({
    colors: { primary: '#FF5733' },
    darkMode: TapToPayDarkMode.Light,
  });
}

const { readers } = await StripeTerminal.discoverReaders({
  type: TerminalConnectTypes.TapToPay,
  locationId: '**************',
});

const reader = readers[0];
if (!reader) throw new Error('Tap to Pay is not available on this device');

await StripeTerminal.connectReader({
  reader,
  autoReconnectOnUnexpectedDisconnect: true,
});