# Guide de migration du SDK Terminal V4 Découvrez comment migrer vers la version 4.0.0 du SDK de Stripe Terminal. Visit our [Design an integration](https://docs.stripe.com/terminal/designing-integration.md) page to learn how to get started. Les SDK Stripe Terminal pour iOS et Android ont été mis à jour avec un certain nombre de changements majeurs au niveau des API et du comportement, dont certains nécessitent que vous mettiez à jour votre intégration avec le SDK Stripe Terminal. Nous apportons régulièrement des modifications aux mises à jour de versions majeures susceptibles d’affecter le fonctionnement ou le comportement de votre intégration, afin d’améliorer la cohérence entre nos SDK et de simplifier la logique et l’intégration de votre application. Ce guide vous présente les dernières modifications pour vous aider à mettre à niveau votre intégration. Before you migrate, review the [Terminal SDK versioning and support policy](https://docs.stripe.com/terminal/references/sdk-versioning.md) to understand supported SDK versions, patch support timelines, and end-of-life enforcement. ## Migrer vers la version 4.0.0 Voici les éléments à retenir concernant les SDK de Stripe Terminal 4.0.0 pour iOS et Android : - [Enregistrer les détails de paiement après le paiement à l’échelle mondiale](https://docs.stripe.com/terminal/features/saving-payment-details/save-after-payment.md) - Les utilisateurs peuvent désormais enregistrer leurs informations de paiement après avoir effectué un paiement en dehors des États-Unis en mettant à jour le processus de collecte du consentement du client pour l’enregistrement des informations de paiement sur les appareils des points de vente. - Prise en charge des paiements des commandes passées par [correspondance et par téléphone](https://docs.stripe.com/terminal/features/mail-telephone-orders/overview.md) (MOTO) sur lecteurs intelligents (Version bêta) - Cette fonctionnalité est en version bêta. Pour faire une demande d’accès, envoyez un e-mail à [stripe-terminal-betas@stripe.com](mailto:stripe-terminal-betas@stripe.com). - Mises à jour vers la version minimale des plateformes iOS prises en charge - Active, par défaut, la reconnexion automatique du [lecteur en cas de déconnexion inattendue](https://docs.stripe.com/terminal/payments/connect-reader.md?terminal-sdk-platform=ios&reader-type=tap-to-pay#automatically-attempt-reconnection) pour les lecteurs mobiles et Tap to Pay - Consolidation des fonctionnalités de connexion des lecteurs et des rappels de déconnexion pour tous les types de lecteurs # Android Si votre application utilise actuellement une version du SDK Terminal pour Android antérieure à 4.0.0, vous devrez procéder à quelques modifications pour effectuer la mise à niveau et accepter les paiements par carte physique dans le monde entier. Pour obtenir une liste détaillée des modifications apportées entre la version 3.10.0 et la version 4.0.0, veuillez consulter le [log des modifications du SDK](https://github.com/stripe/stripe-terminal-android/blob/master/CHANGELOG.md). ## Mettez à jour vos cartes bancaires après l’intégration PaymentIntents Si vous [enregistrez un moyen de paiement après une PaymentIntent réussie en personne](https://docs.stripe.com/terminal/features/saving-payment-details/save-after-payment.md), vous devez apporter les modifications suivantes à votre intégration : - Lors de la création de PaymentIntents Terminal, transmettez le paramètre [setup_future_utilisation](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-payment-intent/index.html#-745150436%2FProperties%2F-1219334616), qui informe Stripe que vous souhaitez effectuer des paiements futurs avec la même carte. - Vous devez également transmettre le paramètre [allow_redisplay](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-collect-configuration/index.html#-74877977%2FProperties%2F-1219334616) sur la valeur `TOUJOURS` ou `LIMITÉ` dans `CollectConfiguration`. Transmettez la valeur `TOUJOURS` si vous souhaitez lui présenter la carte enregistrée du client dans tous les flux des paiements futurs, et `LIMITÉ` s’il ne peut l’utiliser que dans le contexte de l’utilisation initialement visée, comme un abonnement. En savoir plus sur l’[enregistrement des cartes après un paiement](https://docs.stripe.com/terminal/features/saving-payment-details/save-after-payment.md) ## Mettez à jour vos cartes d’épargne sans paiement grâce à l’intégration SetupIntents. Pour garantir une intégration cohérente entre les SetupIntents et les PaymentIntents, ainsi qu’entre les transactions en personne et en ligne, nous avons supprimé, dans la [`collectSetupIntentPaymentMethod`](https://stripe.dev/stripe-terminal-android/core/com.stripe.stripeterminal/-terminal/index.html#915185703%2FFunctions%2F-1814817128) de `Terminal`, le paramètre `customerConsentCollected` qui était auparavant requis pour toutes les transactions SetupIntent, et nous l’avons remplacé par le paramètre `allowRedisplay`. En savoir plus sur l’[épargne directe sans facturation](https://docs.stripe.com/terminal/features/saving-payment-details/save-directly.md). ## Adapter votre utilisation de discoverReaders - Nous avons ajouté une nouvelle valeur d’énumération, `DISCOVERING`, à [ConnectionStatus](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-connection-status/index.html) pour indiquer lorsque la détection du lecteur est en cours. Assurez-vous que votre intégration peut gérer ce nouvel état et fournir les informations pertinentes à vos clients. - Nous avons amélioré la gestion des opérations de détection de plusieurs lecteurs simultanés. Auparavant, appeler [Terminal::discoverReaders](https://stripe.dev/stripe-terminal-android/core/com.stripe.stripeterminal/-terminal/index.html#-307737612%2FFunctions%2F-1814817128) plusieurs fois mettait en file d’attente les opérations, ce qui, selon nous, n’était pas souhaitable. Désormais, lorsqu’un nouveau `Terminal::discoverReaders` est appelé alors qu’un existant est déjà en cours, le SDK annule l’opération en cours et renvoie une erreur [CANCELED_DUE_TO_INTEGRATION_ERROR](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-terminal-error-code/-c-a-n-c-e-l-e-d_-d-u-e_-t-o_-i-n-t-e-g-r-a-t-i-o-n_-e-r-r-o-r/index.html). La nouvelle opération discoverReaders démarre alors immédiatement. - La détection de lecteurs intelligents et de lecteurs Tap to Pay appelle désormais le rappel de fin d’exécution `Terminal::discoverReaders` à la fin de l’opération. Ce changement reflète le fait que la détection de lecteurs pour ces types de lecteurs n’est pas une opération de longue durée. ## Mettez à jour l’utilisation des connexions de votre lecteur - Pour garantir un modèle d’intégration cohérent entre la détection et la connexion du lecteur, nous avons consolidé toutes les méthodes de connexion du lecteur (`connectBluetoothReader`, `connectUsbReader`, `connectInternetReader`, `connectLocalMobileReader`, `connectHandoffReader`) dans [Terminal::connectReader](https://stripe.dev/stripe-terminal-android/core/com.stripe.stripeterminal/-terminal/index.html#1656325082%2FFunctions%2F-1814817128). Le type de connexion spécifique est toujours déterminé par la configuration de connexion fournie. - Pour les lecteurs mobiles, le paramètre `readerListener` a été supprimé des anciennes méthodes `connectBluetoothReader` et `connectUsbReader`, et déplacé dans l’objet `ConnectionConfiguration` respectif, remplaçant `ReaderReconnectionListener`. Pour les lecteurs Tap to Pay, l’objet `TapToPayConnectionConfiguration` intègre désormais un paramètre `TapToPayReaderListener`, qui remplace `ReaderReconnectionListener`. - Comme pour les autres types de lecteurs, la `configuration InternetConnectionConfiguration` des lecteurs intelligents prévoit désormais également la transmission d’un [`InternetReaderListener`](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.callable/-internet-reader-listener/index.html), qui alerte votre intégration des événements, y compris les déconnexions du lecteur. - Pour les [applications sur appareils](https://docs.stripe.com/terminal/features/apps-on-devices/overview.md#pos-stripe-device) en mode transfert, [`HandoffReaderListener`](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.callable/-handoff-reader-listener/index.html) a été supprimé de l’ancienne méthode `connectHandoffReader` en tant que paramètre et déplacé dans l’objet `HandoffConnectionConfiguration`. | Type de lecteur | Configuration de la connexion | Écouteur de lecteur | | ------------------------------ | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Lecteur mobile | `BluetoothConnectionConfiguration` | [MobileReaderListener](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.callable/-mobile-reader-listener/index.html) | | Lecteur intelligent | `InternetConnectionConfiguration` | [InternetReaderListener](https://stripe.dev/stripe-terminal-android/com.stripe.stripeterminal.external.callable/-internet-reader-listener/index.html) | | Tap to Pay | `TapToPayConnectionConfiguration` | [TapToPayReaderListener](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.callable/-tap-to-pay-reader-listener/index.html) | | Applications sur des appareils | `HandoffConnectionConfiguration` | [HandoffReaderListener](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.callable/-handoff-reader-listener/index.html) | ### Avant #### Kotlin ```kotlin val connectionConfig = ConnectionConfiguration.BluetoothConnectionConfiguration( ""{{LOCATION_ID}}"" ) Terminal.getInstance().connectBluetoothReader( selectedReader, connectionConfig, readerListener, object : ReaderCallback { override fun onSuccess(reader: Reader) { // Placeholder for handling successful operation } override fun onFailure(e: TerminalException) { // Placeholder for handling exception } } ) ``` ### Après #### Kotlin ```kotlin // Implement your MobileReaderListener val mobileReaderListener = yourMobileReaderListener val autoReconnectOnUnexpectedDisconnect = true val connectionConfig = BluetoothConnectionConfiguration( ""{{LOCATION_ID}}"", autoReconnectOnUnexpectedDisconnect, mobileReaderListener ) Terminal.getInstance().connectReader( selectedReader, connectionConfig, object : ReaderCallback { override fun onSuccess(reader: Reader) { // Placeholder for handling successful operation } override fun onFailure(e: TerminalException) { // Placeholder for handling exception } } ) ``` Pour en savoir plus, consultez la section [connexion à un lecteur](https://docs.stripe.com/terminal/payments/connect-reader.md?terminal-sdk-platform=android&reader-type=bluetooth#connect-reader) ## La reconnexion automatique est désormais activée par défaut pour les lecteurs mobiles et Tap to Pay - Pour augmenter la résilience de votre intégration Terminal avec les lecteurs mobiles et Tap to Pay, nous avons activé la [reconnexion automatique](https://docs.stripe.com/terminal/payments/connect-reader.md?terminal-sdk-platform=android&reader-type=bluetooth#handle-disconnects) par défaut lorsque le lecteur se déconnecte de manière inattendue. - Nous vous recommandons d’afficher des notifications dans votre application pour informer les utilisateurs de l’état du lecteur tout au long du processus de reconnexion. Pour gérer les méthodes de reconnexion des lecteurs, le `ReaderReconnectionListener` a été hérité par les ReaderListeners respectifs. Utilisez `MobileReaderListener` pour les lecteurs mobiles et `TapToPayReaderListener` pour les lecteurs Tap to Pay afin de gérer les événements de reconnexion. - Nous avons supprimé le paramètre `ReaderReconnectionListener` des configurations de connexion : `LocalMobileConnectionConfiguration`, `BluetoothConnectionConfiguration` et `UsbConnectionConfiguration`, et l’avons remplacé par le paramètre `ReaderListener` approprié. Si vous avez implémenté votre propre logique de reconnexion du lecteur et que vous souhaitez conserver ce comportement, vous pouvez désactiver la reconnexion automatique en définissant [autoReconnectOnUnexpectedDisconnect](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-connection-configuration/-bluetooth-connection-configuration/index.html#1748469061%2FProperties%2F-1219334616) sur la valeur `false`. ### Avant #### Kotlin ```kotlin class CustomReaderReconnectionListener : ReaderReconnectionListener { override fun onReaderReconnectStarted(reader: Reader, cancelReconnect: Cancelable, reason: DisconnectReason) { // 1. Notified at the start of a reconnection attempt // Use cancelable to stop reconnection at any time } override fun onReaderReconnectSucceeded(reader: Reader) { // 2. Notified when reader reconnection succeeds // App is now connected } override fun onReaderReconnectFailed(reader: Reader) { // 3. Notified when reader reconnection fails // App is now disconnected } } ``` ### Après #### Kotlin ```kotlin class CustomMobileReaderListener : MobileReaderListener { // ... override fun onReaderReconnectStarted(reader: Reader, cancelReconnect: Cancelable, reason: DisconnectReason) { // 1. Notified at the start of a reconnection attempt // Use cancelable to stop reconnection at any time } override fun onReaderReconnectSucceeded(reader: Reader) { // 2. Notified when reader reconnection succeeds // App is now connected } override fun onReaderReconnectFailed(reader: Reader) { // 3. Notified when reader reconnection fails // App is now disconnected } // ... } ``` Pour en savoir plus, consultez la page [Tentative automatique de reconnexion](https://docs.stripe.com/terminal/payments/connect-reader.md?terminal-sdk-platform=android&reader-type=tap-to-pay#automatically-attempt-reconnection). ## Mettez à jour la gestion de la déconnexion des lecteurs - Pour recevoir une notification lorsqu’un lecteur se déconnecte, nous avons regroupé les rappels de déconnexion des lecteurs pour tous les types de lecteurs en supprimant `TerminalListener::onUnexpectedReaderDisconnect`. À l’avenir, implémentez le paramètre `onDisconnect` sur l’un des écouteurs suivants pour recevoir une notification des déconnexions des lecteurs correspondants : `InternetReaderListener`, `MobileReaderListener`, `TapToPayReaderListener`, ou `HandoffReaderListener`. Pour les lecteurs mobiles, le paramètre [`DisconnectReason`](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-disconnect-reason/index.html) peut aider à identifier la raison de la déconnexion. Lorsque la reconnexion automatique est activée, les méthodes `onDisconnect` et [`on ReaderReconnectFailed`](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.callable/-reader-reconnection-listener/on-reader-reconnect-failed.html) sont appelées si le SDK ne parvient pas à se reconnecter au lecteur et qu’il se déconnecte. ### Avant #### Kotlin ```kotlin class ReaderActivity : AppCompatActivity(), TerminalListener { // ... Terminal.getInstance().setTerminalListener(this) // ... override fun onUnexpectedReaderDisconnect(reader: Reader) { // Consider displaying a UI to notify the user and start rediscovering readers } // ... } ``` ### Après #### Kotlin ```kotlin class ReaderActivity : AppCompatActivity(), MobileReaderListener { // ... override fun onDisconnect(reason: DisconnectReason) { // Consider displaying a UI to notify the user and start rediscovering readers } // ... } ``` Pour plus de détails, consultez la page [gestion manuelle des déconnexions](https://docs.stripe.com/terminal/payments/connect-reader.md?terminal-sdk-platform=android&reader-type=tap-to-pay#handle-the-disconnect-manually). ## Mettez à jour votre intégration de l’acceptation des paiements - Vous pouvez désormais annuler le paramètre `Terminal::confirmPaymentIntent` en utilisant l’objet `Cancelable` renvoyé. Ceci est utile pour les paiements par QR code, dont le processus de confirmation est asynchrone. De même, les paramètres `Terminal::confirmSetupIntent` et `Terminal::confirmRefund` peuvent désormais être annulés. - Pour améliorer le flux d’annulation des PaymentIntents et des SetupIntents, l’appel à `Terminal::cancelPaymentIntent` ou `Terminal::cancelSetupIntent` annule également tout traitement de paiement en cours. Il n’est plus nécessaire d’annuler séparément les opérations de paiement telles que `Terminal::collectPaymentMethod` avant d’annuler le PaymentIntent. - La valeur null peut désormais être attribuée à `SetupIntent.id`, par cohérence avec `PaymentIntent.id`. Bien que la valeur `id`soit toujours présente, assurez-vous que votre code gère en toute sécurité le cas où `SetupIntent.id` pourrait être `null` afin d’éviter une erreur de compilation. ## Mettez à jour la gestion des erreurs - Nous avons déplacé `TerminalException.TerminalErrorCode` vers une énumération autonome, `TerminalErrorCode`. Veillez à Mettez à jour les déclarations d’importation et la définition du code d’erreur de Terminal pour maintenir la fonctionnalité. - Nous avons ajouté un nouveau code d’erreur `TerminalErrorCode.GENERIC_READER_ERROR`, qui peut se produire lorsque le SDK n’est pas à jour et ne peut pas reconnaître l’erreur renvoyée par le lecteur intelligent. Pour rectifier cette erreur, mettez à jour votre SDK Terminal. - Pour Tap to Pay sur Android, `Terminal::collectPaymentMethod` et `Terminal::collectSetupIntentPaymentMethod` expirent désormais au bout de 60 secondes pour les transactions Tap to Pay sur Android. Une `TerminalException` est levée avec le code d’erreur `TerminalErrorCode.CARD_READ_TIMED_OUT`. - Pour Tap to Pay sur Android, lorsque la collecte du code PIN est demandée pour un paiement, une `TerminalException` est levée avec le code d’erreur `FEATURE_NOT_ENABLED_ON_ACCOUNT` au lieu de `DECLINED_BY_STRIPE_API`avec une erreur `ONLINE_OR_OFFLINE_PIN_REQUIRED` `ApiError`. ## Mise à jour de l’utilisation pour le renommage et la refactorisation - `ReaderListener` a été renommé en [`MobileReaderListener`](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.callable/-mobile-reader-listener/index.html). - Nous avons renommé le paramètre `allowedPaymentMethodTypes` en `paymentMethodTypes` dans les constructeurs `PaymentIntentParameters.Builder` et `SetupIntentParameter.Builder`. - Dans `ReaderSoftwareUpdate`, nous avons renommé `UpdateTimeEstimate` en `UpdateDurationEstimate` et `estimatedUpdateTime`en `durationEstimate` afin de mieux refléter leur intention. - Nous avons converti les références `java.util.Date` en horodatages en millisecondes pour les champs suivants : `ReaderSoftwareUpdate::requiredAt`, `OfflineDetails::storedAt` et `OfflineSetupIntentDetails::storedAt`. Assurez-vous que votre application interprète correctement ces horodatages. - Les champs de l’objet `Location` ne sont plus modifiables. ## Mettez à jour l’intégration de Tap to Pay sur Android - Les coordonnées Maven pour la fonctionnalité Tap to Pay sur Android ont changé pour devenir `com.stripe:stripeterminal-taptopay:4.0.0`. Mettez à jour vos dépendances pour pointer vers le nouveau nom de l’artefact. L’ancien ne sera plus mis à jour. - Nous avons renommé tous les noms de fonctions et de champs de `LocalMobile` en `TapToPay`. Par exemple, le champ `LocalMobileDiscoveryConfiguration` a été renommé en `TapToPayDiscoveryConfiguration`. - `TapToPayConnectionConfiguration` prend désormais en charge un paramètre `TapToPayReaderListener`. Cet écouteur hérite des événements de `ReaderReconnectionListener` et de `ReaderDisconnectionListener`, fournissant ainsi un mécanisme unifié pour la gestion des événements du lecteur. - Nous avons renommé le processus d’application en arrière-plan utilisé pour collecter les transactions Tap to Pay afin d’utiliser l’identifiant de votre application, suivi du suffixe `:stripetaptopay`.