Guide de migration du SDK Terminal V3

Si votre application utilise actuellement une version du SDK Terminal iOS antérieure à 3.0.0, vous devez 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 2.23.1 et la version 3.0.0, veuillez consulter le journal des modifications du SDK.

Mettre à jour votre version minimale prise en charge vers iOS 13 ou une version ultérieure

Nous mettons régulièrement à jour la version minimale prise en charge de nos SDK afin d’offrir la meilleure expérience à nos développeurs.

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

Mettre à jour votre utilisation de DiscoveryConfiguration en fonction de l’implémentation spécifique de DiscoveryConfiguration

Afin de permettre la configuration de différentes méthodes de détection, SCPDiscoveryConfiguration est désormais un protocole mis en œuvre par plusieurs types différents. Plutôt que d’avoir à fournir une DiscoveryMethod, vous avez désormais le choix entre différentes classes pour rechercher un type de lecteur spécifique :

Créez la configuration de détection appropriée pour la méthode de détection de votre choix à l’aide de la classe de génération fournie, puis fournissez-la à discoverReaders. Le générateur expose des paramètres pour les propriétés que chaque configuration prend en charge.

Mise à jour de votre utilisation de discoverReaders et de connectReader

• L’annulation de discoverReaders entraîne désormais l’appel du bloc de finalisation comportant une erreur avec le code SCPErrorCanceled, comme toutes les autres méthodes annulables.
• discoverReaders se termine désormais correctement lorsque connectReader est appelé. Si connectReader échoue, votre intégration doit effectuer un nouvel appel à discoverReaders pour reprendre la détection des lecteurs.
• Il n’est plus nécessaire que discoverReaders soit en cours d’exécution pour que connectReader fonctionne. Vous pouvez désormais appeler connectReader avec une instance de lecteur précédemment détectée ou réessayer de vous connecter sans redémarrer discoverReaders.

Mettre à jour votre implémentation ReconnectionDelegate

SCPReconnectionDelegate fournit désormais l’instance du lecteur reconnecté au lieu de l’instance de Terminal. Si vous avez implémenté ce protocole auparavant, vous devez remplacer terminal dans les noms de méthodes par reader.

Mise à jour de l’utilisation des classes de paramètres et de configuration pour utiliser les générateurs

Les classes d’entrée comme SCPCollectConfiguration et SCPPaymentIntentParameters sont désormais immuables, et des outils de création associés sont fournis pour les créer. Tous ces outils disposent d’une méthode de génération qui permet de valider les entrées et de créer la classe qu’ils génèrent.

• Dans Swift, build() renvoie des erreurs et doit être vérifié à cet égard.
• En Objective-C, vous fournissez un paramètre de sortie NSError ** pour recevoir l’erreur, le cas échéant.

let paymentParams = try PaymentIntentParametersBuilder(amount: 100, currency: "cad")
  .setCaptureMethod(.automatic)
  .build()

Éliminer toute dépendance à l’égard de SCPErrorBusy

SCPErrorBusy est supprimé. Dans le SDK 3.0.0 et les versions ultérieures, si vous appelez une méthode Terminal alors qu’une autre est encore en cours, les nouveaux appels sont désormais mis en file d’attente. Les commandes sont exécutées une fois toutes les commandes précédentes terminées. Si vous procédiez au suivi de l’état pour éviter les erreurs SCPErrorBusy ou mettiez vos propres commandes en file d’attente pour contourner SCPErrorBusy, vous pouvez désormais utiliser la file d’attente de commandes pour simplifier votre code. Si votre application s’appuyait sur SCPErrorBusy pour savoir si une commande était en cours d’exécution, vérifiez votre code pour voir si cela peut poser problème avec la mise en file d’attente d’un trop grand nombre de commandes.

Consulter la prise en charge des paiements hors ligne

La valeur de SCPPaymentIntent.stripeId est nulle pour les paiements hors ligne. Si votre intégration prend uniquement en charge les paiements en ligne, le stripeId sera toujours présent et aucune modification ne sera nécessaire hormis les vérifications pour confirmer la présence de l’ID. Veuillez consulter la section relative à l’encaissement des paiements par carte en mode hors ligne pour en savoir plus sur le traitement hors ligne des paiements.

Terminal.shared.createPaymentIntent(params) { intent, error in
  if let error = error {
    // Placeholder for handling exception
  }
  guard let intentId = intent.stripeId else {
    // PaymentIntent was created offline without an id. See intent.offlineDetails.
    // This is only expected when offline mode is enabled.
  }
}

Mise à jour de vos appels de processus pour confirmer

SCPTerminal.processPayment est renommé SCPTerminal.confirmPaymentIntent et SCPTerminal.processRefund est renommé SCPTerminal.confirmRefund. Les paramètres de ces méthodes n’ont pas changé, mais les types d’erreurs ont également été renommés SCPConfirmPaymentIntentError et SCPConfirmRefundError respectivement.

Mise à jour de votre readReusableCard par des SetupIntents

SCPTerminal.readReusableCard est supprimé. Les SetupIntents sont la méthode recommandée pour enregistrer les cartes sans débiter les clients. Les SetupIntents suivent un modèle similaire aux PaymentIntents : vous créez, collectez puis confirmez le SetupIntent dans le SDK. Pour en savoir plus, consultez la page sur l’enregistrement des cartes pour les paiements en ligne.