Se connecter à un lecteur

Avant de pouvoir connecter votre application à un lecteur intelligent, vous devez enregistrer le lecteur sur votre compte.

Enregistrement dans le Dashboard

Vous pouvez ajouter votre lecteur directement dans le Dashboard.

Enregistrer par code d’enregistrement

1. Sur la page Lecteurs, cliquez sur Enregistrer un lecteur.
2. Si vous disposez d’un lecteur Verifone P400, saisissez la séquence 0-7-1-3-9 pour afficher un code d’enregistrement unique. Si vous disposez d’un lecteur BBPOS WisePOS E ou d’un lecteur Stripe S700, accédez aux paramètres du lecteur, puis appuyez sur Générer un code d’association.
3. Saisissez le code d’enregistrement et cliquez sur Suivant.
4. Vous pouvez facultativement choisir un nom pour le lecteur.
5. Si vous avez déjà créé un emplacement, sélectionnez le nouvel emplacement du lecteur. Sinon, créez-en un en cliquant sur + Ajouter un emplacement.
6. Cliquez sur Enregistrer pour terminer l’enregistrement de votre lecteur.

Enregistrer par numéro de série

1. Sur la page Lecteurs, cliquez sur Enregistrer un lecteur.
2. Recherchez le numéro de série de l’appareil et saisissez-le. Pour enregistrer plusieurs appareils à la fois, vous pouvez saisir plusieurs numéros de série séparés par des virgules.
3. Vous pouvez facultativement choisir un nom pour le lecteur.
4. Si vous avez déjà créé un emplacement, sélectionnez le nouvel emplacement du lecteur. Sinon, créez-en un en cliquant sur + Ajouter un emplacement.
5. Cliquez sur Enregistrer pour terminer l’enregistrement de votre lecteur.

Enregistrer par commande de matériel

1. Sur la page Commandes de matériel, trouvez une commande dont le statut est « expédié » ou « livré ». Cliquez sur le menu de débordement () à la fin de la ligne, puis cliquez sur Enregistrer.
2. Sur la page Enregistrer des lecteurs, sélectionnez un ou plusieurs lecteurs dans la commande de matériel à enregistrer, puis cliquez sur Enregistrer.
3. Vous pouvez facultativement choisir un nom pour le lecteur. Si vous avez sélectionné plusieurs lecteurs, le nom sert de préfixe et nous nommons les lecteurs de manière séquentielle (par exemple, pour une entrée donnée « Lecteur de test », nous nommons les lecteurs « Lecteur de test 1 », « Lecteur de test 2 », et ainsi de suite).
4. Si vous avez déjà créé un emplacement, sélectionnez le nouvel emplacement du lecteur. Sinon, créez-en un en cliquant sur + Ajouter un emplacement.
5. Cliquez sur Enregistrer pour terminer l’enregistrement de vos lecteurs.

Enregistrement à l’aide de l’API

Dans le cadre de déploiements de plus grande envergure, donnez à vos utilisateurs sur le terrain la possibilité de recevoir et de configurer eux-mêmes de nouveaux lecteurs. Dans votre application, créez un flux permettant d’enregistrer un lecteur à l’aide de l’API Stripe.

1. Si vous disposez d’un lecteur Verifone P400, saisissez la séquence 0-7-1-3-9 pour afficher un code d’enregistrement unique. Si vous disposez d’un lecteur BBPOS WisePOS E ou d’un lecteur Stripe S700, accédez aux paramètres du lecteur, puis appuyez sur Générer un code d’association.
2. L’utilisateur saisit le code dans votre application.
3. Votre application envoie le code à 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}}

Afin de confirmer le bon enregistrement de votre lecteur, listez tous les lecteurs que vous avez enregistrés à cet emplacement :

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

Pour connecter votre application de point de vente à un lecteur, appelez connectReader en indiquant le lecteur sélectionné.

Vous pouvez affiner votre recherche en spécifiant l’emplacement location dans lequel vous avez enregistré le lecteur lors de l’étape précédente.

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

Pour connecter votre application de point de vente à un lecteur, appelez connectReader en indiquant le lecteur sélectionné.

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

Connexions multiples

Une seule instance du SDK Stripe Terminal peut se connecter à un lecteur à la fois. Par défaut, lorsque vous appelez connectReader à partir d’une autre application, la connexion entrante remplace la connexion existante entre le SDK et le lecteur, et le SDK précédemment connecté se déconnecte du lecteur. La méthode 'connectReader utilise un objet de configuration avec une propriété fail_if_in_use dont la valeur par défaut est false. Lorsque votre application définit fail_if_in_use sur « true », l’appel connectReader présente un autre comportement : la connexion entrante échoue lorsque le lecteur est au milieu d’un appel collectPaymentMethod ou processPayment lancé par un autre SDK. Si le lecteur est connecté à un autre SDK mais qu’il est inactif (s’il affiche l’écran d’accueil avant l’appel de collectPaymentMethod), le paramétrage de fail_if_in_use ne modifie pas le comportement de la connexion, et la demande de connexion entrante peut toujours interrompre la connexion SDK-lecteur existante.

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

Pour perturber le moins possible l’expérience de connexion dans les environnements à plusieurs lecteurs, nous vous recommandons de définir la valeur fail_if_in_use sur true lors de la première tentative de connexion de votre application. Ensuite, permettez à vos utilisateurs de réessayer la connexion avec fail_if_in_use sur false si la connexion échoue la première fois.

Avec cette configuration, vos utilisateurs ne peuvent pas interrompre accidentellement une transaction en se connectant par inadvertance à un lecteur en cours d’utilisation, mais peuvent toujours se connecter si nécessaire.

Gérer les déconnexions

Votre application doit implémenter le rappel onUnexpectedReaderDisconnect afin de remédier à toute déconnexion du lecteur. Lors de la mise en place de ce rappel, affichez une interface utilisateur qui informe l’utilisateur de la déconnexion du lecteur. Vous pouvez appeler discoverReaders pour rechercher des lecteurs et initier une reconnexion.

Votre application peut tenter de se reconnecter automatiquement au lecteur déconnecté ou afficher une interface utilisateur qui invite l’utilisateur à se reconnecter à un autre lecteur.

Le lecteur peut se déconnecter de votre application s’il perd la connexion au réseau. Pour simuler une déconnexion inattendue, éteignez le lecteur.

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

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

Reconnexion automatique

Stripe Terminal ne se reconnecte pas automatiquement à un lecteur au démarrage de votre application. Vous pouvez créer un flux de reconnexion en enregistrant les ID de lecteur et en essayant de vous connecter à un lecteur connu au démarrage.

1. Lorsque vous vous connectez à un lecteur, enregistrez son numéro de série dans un emplacement de stockage persistant, comme l’API localStorage.
2. Au lancement de votre application, vérifiez si un numéro de série enregistré se trouve dans cet emplacement persistant. Si vous en trouvez un, appelez la méthode discoverReaders afin que votre application puisse essayer de retrouver le lecteur.
3. Si le numéro de série enregistré correspond à l’un des lecteurs détectés, essayez de vous connecter à ce lecteur à l’aide de l’objet Reader correspondant renvoyé par l’appel à discoverReaders. Si le lecteur en question est introuvable, mettez fin au processus de recherche.

Au cours du processus de détection et de connexion, vous pouvez afficher un message d’interface utilisateur indiquant qu’une reconnexion automatique est en cours.