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
:

Après avoir enregistré le lecteur sur votre compte, recherchez les lecteurs précédemment enregistrés à connecter à votre application de point de vente avec discoverReaders, à l’aide de InternetDiscoveryConfiguration.

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.

var discoveryCancelable: Cancelable? = null

fun onDiscoverReaders() {
    val timeout = 0
    val isSimulated = false

    val config = InternetDiscoveryConfiguration(
        timeout = timeout,
        isSimulated = isSimulated,
        location = 
"{{LOCATION_ID}}"
    )

    // Save this cancelable to an instance variable
    discoveryCancelable = Terminal.getInstance().discoverReaders(
        config,
        object : DiscoveryListener {
            override fun onUpdateDiscoveredReaders(readers: List<Reader>) {
                // Display the discovered readers to the user
            }
        },
        object : Callback {
            override fun onSuccess() {
                // Placeholder for handling successful operation
            }

            override fun onFailure(e: TerminalException) {
                // Placeholder for handling exception
            }
        }
    )
}

override fun onStop() {
    super.onStop()

    // If you're leaving the activity or fragment without selecting a reader,
    // make sure you cancel the discovery process or the SDK will be stuck in
    // a discover readers phase.
    discoveryCancelable?.cancel(
        object : Callback {
            override fun onSuccess() {
                // Placeholder for handling successful operation
            }

            override fun onFailure(e: TerminalException) {
                // Placeholder for handling exception
            }
        }
    )
}

Pour connecter votre application de point de vente à un lecteur, appelez connectReader en indiquant le lecteur sélectionné, à l’aide de la propriété InternetConnectionConfiguration.

val internetReaderListener = yourInternetReaderListener

val config = InternetConnectionConfiguration(internetReaderListener)
Terminal.getInstance().connectReader(
    firstReader,
    config,
    object : ReaderCallback {
        override fun onSuccess(reader: Reader) {
            // Placeholder for handling successful operation
        }

        override fun onFailure(e: TerminalException) {
            // Placeholder for handling exception
        }
    }
)

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 Configuration avec une propriété failIfInUse dont la valeur par défaut est false. Lorsque votre application définit failIfInUse sur true, l’appel connectReader a un comportement alternatif où la connexion entrante échoue lorsque le lecteur est au milieu d’un appel collectPaymentMethod ou confirmPaymentIntent lancé par un SDK. Si le lecteur est connecté à un SDK mais qu’il est inactif (il affiche l’écran d’accueil avant l’appel de collectPaymentMethod), le paramétrage de failIfInUse ne modifie pas le comportement de la connexion. La demande de connexion entrante peut toujours interrompre la connexion SDK-lecteur existante.

val failIfInUse = true
val internetReaderListener = yourInternetReaderListener

val config = InternetConnectionConfiguration(failIfInUse, internetReaderListener)
Terminal.getInstance().connectReader(
    reader,
    config,
    object : ReaderCallback {
        override fun onSuccess(reader: Reader) {
            // Placeholder for handling successful operation
        }

        override fun onFailure(e: TerminalException) {
            // Placeholder for handling exception
        }
    }
)

Pour perturber le moins possible l’expérience de connexion dans les environnements à plusieurs lecteurs, nous vous recommandons de définir la valeur failIfInUse sur true lors de la première tentative de connexion de votre application. Ensuite, permettez à vos utilisateurs de réessayer la connexion avec failIfInUse 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 mettre en place le rappel onDisconnect 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 du que le lecteur est déconnecté. 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.

class ReaderActivity : AppCompatActivity(), InternetReaderListener {
    // ...

    override fun onDisconnect(reason: DisconnectReason) {
        // 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 Shared Preferences (Android).
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.