Tap to Pay

Tap to Pay permet d’encaisser des paiements sans contact sur un téléphone ou une tablette compatible, sans lecteur de carte séparé. Utilisez TerminalConnectTypes.TapToPay après la configuration et la mise en place d’un jeton de connexion fonctionnel.

La démo officielle présente Tap to Pay, Internet et Bluetooth dans demo/angular.

Prérequis des plateformes

Plateforme	Pris en charge	Remarques
Android	Oui	Appareil compatible NFC, autorisation de localisation et admissibilité à Stripe Tap to Pay sur Android. minSdkVersion 26.
iOS	Oui	Tap to Pay sur iPhone ; iOS 16.4+ pour la vérification de l’association du compte. setTapToPayUxConfiguration n’est pas implémenté.
Web	Non	discoverReaders({ type: TapToPay }) est indisponible.

Terminez la configuration Terminal dans le Dashboard Stripe et créez un emplacement. Transmettez ce locationId à discoverReaders ; le plugin l’utilise pour connecter le lecteur Tap to Pay.

Sur Android, initialize demande l’autorisation de localisation indiquée dans Configuration. Les autorisations Bluetooth ne sont demandées que lors de la recherche de lecteurs Bluetooth ou Simulated ; la recherche Tap to Pay elle-même ne les demande pas.

Ordre de configuration

1. Enregistrez les écouteurs au niveau de l’application.
2. Enregistrez un fournisseur authentifié de jetons de connexion avec RequestedConnectionToken + setConnectionToken, puis appelez initialize.
3. Sur iOS, appelez isTapToPayAccountLinked sans mettre le résultat en cache.
4. Sur Android, appelez éventuellement setTapToPayUxConfiguration.
5. Appelez discoverReaders avec type: TerminalConnectTypes.TapToPay et locationId.
6. Appelez connectReader avec le lecteur découvert.
7. Recueillez le moyen de paiement et confirmez un PaymentIntent card_present comme indiqué dans Encaisser un paiement.

method initialize(...)

Initialise le SDK Stripe Terminal et son fournisseur de jetons de connexion.
Appelez cette méthode une fois avant de découvrir les lecteurs.

Lorsque tokenProviderEndpoint est fourni, le plugin envoie une requête POST et attend { secret: string }. Si ce paramètre est omis, gérez plutôt RequestedConnectionToken et appelez setConnectionToken().

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

Vérifier l’association du compte

isTapToPayAccountLinked est réservé à iOS et nécessite iOS 16.4 ou une version ultérieure. initialize() doit avoir été exécuté pour que le SDK dispose d’un fournisseur de jetons de connexion. Aucune connexion à un lecteur n’est nécessaire et l’appel n’active pas le NFC.

La réponse est obtenue auprès d’Apple à chaque appel. Ne mettez pas isLinked en cache. Pour Stripe Connect, transmettez l’identifiant du compte connecté dans onBehalfOf ; omettez-le pour vérifier le compte propriétaire de la clé API.

Android et le Web rejettent l’appel (unimplemented / unavailable). Protégez-le par une vérification de plateforme ou un .catch(), comme le fait la démo officielle pour la configuration d’interface propre à Android.

method isTapToPayAccountLinked(...)

Vérifie si le commerçant a accepté les conditions générales d’Apple pour Tap to Pay sur iPhone.

iOS uniquement, à partir d’iOS 16.4. initialize() doit avoir été appelé au préalable, car le SDK nécessite un fournisseur de jetons de connexion. Aucune connexion à un lecteur n’est toutefois requise, et l’appel n’active pas l’appareil.

La réponse est récupérée auprès d’Apple à chaque appel. Les exigences d’Apple pour Tap to Pay sur iPhone imposent de récupérer l’état d’acceptation auprès d’Apple plutôt que depuis une variable locale : ne mettez donc pas le résultat en cache.

Référence de la documentation Stripe

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

interface IsTapToPayAccountLinkedOptions

Options de isTapToPayAccountLinked.

Propriété	Type	Description	Depuis
onBehalfOf	string	Identifiant du compte connecté pour les plateformes Stripe Connect. Omettez-le pour vérifier le compte auquel appartient la clé d’API.	8.2.0

Configuration de l’interface

setTapToPayUxConfiguration est réservé à Android. Appelez-le après initialize() et avant connectReader(). iOS renvoie une erreur de non-implémentation ; le Web journalise l’appel puis se termine.

L’implémentation Android installée applique colors (primary, success, error, avec 'default' ou une chaîne hexadécimale comme '#FF5733') et darkMode (SYSTEM, DARK, LIGHT). Le champ TypeScript tapZone est déclaré, mais n’est pas appliqué par le SDK Terminal Android actuel utilisé dans v8.2.1.

method setTapToPayUxConfiguration(...)

Configure l’apparence de l’expérience Tap to Pay (Android uniquement).
Appelez cette méthode après initialize(), mais avant connectReader().
Sans effet sur iOS et le Web.

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

interface TapToPayUxConfiguration

Configuration de l’expérience Tap to Pay (Android uniquement).

Propriété	Type	Description	Depuis
colors	TapToPayColorScheme	Palette de couleurs de l’écran Tap to Pay.	8.1.0
darkMode	TapToPayDarkMode	Paramètre de mode sombre de l’écran Tap to Pay.	8.1.0
tapZone	TapToPayTapZone	Position de l’indicateur d’appui à l’écran.	8.1.0

interface TapToPayColorScheme

Palette de couleurs de l’écran Tap to Pay.

Propriété	Type	Description	Depuis
primary	TapToPayColor	Couleur principale de l’indicateur de zone d’appui. Utilisez une chaîne hexadécimale ou default.	8.1.0
success	TapToPayColor	Couleur de l’état de réussite. Utilisez une chaîne hexadécimale ou default.	8.1.0
error	TapToPayColor	Couleur de l’état d’erreur. Utilisez une chaîne hexadécimale ou default.	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

Membre	Valeur
System	'SYSTEM'
Dark	'DARK'
Light	'LIGHT'

Rechercher et connecter

Recherchez avec TerminalConnectTypes.TapToPay et un locationId. La simulation Tap to Pay utilise isTest: true dans initialize, et non TerminalConnectTypes.Simulated.

Connectez le lecteur issu du résultat de recherche. autoReconnectOnUnexpectedDisconnect vaut false par défaut et est pris en charge pour Tap to Pay. Sur iOS, merchantDisplayName et onBehalfOf sont transmis à la configuration de connexion Tap to Pay. Sur Android, définissez plutôt ces valeurs sur le PaymentIntent.

method discoverReaders(...)

Découvre les lecteurs avec le mode de communication demandé. Les lecteurs renvoyés sont des instantanés ; écoutez DiscoveredReaders lorsque la découverte continue peut produire des résultats supplémentaires.

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

method connectReader(...)

Se connecte à un lecteur renvoyé par discoverReaders().

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

Après la connexion, utilisez collectPaymentMethod et confirmPaymentIntent avec un PaymentIntent card_present créé sur le serveur.

Limitations

• Le Web ne permet ni de rechercher ni de connecter Tap to Pay.
• Les couleurs de l’interface et le mode sombre sont réservés à Android ; iOS utilise l’interface système Tap to Pay sur iPhone.
• L’état d’association du compte est réservé à iOS et doit être redemandé à Apple à chaque fois.
• tapZone fait partie de l’API TypeScript, mais n’est pas transmis au SDK Android installé.
• Les mises à jour facultatives du logiciel des lecteurs suivent toujours les règles de Cycle de vie du lecteur : ne les installez pas pendant l’encaissement.
• Conservez les clés secrètes Stripe et la création des jetons de connexion sur le 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,
});