Configurer votre intégration

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

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
   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
   Valeur	bluetooth-central (Utilise les accessoires Bluetooth LE)

   La configuration du mode d’arrière-plan bluetooth-central 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
   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
   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.

Sauvegardez le fichier Info.plist de votre application. Il est désormais correctement configuré et peut être utilisé avec le SDK Stripe Terminal.

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 d’un ConnectionToken. Votre back-end doit créer des tokens de connexion uniquement pour les clients qu’il reconnaît comme fiables.

curl https://api.stripe.com/v1/terminal/connection_tokens \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -X "POST"

Obtenez la clé secrète à partir du ConnectionToken sur votre serveur et transmettez-la côté client.

post '/connection_token' do
  token = # ... Create or retrieve the ConnectionToken
  {secret: token.secret}.to_json
end

Côté client

Afin de permettre au SDK d’accéder à cet endpoint, déployez le protocole ConnectionTokenProvider dans votre application. Celui-ci définit une fonction unique qui demande un ConnectionToken à votre back-end.

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.

La classe Terminal 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.

Pour commencer, fournissez votre ConnectionTokenProvider utilisé à l’étape 3. Vous ne pouvez appeler setTokenProvider qu’une seule fois dans votre application, et devez le faire avant d’accéder à Terminal.shared. Nous vous recommandons d’appeler setTokenProvider en utilisant la méthode application:didFinishLaunchingWithOptions de votre AppDelegate. Vous pouvez sinon utiliser dispatch_once dans Objective-C, ou un assistant de construction static dans Swift.

import UIKit
import StripeTerminal

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
        Terminal.setTokenProvider(APIClient.shared)
        // ...
        return true
    }

    // ...

}