# Configurer votre intégration Configurez un SDK Stripe Terminal ou une intégration pilotée par serveur pour accepter les paiements par TPE. # iOS Si vous recherchez un document qui décrit plus en détail les méthodes, objets et erreurs disponibles, consultez notre [documentation complète sur les SDK](https://stripe.dev/stripe-terminal-ios). Pour démarrer avec le SDK iOS, suivez ces quatre étapes : 1. [Installer le SDK](https://docs.stripe.com/terminal/payments/setup-integration.md#install) dans votre application. 2. [Configurer](https://docs.stripe.com/terminal/payments/setup-integration.md#configure) votre application. 3. [Configurer l’endpoint du token de connexion](https://docs.stripe.com/terminal/payments/setup-integration.md#connection-token) dans votre application et votre back-end. 4. [Initialiser le SDK](https://docs.stripe.com/terminal/payments/setup-integration.md#initialize) dans votre application. ## Installer le SDK [Côté client] Le SDK Stripe Terminal iOS est compatible avec les applications qui : - Prennent en charge iOS 13 et les versions ultérieures - Sont installés avec CocoaPods, Swift Package Manager, ou en intégrant manuellement le framework #### Cocoapods 1. Si vous ne l’avez pas encore fait, installez la version la plus récente de [CocoaPods](https://guides.cocoapods.org/using/getting-started.html). 2. Si vous n’avez pas de fichier [Podfile](https://guides.cocoapods.org/syntax/podfile.html), exécutez la commande suivante pour en créer un : ```bash pod init ``` 3. Ajoutez cette ligne à votre Podfile : ```podfile pod 'StripeTerminal', '~> 5.0' ``` 4. Exécutez la commande suivante : ```bash pod install ``` 5. À partir de maintenant, utilisez le fichier `.xcworkspace` au lieu de `.xcodeproj` pour ouvrir votre projet dans Xcode. #### Swift Package Manager 1. Dans Xcode, sélectionnez **Fichier** > **Ajouter des packages…** dans la barre de menus. 2. Saisissez l’URL Github du SDK iOS Terminal Stripe : `https://github.com/stripe/stripe-terminal-ios` 3. Saisissez la version SDK que vous souhaitez installer dans votre projet. La valeur par défaut « Up to Next Major » vous aidera à installer les mises à jour de sécurité et de fonctionnalité sans entraîner de changements brutaux et imprévus. #### Manuel 1. Visitez le référentiel de Stripe Terminal iOS sur GitHub et accédez à la [dernière version en date](https://github.com/stripe/stripe-terminal-ios/releases). 2. Téléchargez le fichier `StripeTerminal.xcframework.zip` joint à la version GitHub. 3. Décompressez le fichier, plus glissez-déposez le XCFramework dans votre projet Xcode. 4. S’il n’est pas possible de charger les symboles de l’infrastructure logicielle, rendez-vous dans le volet « General » (Général) de votre cible et trouvez la liste déroulante « Frameworks, Libraries, and Embedded Content » (Infrastructures logicielles, bibliothèques et contenus intégrés). Dans `StripeTerminal.xcframework`, remplacez « Do Not Embed » (Ne pas intégrer) par « Embed and Sign » (Intégrer et signer). > Pour plus de détails sur la dernière version du SDK et les versions précédentes, consultez la page [Releases](https://github.com/stripe/stripe-terminal-ios/releases) sur GitHub. Pour recevoir des notifications lorsqu’une nouvelle version est publiée, [surveillez les versions du dépôt](https://docs.github.com/en/github/managing-subscriptions-and-notifications-on-github/configuring-notifications#configuring-your-watch-settings-for-an-individual-repository) ou [abonnez-vous au flux RSS GitHub Releases](https://github.com/stripe/stripe-terminal-ios/releases.atom). > > Pour en savoir plus sur la migration depuis des versions antérieures du SDK iOS, consultez [le guide de migration du SDK Stripe Terminal](https://docs.stripe.com/terminal/references/sdk-migration-guide.md). ## Configurer votre application [Côté client] Pour que votre application puisse fonctionner avec le SDK Stripe Terminal, apportez quelques modifications à votre fichier **Info.plist** dans Xcode. 1. Activez les services de localisation avec la paire clé-valeur suivante. | Confidentialité – Description de l’utilisation de l’emplacement, le cas échéant | | ------------------------------------------------------------------------------- | | **Clé** | [NSLocationWhenInUseUsageDescription](https://developer.apple.com/documentation/bundleresources/information_property_list/nslocationwheninuseusagedescription) | | **Valeur** | **L’accès à l’emplacement est indispensable pour accepter des paiements.** | Afin de réduire les risques de fraude associés aux paiements et de limiter le nombre de litiges, Stripe a besoin de connaître le lieu où se déroulent les paiements. Si le SDK ne peut déterminer l’emplacement de l’appareil iOS, les paiements sont désactivés jusqu’à ce que l’accès à l’emplacement soit rétabli. 2. Assurez-vous que votre application fonctionne en arrière-plan et reste connectée aux lecteurs Bluetooth. | Modes d’arrière-plan requis pour les lecteurs Bluetooth | | ------------------------------------------------------- | | **Clé** | [UIBackgroundModes](https://developer.apple.com/documentation/bundleresources/information_property_list/uibackgroundmodes) | | **Valeur** | **bluetooth-central** (Utilise les accessoires Bluetooth LE) | La configuration du mode d’arrière-plan [bluetooth-central](https://developer.apple.com/library/archive/documentation/NetworkingInternetWeb/Conceptual/CoreBluetooth_concepts/CoreBluetoothBackgroundProcessingForIOSApps/PerformingTasksWhileYourAppIsInTheBackground.html#//apple_ref/doc/uid/TP40013257-CH7-SW6) permet au lecteur de rester en mode veille lorsque votre application est exécutée en arrière-plan, ou lorsque l’appareil iOS est verrouillé. Sans cette valeur, la mise en veille échoue. Lorsque votre application est exécutée en arrière-plan, le lecteur est susceptible de s’éteindre automatiquement afin d’économiser de l’énergie. 3. Autorisez votre application à afficher une boîte de dialogue d’autorisation Bluetooth. L’App Store exige l’intégration de cette option, même si votre application ne prend pas en charge la connexion aux lecteurs Bluetooth. | Confidentialité – Description de l’utilisation systématique du Bluetooth | | ------------------------------------------------------------------------ | | **Clé** | [NSBluetoothAlwaysUsageDescription](https://developer.apple.com/documentation/bundleresources/information_property_list/NSBluetoothAlwaysUsageDescription) | | **Valeur** | **Cette application utilise le Bluetooth pour se connecter aux lecteurs de cartes bancaires pris en charge.** | iOS 13 propose désormais des autorisations plus spécifiques concernant l’utilisation de périphériques Bluetooth par une application. Les applications associées à Core Bluetooth doivent inclure cette clé dans leur fichier Info.plist afin d’éviter que l’application ne plante lors de son premier lancement. 4. Passer les contrôles de validation de l’application lorsque vous la soumettez à l’App Store. À partir de la version 3.4.0 du SDK, cette exigence d’autorisation est supprimée. | Confidentialité – Description de l’utilisation du périphérique Bluetooth | | ------------------------------------------------------------------------ | | **Clé** | [NSBluetoothPeripheralUsageDescription](https://developer.apple.com/documentation/bundleresources/information_property_list/nsbluetoothperipheralusagedescription) | | **Valeur** | **La connexion aux lecteurs de cartes pris en charge nécessite un accès au Bluetooth.** | Ceci est un exemple ; vous pouvez reformuler la demande d’autorisation de l’utilisateur dans votre application. 5. Sauvegardez le fichier **Info.plist** de votre application. Il est désormais correctement configuré et peut être utilisé avec le SDK Stripe Terminal. > Si vous utilisez Tap to Pay sur iPhone, vous devez [demander et configurer](https://developer.apple.com/documentation/proximityreader/setting-up-the-entitlement-for-tap-to-pay-on-iphone) le droit de développement Tap to Pay sur iPhone à partir de votre compte Apple Developer. ## Configurer l'endpoint ConnectionToken [Côté serveur] [Côté client] ### Côté serveur Pour se connecter à un lecteur, votre back-end doit donner au SDK la permission d’utiliser le lecteur avec votre compte Stripe en lui fournissant la [clé secrète](https://docs.stripe.com/api/terminal/connection_tokens/object.md#terminal_connection_token_object-secret) d’un [ConnectionToken](https://docs.stripe.com/api/terminal/connection_tokens.md). Votre back-end doit créer des tokens de connexion uniquement pour les clients qu’il reconnaît comme fiables. #### curl ```bash curl https://api.stripe.com/v1/terminal/connection_tokens \ -u <>: \ -X "POST" ``` Obtenez la clé secrète à partir du `ConnectionToken` sur votre serveur et transmettez-la côté client. #### Ruby ```ruby post '/connection_token' do token = # ... Create or retrieve the ConnectionToken {secret: token.secret}.to_json end ``` > Le `secret` du `ConnectionToken` vous permet de vous connecter à n’importe quel lecteur Stripe Terminal et de traiter les paiements à l’aide de votre compte Stripe. Veillez à authentifier l’endpoint pour créer des tokens de connexion et à le protéger contre la falsification des requêtes intersites (CSRF). ### Côté client Afin de permettre au SDK d’accéder à cet endpoint, déployez le protocole [ConnectionTokenProvider](https://stripe.dev/stripe-terminal-ios/docs/Protocols/SCPConnectionTokenProvider.html) dans votre application. Celui-ci définit une fonction unique qui demande un `ConnectionToken` à votre back-end. ```swift import StripeTerminal // Example API client class for communicating with your backend class APIClient: ConnectionTokenProvider { // For simplicity, this example class is a singleton static let shared = APIClient() // Fetches a ConnectionToken from your backend func fetchConnectionToken(_ completion: @escaping ConnectionTokenCompletionBlock) { let config = URLSessionConfiguration.default let session = URLSession(configuration: config) guard let url = URL(string: "https://{{YOUR_BACKEND_URL}}/connection_token") else { fatalError("Invalid backend URL") } var request = URLRequest(url: url) request.httpMethod = "POST" let task = session.dataTask(with: request) { (data, response, error) in if let data = data { do { // Warning: casting using `as? [String: String]` looks simpler, but isn't safe: let json = try JSONSerialization.jsonObject(with: data, options: []) as? [String: Any] if let secret = json?["secret"] as? String { completion(secret, nil) } else { let error = NSError(domain: "com.stripe-terminal-ios.example", code: 2000, userInfo: [NSLocalizedDescriptionKey: "Missing `secret` in ConnectionToken JSON response"]) completion(nil, error) } } catch { completion(nil, error) } } else { let error = NSError(domain: "com.stripe-terminal-ios.example", code: 1000, userInfo: [NSLocalizedDescriptionKey: "No data in response from ConnectionToken endpoint"]) completion(nil, error) } } task.resume() } } ``` Cette fonction est appelée dès lors que le SDK doit s’authentifier auprès de Stripe ou du lecteur. Elle est également appelée lorsqu’un nouveau token est nécessaire pour se connecter à un lecteur (par exemple, lorsque votre application s’est déconnectée du lecteur). Si le SDK n’est pas en mesure de récupérer un nouveau jeton de connexion depuis votre backend, la connexion au lecteur échoue associée à une erreur de votre serveur. > Évitez de mettre en cache ou de coder en dur le token de connexion. Le SDK s’occupe de la gestion complète du cycle de vie du token de connexion. > #### Épinglage des certificats > > Dans la plupart des cas, vous ne devez pas configurer votre application avec l’épinglage de certificats. Si votre application l’exige, consultez la documentation sur l’[épinglage des certificats](https://docs.stripe.com/tls-certificates.md#certificate-pinning). ## Initialiser le SDK [Côté client] La classe [Terminal](https://stripe.dev/stripe-terminal-ios/docs/Classes/SCPTerminal.html) mise à disposition par le SDK Stripe Terminal dispose d’une interface générique permettant de détecter les lecteurs, de se connecter à un lecteur et d’effectuer des opérations sur le lecteur, telles que l’affichage des informations du panier, l’encaissement de paiements et l’enregistrement de cartes bancaires pour une utilisation ultérieure. Fournissez le `ConnectionTokenProvider` que vous avez implémenté lors de la [configuration du token de connexion](https://docs.stripe.com/terminal/payments/setup-integration.md#connection-token). Appelez `initWithTokenProvider` une seule fois dans votre application avant d’accéder à `Terminal.shared`, généralement dans le `application:didFinishLaunchingWithOptions` de la méthode `AppDelegate` ou dans l’`init()` de votre type d’`App` SwiftUI. Vous pouvez également utiliser `dispatch_once` dans Objective-C ou un initialiseur `static` dans Swift. ```swift import UIKit import StripeTerminal @UIApplicationMain class AppDelegate: UIResponder, UIApplicationDelegate { func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool { Terminal.initWithTokenProvider(APIClient.shared) // ... return true } // ... } ``` ## Mises à jour du SDK Stripe publie régulièrement des mises à jour qui peuvent inclure de nouvelles fonctionnalités, des corrections de bugs et des mises à jour de sécurité. Mettez à jour votre SDK dès qu’une nouvelle version est disponible. Les SDK actuellement disponibles sont les suivants : - [SDK Stripe Terminal Android](https://github.com/stripe/stripe-terminal-android/releases) - [SDK Stripe Terminal iOS](https://github.com/stripe/stripe-terminal-ios/releases) - [SDK Stripe Terminal JavaScript](https://docs.stripe.com/terminal/references/api/js-sdk.md#changelog) - [SDK Stripe Terminal React Native](https://github.com/stripe/stripe-terminal-react-native) ## Prochaines étapes - [Se connecter à un lecteur](https://docs.stripe.com/terminal/payments/connect-reader.md?terminal-sdk-platform=ios&reader-type=internet)