Guide de migration du SDK Terminal

Si votre application utilise actuellement une version du SDK Terminal pour iOS 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.9.1 et la version 4.0.0, veuillez consulter le journal des modifications du SDK.

Mettez à jour votre version minimale prise en charge vers iOS 14 ou une version plus récente

Nous mettons régulièrement à jour la version minimale prise en charge de nos SDK afin de rationaliser nos efforts de support aux développeurs.

Les versions 3.X existantes du SDK Terminal iOS continueront de prendre en charge les appareils exécutant iOS 13 et versions ultérieures.

Mettre à jour les cartes bancaires après l’intégration de 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 Terminal PaymentIntents, 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 SCPCollectConfiguration. 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 les 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 la collectSetupIntentPaymentMethod de SCPTerminal, 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, à SCPConnectionStatus 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, le fait d’appeler plusieurs fois discoverReaders avait pour effet de mettre les opérations en file d’attente. Désormais, lorsqu’une nouvelle opération discoverReaders est appelée alors qu’une opération existante est déjà en cours, le SDK annule cette dernière et renvoie une erreur SCPErrorCanceledDueToIntegrationError. 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 bloc d’achèvement 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.

• Nous avons corrigé un bogue qui gardait une référence forte vers SCPDiscoveryDelegate dans le SDK. Assurez-vous que votre application conserve une référence forte vers à votre délégué pour recevoir les événements de découverte.

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 précédentes (connectBluetoothReader, connectInternetReader, connectLocalMobileReader) dans connectReader. Le type de connexion exact est toujours déterminé par la configuration de connexion transmise.

• Pour les lecteurs mobiles et les lecteurs Tap to Pay, le paramètre ReaderDelegate a été supprimé de la méthode connectReader et déplacé à la place dans connectionConfig, remplaçant SCPReconnectionDelegate. À l’instar des autres types de lecteurs, le paramètre InternetConnectionConfiguration des lecteurs intelligents s’attend désormais à ce qu’un InternetReaderDelegate lui soit transmis, ce qui permet d’alerter votre intégration en cas d’événements tels que la déconnexion d’un lecteur.

Avant

// Call `connectBluetoothReader` with the selected reader and a connection config
// to register to a location as set by your app.
let connectionConfig: BluetoothConnectionConfiguration
do {
    connectionConfig = try BluetoothConnectionConfigurationBuilder(locationId: 
"{{LOCATION_ID}}").build()
} catch {
    // Handle the error building the connection configuration
    return
}
Terminal.shared.connectBluetoothReader(selectedReader, delegate: readerDelegate, connectionConfig: connectionConfig) { reader, error in
    if let reader = reader {
        print("Successfully connected to reader: \(reader)")
    } else if let error = error {
        print("connectBluetoothReader failed: \(error)")
    }
}

Après

// Call `connectReader` with the selected reader and a connection config
// to register to a location as set by your app.
let connectionConfig: BluetoothConnectionConfiguration
do {
    connectionConfig = try BluetoothConnectionConfigurationBuilder(delegate: yourMobileReaderDelegate, locationId: 
"{{LOCATION_ID}}")
    .build()
} catch {
    // Handle the error building the connection configuration
    return
}
Terminal.shared.connectReader(selectedReader, connectionConfig: connectionConfig) { reader, error in
    if let reader = reader {
        print("Successfully connected to reader: \(reader)")
    } else if let error = error {
        print("connectReader failed: \(error)")
    }
}

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 lorsqu’un 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, nous avons supprimé le SCPReconnectionDelegate. Ses responsabilités ont été intégrées dans les ReaderDelegate respectifs. Utilisez MobileReaderDelegate pour les lecteurs mobiles et TapToPayReaderDelegate pour les lecteurs Tap to Pay afin de gérer les événements de reconnexion.

• 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 à setAutoReconnectOnUnexpectedDisconnect.

Avant

import StripeTerminal

extension ReaderViewController: ReconnectionDelegate {
    // MARK: ReconnectionDelegate
    func terminal(_ terminal: Terminal, didStartReaderReconnect cancelable: Cancelable) {
        // 1. Notified at the start of a reconnection attempt
        // Use cancelable to stop reconnection at any time
    }

    func terminalDidSucceedReaderReconnect(_ terminal: Terminal) {
        // 2. Notified when reader reconnection succeeds
        // App is now connected
    }
    func terminalDidFailReaderReconnect(_ terminal: Terminal) {
        // 3. Notified when reader reconnection fails
        // App is now disconnected
    }
}

Après

import StripeTerminal

extension ReaderViewController: MobileReaderDelegate {
    // MARK: MobileReaderDelegate

    func reader(_ reader: Reader, didStartReconnect cancelable: Cancelable, disconnectReason: DisconnectReason) {
        // 1. Notified at the start of a reconnection attempt
        // Use cancelable to stop reconnection at any time
    }

    func readerDidSucceedReconnect(_ reader: Reader) {
        // 2. Notified when reader reconnection succeeds
        // App is now connected
    }
    func readerDidFailReconnect(_ reader: Reader) {
        // 3. Notified when reader reconnection fails
        // App is now disconnected
    }
}

Pour en savoir plus et obtenir des extraits de code, 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 terminal:didReportUnexpectedReaderDisconnect: du SCPTerminalDelegate. Utilisez reader:didDisconnect: dans le cadre de ReaderDelegates pour être informé de la déconnexion d’un lecteur. Pour les lecteurs mobiles, le paramètre SCPDisconnectReason peut aider à identifier le motif de la déconnexion.

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

Avant

import StripeTerminal

class ReaderViewController: UIViewController, TerminalDelegate {
    override func viewDidLoad() {
        super.viewDidLoad()
        Terminal.shared.delegate = self
    }

    // ...
    // MARK: TerminalDelegate
    func terminal(_ terminal: Terminal, didReportUnexpectedReaderDisconnect reader: Reader) {
        // Consider displaying a UI to notify the user and start rediscovering readers
    }
}

Après

import StripeTerminal

class ReaderViewController: UIViewController, MobileReaderDelegate {
    override func viewDidLoad() {
        super.viewDidLoad()
        // Set the reader delegate when connecting to a reader
    }

    // ...



    func reader(_ reader: Reader, didDisconnect 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 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, confirmSetupIntent et confirmRefund peuvent désormais être annulés.
• Nous avons amélioré la sécurité des types et la cohérence entre les SDK mobiles en mettant à jour la façon dont les paymentMethodTypes sont spécifiés dans SCPPaymentIntentParameters et SCPSetupIntentParameters. Auparavant, ce paramètre était représenté par un tableau de chaînes (par exemple, [“card_present”]). Il utilise désormais les valeurs d’énumération de SCPPaymentMethodType.
• 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 .collectPaymentMethod avant d’annuler le PaymentIntent.
• La valeur null peut désormais être attribuée à SCPSetupIntent.stripeId, par cohérence avec SCPPaymentIntent.stripeId. Bien que la valeur stripeId soit toujours présente, assurez-vous que votre code gère en toute sécurité le cas où SCPSetupIntent.stripeId pourrait être null afin d’éviter une erreur de compilation.

Adapter l’utilisation pour le renommage et la fin de prise en charge

• BluetoothReaderDelegate a été renommé en MobileReaderDelegate.
• Dans SCPReaderSoftwareUpdate, nous avons renommé SCPUpdateTimeEstimate en SCPUpdateDurationEstimate et estimatedUpdateTime en durationEstimate pour mieux représenter leur intention.
• Dans SCPOfflineDetails, qui représente les informations de paiement disponibles lorsqu’un paiement est créé ou confirmé hors ligne, nous avons remplacé le nom du paramètre collectedAt correspondant à l’heure à laquelle le paiement hors ligne a eu lieu parstoredAt, afin de nous aligner sur les conventions de dénomination du SDK Terminal pour Android.
• Nous avons renommé « local mobile » et « apple built in » en « Tap To Pay » dans tous les noms de fonctions et codes d’erreur du SDK.