Guide de migration du SDK Terminal V4

Si votre application utilise actuellement une version du SDK Terminal iOS antérieure à 4.0.0, vous devez apporter quelques modifications pour passer à une mise à niveau et accepter les paiements par carte physique dans le monde entier. Pour obtenir la liste détaillée des modifications apportées de la version 3.9.1 à la version 4.0.0, consultez le log 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 fonctionnant sous iOS 13 et versions ultérieures.

Mettez à jour les cartes bancaires après l’intégration de PaymentIntents

Si vous enregistrez un moyen de paiement après une PaymentIntent réussie en personne, vous devez apporter les modifications 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 bancaire.

• Vous devez également transmettre le paramètre allow_redisplaySCPCollectConfiguration sur la valeur toujours ou de façon limitée dans SCPCollectConfiguration. Transmettez la valeur toujours si vous souhaitez que la carte enregistrée du client lui soit présentée dans tous les tunnels de paiement futurs, et de façon limitée 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 informations de paiement après un paiement

Mise à jour des cartes enregistrées sans paiement grâce à 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.

En savoir plus sur l’épargne directe sans facturation.

Adapter votre utilisation de discoverReaders

• Nous avons ajouté une nouvelle valeur d’énumération, discoveringà SCPConnectionStatus pour représenter le moment où la détection 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 de détection simultanée de lecteurs. Auparavant, appeler discoverReadersSCPTerminal plusieurs fois mettait en file d’attente les opérations. Désormais, lorsqu’un nouveau discoverReadersSCPTerminal(im) est appelé alors qu’un existant est déjà en cours, le SDK annule l’opération en cours et renvoie une erreur SCPError CanceledDueToIntegrationError. 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 bloc d’achèvement discoverReaders à la fin de l’opération. Ce changement reflète le fait que la détection de ces types de lecteurs n’est pas une opération de longue durée.

• Nous avons corrigé un bug qui faisait fortement référence au SCPDiscoveryDelegate dans le SDK. Assurez-vous que votre application fait bien référence à votre délégué pour recevoir les événements de détection.

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 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 paramètre InternetReaderDelegate lui soit transmis, ce qui permet d’alerter votre système d’intégration des événements, y compris lorsqu’un lecteur se déconnecte.

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 plus de détails, 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 augmenter la résilience de votre intégration Terminal avec les lecteurs mobiles et Tap to Pay, nous avons activé la reconnexion automatique par défaut lorsqu’un lecteur se déconnecte de manière inattendue.

• We recommend displaying notifications in your app to inform the users about the reader status throughout the reconnection process. To handle reader reconnection methods, we removed the SCPReconnectionDelegate. Its responsibilities have been integrated into the respective ReaderDelegates. Use MobileReaderDelegate for mobile readers, and TapToPayReaderDelegate for Tap to Pay readers to handle reconnection events.

• 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 le paramètre setAutoReconnectOnUnexpectedDisconnect sur false.

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 plus de détails et d’extrait de code, consultez la page Tentative automatique de reconnexion.

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

• Pour recevoir une notification de la déconnexion d’un lecteur, nous avons consolidé les rappels de déconnexion du lecteur pour tous les types de lecteurs en supprimant le paramètre terminal:didReportUnexpectedReaderDisconnect: à partir de SCPTerminalDelegate. Utilisez reader:didDisconnect: dans le cadre des ReaderDelegates pour être recevoir une notification de la déconnexion d’un lecteur. Pour les lecteurs mobiles, le paramètre SCPDisconnectReason peut aider à identifier la raison de la déconnexion.

Lorsque la reconnexion automatique est activée, les deux méthodes lecteurDidFailReconnect: et reader:didDisconnect: sont appelées, si le SDK ne parvient pas à se reconnecter au lecteur et qu’il 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.

Mettez à 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 QR code, dont le processus de confirmation est asynchrone. De même, les paramètres 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 énumérées 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 la 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é dans 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 conformer aux 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.