Guide de migration du SDK Terminal

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 avec carte présente 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 journal des modifications du SDK.

Mettre à jour vos cartes bancaires après l’intégration PaymentIntents

Si vous enregistrez un moyen de paiement après un PaymentIntent réussi en personne, vous devez mettre les mises à jour suivantes à votre intégration :

• Lors de la création de PaymentIntents Terminal, transmettez le paramètre setup_future_usage, qui informe Stripe que vous souhaitez effectuer des paiements futurs avec la même carte.
• Vous devez également transmettre allow_redisplay avec la valeur ALWAYS ou LIMITED dans CollectConfiguration. Transmettez ALWAYS si vous voulez que la carte bancaire enregistrée du client lui soit présentée dans tous les futurs flux de paiement, et LIMITED si elle ne peut être utilisée que dans le contexte de l’utilisation initialement prévue, comme un abonnement.

Découvrez comment enregistrer des cartes après un paiement.

Mettre à jour vos cartes bancaires sans paiement avec l’intégration de 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 collectSetupIntentPaymentMethod 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.

Découvrez comment enregistrer directement les informations de paiement sans débiter le client.

Adapter votre utilisation de discoverReaders

• Nous avons ajouté une nouvelle valeur enum, DISCOVERING, à ConnectionStatus pour représenter le moment où la découverte du lecteur est en cours. Assurez-vous que votre intégration peut gérer ce nouvel état et fournir des informations pertinentes à vos clients.

• Nous avons amélioré la gestion de plusieurs opérations simultanées de découverte de lecteurs. Auparavant, appeler Terminal::discoverReaders plusieurs fois avait pour effet de mettre les opérations en file d’attente, ce qui, nous l’avons appris, n’était pas souhaitable. Désormais, lorsqu’un nouveau Terminal::discoverReaders est appelé alors qu’une opération existante est déjà en cours, le SDK annule cette dernière et renvoie une erreur CANCELED_DUE_TO_INTEGRATION_ERROR. La nouvelle opération discoverReaders démarre alors immédiatement.

• La découverte 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écouverte de lecteurs pour ces types de lecteurs n’est pas une opération de longue durée.

Mettre à jour l’utilisation des connexions de votre lecteur

• Afin de garantir un modèle d’intégration cohérent pour la découverte et la connexion des lecteurs, nous avons consolidé toutes les méthodes de connexion des lecteurs (connectBluetoothReader, connectUsbReader, connectInternetReader, connectLocalMobileReader, connectHandoffReader) dans Terminal::connectReader. 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.
• À l’instar des autres types de lecteurs, le paramètre InternetConnectionConfiguration des lecteurs intelligents s’attend désormais à ce qu’un InternetReaderListener lui soit transmis, ce qui permet d’alerter votre intégration en cas d’événements tels que la déconnexion d’un lecteur.
• Pour les applications sur des appareils en mode transfert, HandoffReaderListener a été supprimé de l’ancienne méthode connectHandoffReader en tant que paramètre, et déplacé dans l’objet HandoffConnectionConfiguration.

Avant

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

// 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 notre documentation sur la connexion à un lecteur.

La reconnexion automatique est désormais activée par défaut pour les lecteurs mobiles et Tap to Pay

• Pour accroître la résilience de l’intégration de votre terminal avec les lecteurs mobiles et Tap to Pay, nous avons activé la reconnexion automatique par défaut lorsque le lecteur se déconnecte inopinément.
• 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 mis en œuvre votre propre logique de reconnexion des lecteurs et que vous souhaitez conserver ce comportement, vous pouvez désactiver la reconnexion automatique en attribuant la valeur false à autoReconnectOnUnexpectedDisconnect.

Avant

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

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 notre documentation sur la tentative de reconnexion automatique.

Mettre à jour la gestion de la déconnexion des lecteurs

• Pour être informé de la déconnexion d’un lecteur, nous avons consolidé les rappels de déconnexion de tous les types de lecteurs en supprimant TerminalListener::onUnexpectedReaderDisconnect. À l’avenir, implémentez onDisconnect sur l’un des lecteurs suivants pour être informé de la déconnexion du lecteur correspondant : InternetReaderListener, MobileReaderListener, TapToPayReaderListener ou HandoffReaderListener. Pour les lecteurs mobiles, DisconnectReason peut aider à identifier la raison de la déconnexion.

Lorsque la reconnexion automatique est activée, les méthodes onDisconnect et onReaderReconnectFailed sont appelées si le SDK ne parvient pas à se reconnecter au lecteur et que celui-ci se déconnecte.

Avant

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

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

    override fun onDisconnect(reason: DisconnectReason) {
        // Consider displaying a UI to notify the user and start rediscovering readers
    }

    // ...
}

Pour en savoir plus, consultez notre documentation sur la gestion manuelle des déconnexions.

Mettre à jour votre intégration de l’acceptation des paiements

• Vous pouvez désormais annuler Terminal::confirmPaymentIntent en utilisant l’objet Cancelable renvoyé. Ceci est utile pour les paiements par code QR, dont le processus de confirmation est asynchrone. De même, 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 de 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.

Mettre à jour la gestion des erreurs

• Nous avons déplacé TerminalException.TerminalErrorCode vers une énumération autonome, TerminalErrorCode. Veillez à mettre à 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 Terminal 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 ApiError ONLINE_OR_OFFLINE_PIN_REQUIRED.

Adapter l’utilisation pour le renommage et le remaniement du code

• ReaderListener a été renommé en MobileReaderListener.
• 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 pour mieux représenter 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.

Mettre à 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, LocalMobileDiscoveryConfiguration est devenu TapToPayDiscoveryConfiguration.
• TapToPayConnectionConfiguration prend désormais un paramètre TapToPayReaderListener. Cet écouteur hérite des événements de ReaderReconnectionListener et de ReaderDisconnectionListener, ce qui permet de disposer d’un mécanisme unifié pour gérer les événements liés aux lecteurs.
• Nous avons renommé le processus d’application en arrière-plan utilisé pour la collecte des transactions Tap to Pay afin d’utiliser l’identifiant de votre application, avec le suffixe :stripetaptopay.