Cycle de vie du lecteur

Gérez les mises à jour du logiciel, l’état du lecteur et les messages d’affichage afin que les opérations Terminal n’interrompent pas l’encaissement.

Écouter les mises à jour du logiciel

Le lecteur peut commencer à se mettre à jour si nécessaire. Écoutez les mises à jour disponibles, installez-les ou annulez-les et affichez la progression pendant l’installation.

Contraintes :

Appelez setSimulatorConfiguration avant discoverReaders pour simuler une mise à jour (SimulateReaderUpdate.UpdateAvailable ou Required). Sur le Web, setSimulatorConfiguration est sans effet.
StartInstallingUpdate, ReaderSoftwareUpdateProgress et FinishInstallingUpdate s’appliquent aux lecteurs Bluetooth et USB. Une mise à jour obligatoire à la première connexion s’installe automatiquement, avant ConnectedReader et avant que connectReader() se termine. Ordre : StartInstallingUpdate → ReaderSoftwareUpdateProgress (répété) → FinishInstallingUpdate → ConnectedReader → résolution de connectReader(). Affichez une indication dans l’interface pour qu’une connexion longue ne soit pas prise pour un blocage.
ReportAvailableUpdate indique qu’une mise à jour facultative est prête ; appelez installAvailableUpdate lorsque le commerçant peut attendre. Ne lancez pas d’installation facultative pendant l’encaissement.
progress est un nombre à virgule flottante compris entre 0 et 1.
cancelInstallUpdate annule une installation en cours lorsque le SDK le permet. Les méthodes Web d’installation et d’annulation sont sans effet.
Tap to Pay sur iOS signale aussi le début, la progression et la fin de l’installation via le délégué du lecteur Tap to Pay. L’interface Tap to Pay sur Android est distincte ; consultez Tap to Pay.

 method installAvailableUpdate()Installe la mise à jour logicielle signalée par ReportAvailableUpdate.
installAvailableUpdate() => Promise<void>

 method cancelInstallUpdate()Annule une mise à jour logicielle facultative du lecteur en cours.
cancelInstallUpdate() => Promise<void>

 method setSimulatorConfiguration(...)Configure le lecteur simulé utilisé en mode test. Appelez cette méthode avant l’opération dont vous souhaitez simuler le comportement.
Référence de la documentation Stripe
setSimulatorConfiguration(options: SimulatorConfigurationOptions) => Promise<void>

Écouter l’état et les demandes de saisie

Pour les lecteurs sans écran, récupérez le niveau de batterie, les événements du lecteur, les messages d’affichage et les demandes de saisie via les écouteurs, puis affichez-les sur l’appareil mobile.

BatteryLevel, ReaderEvent, RequestDisplayMessage et RequestReaderInput s’appliquent aux lecteurs Bluetooth et USB. Les mises à jour de batterie sont émises à la connexion et environ toutes les 10 minutes.

Définir l’affichage du lecteur

Sur les appareils avec écran, affichez le contenu du panier avant collectPaymentMethod. Effacez l’affichage une fois terminé. Les lecteurs Internet sur le Web prennent en charge ces appels.

 method setReaderDisplay(...)Affiche les informations du panier sur un lecteur doté d’un écran destiné au client.
setReaderDisplay(options: Cart) => Promise<void>

 method clearReaderDisplay()Efface les informations du panier de l’écran du lecteur destiné au client.
clearReaderDisplay() => Promise<void>

 interface CartTotaux du Cart affichés sur l’écran du lecteur destiné au client.


Propriété
Type
Description
Depuis


currency
string
Code de devise ISO 4217 à trois lettres.
6.2.0

tax
number
Montant de la taxe dans la plus petite unité de la devise.
6.2.0

total
number
Total du Cart dans la plus petite unité de la devise.
6.2.0

lineItems
CartLineItem[]
Articles affichés dans le panier.
6.2.0

Propriété	Type	Description	Depuis
`currency`	`string`	Code de devise ISO 4217 à trois lettres.	6.2.0
`tax`	`number`	Montant de la taxe dans la plus petite unité de la devise.	6.2.0
`total`	`number`	Total du Cart dans la plus petite unité de la devise.	6.2.0
`lineItems`	`CartLineItem[]`	Articles affichés dans le panier.	6.2.0

 interface CartLineItemLigne affichée sur l’écran du lecteur destiné au client.


Propriété
Type
Description
Depuis


displayName
string
Nom de l’article affiché sur le lecteur.
6.2.0

quantity
number
Nombre d’unités dans le panier.
6.2.0

amount
number
Montant de la ligne dans la plus petite unité de la devise.
6.2.0

Propriété	Type	Description	Depuis
`displayName`	`string`	Nom de l’article affiché sur le lecteur.	6.2.0
`quantity`	`number`	Nombre d’unités dans le panier.	6.2.0
`amount`	`number`	Montant de la ligne dans la plus petite unité de la devise.	6.2.0

Annuler la recherche

Appelez cancelDiscoverReaders lorsque l’utilisateur quitte l’écran de recherche ou après un délai d’expiration. En cas de réussite, les plateformes natives émettent CancelDiscoveredReaders. Si aucune recherche n’est en cours, la promesse est tout de même résolue.

La recherche Bluetooth sur iOS peut durer longtemps et continuer à émettre DiscoveredReaders. Associez l’annulation à bluetoothScanWaitTime ou à votre propre délai d’expiration. Sur le Web, cancelDiscoverReaders est sans effet.

 method cancelDiscoverReaders()Annule l’opération de découverte de lecteurs en cours.
cancelDiscoverReaders() => Promise<void>

Déconnexion et reconnexion

disconnectReader déconnecte le lecteur actuel. Si aucun lecteur n’est connecté, la promesse est résolue.

Comportement de DisconnectedReader :

Tous les types de lecteurs l’émettent en réponse à disconnectReader(), sans reason.
Bluetooth et USB l’émettent aussi avec un reason lorsque la déconnexion du lecteur est terminée. Une déconnexion demandée par l’utilisateur produit donc deux événements : l’accusé de réception, puis la déconnexion accompagnée de sa raison.

Ne considérez pas ConnectionStatusChange comme une déconnexion inattendue. Utilisez UnexpectedReaderDisconnect pour avertir l’utilisateur. Vous pouvez rappeler discoverReaders pour vous reconnecter ; prévoyez toujours un délai d’expiration ou cancelDiscoverReaders.

Définissez autoReconnectOnUnexpectedDisconnect: true dans connectReader pour Tap to Pay et Bluetooth si vous souhaitez que le SDK réessaie. Écoutez ensuite :

ReaderReconnectStarted — contient reader et reason
ReaderReconnectSucceeded
ReaderReconnectFailed

cancelReaderReconnection annule une reconnexion en cours. Sur le Web, rebootReader et cancelReaderReconnection sont sans effet.

 method getConnectedReader()Renvoie le lecteur actuellement connecté, ou null s’il est déconnecté.
getConnectedReader() => Promise<{ reader: ReaderInterface | null; }>

 method rebootReader()Redémarre le lecteur connecté. Les types de lecteurs pris en charge dépendent de la plateforme.
rebootReader() => Promise<void>

 method cancelReaderReconnection()Annule une tentative de reconnexion automatique du lecteur.
cancelReaderReconnection() => Promise<void>

Gestion des erreurs

Failed est émis si la collecte ou la confirmation échoue ; la promesse correspondante est rejetée avec les mêmes message / code / declineCode lorsque le SDK natif les fournit.

UnexpectedReaderDisconnect signifie que Terminal a perdu la connexion au lecteur en dehors de disconnectReader(). Pour Bluetooth et USB, inspectez DisconnectedReader pour obtenir le DisconnectReason (POWERED_OFF, BLUETOOTH_DISABLED, CRITICALLY_LOW_BATTERY, etc.).

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

Plugins Capacitor

Cycle de vie du lecteur

Écouter les mises à jour du logiciel

`method` installAvailableUpdate()

`method` cancelInstallUpdate()

`method` setSimulatorConfiguration(...)

Écouter l’état et les demandes de saisie

Définir l’affichage du lecteur

`method` setReaderDisplay(...)

`method` clearReaderDisplay()

`interface` Cart

`interface` CartLineItem

Annuler la recherche

`method` cancelDiscoverReaders()

Déconnexion et reconnexion

`method` getConnectedReader()

`method` rebootReader()

`method` cancelReaderReconnection()

Gestion des erreurs