# Integration einrichten Richten Sie ein Stripe Terminal SDK oder eine servergestützte Integration ein, um persönliche Zahlungen zu akzeptieren. # iOS Eine ausführlichere Dokumentation mit allen verfügbaren Methoden, Objekten und Fehlern finden Sie in unserer [vollständigen SDK-Dokumentation](https://stripe.dev/stripe-terminal-ios). Für den Einstieg in das iOS SDK sind vier Schritte erforderlich: 1. [SDK](https://docs.stripe.com/terminal/payments/setup-integration.md#install) in Ihrer App installieren. 2. Ihre App [konfigurieren](https://docs.stripe.com/terminal/payments/setup-integration.md#configure). 3. [Verbindungs-Token](https://docs.stripe.com/terminal/payments/setup-integration.md#connection-token)-Endpoint in Ihrer App und Ihrem Backend einrichten. 4. [SDK](https://docs.stripe.com/terminal/payments/setup-integration.md#initialize) in Ihrer App initialisieren. ## SDK installieren [Clientseitig] Das Stripe Terminal iOS SDK ist mit Apps kompatibel, die: - iOS 15 und höher unterstützen - MIt CocoaPods, Swift Package Manager oder durch die manuelle Integration des Frameworks installiert werden #### CocoaPods 1. Falls noch nicht geschehen, installieren Sie bitte die aktuellste Version von [CocoaPods](https://guides.cocoapods.org/using/getting-started.html). 2. Wenn Sie keine bestehende [Podfile](https://guides.cocoapods.org/syntax/podfile.html) haben, führen Sie folgenden Befehl aus, um eine zu erstellen: ```bash pod init ``` 3. Fügen Sie folgende Zeile in Ihre Podfile ein: ```podfile pod 'StripeTerminal', '~> 5.0' ``` 4. Führen Sie folgenden Befehl aus: ```bash pod install ``` 5. Verwenden Sie ab jetzt anstelle der Datei `.xcodeproj` die Datei `.xcworkspace` zum Öffnen Ihres Projekts in Xcode. #### Swift Package Manager 1. Wählen Sie in Xcode in der Menüleiste die Option **Datei** > **Pakete hinzufügen…** aus. 2. Geben Sie die GitHub-URL des Stripe Terminal iOS SDK ein: `https://github.com/stripe/stripe-terminal-ios` 3. Geben Sie die SDK-Version ein, die Sie in Ihrem Projekt installieren möchten. Der Standardwert „Up to Next Major“ hilft Ihnen, über Sicherheits- und Funktionsupdates auf dem Laufenden zu bleiben, ohne dass fehlerverursachende Änderungen unerwartet übernommen werden. #### Manuell 1. Besuchen Sie das Stripe Terminal iOS Repository auf GitHub und gehen Sie zur [neuesten Veröffentlichung](https://github.com/stripe/stripe-terminal-ios/releases). 2. Laden Sie die Datei `StripeTerminal.xcframework.zip` herunter, die dem GitHub-Release zugeordnet ist. 3. Dekomprimieren Sie die Datei und fügen Sie anschließend das XCFramework per Drag-and-Drop in Ihr Xcode-Projekt ein. 4. Wenn die Symbole des Frameworks nicht geladen werden können, navigieren Sie zum Bereich „Allgemeines“ und wählen Sie das Dropdown-Menü „Frameworks, Bibliotheken und eingebettete Inhalte“. Wechseln Sie den Status von `StripeTerminal.xcframework` von „Nicht einbetten“ zu „Einbetten und Anmelden“. > Details zur neuesten SDK-Version und zu früheren Versionen finden Sie auf der [Releases](https://github.com/stripe/stripe-terminal-ios/releases)-Seite auf GitHub. Um Benachrichtigungen zu erhalten, wenn eine neue Version veröffentlicht wird, [beobachten Sie die Releases des Repositories](https://docs.github.com/en/github/managing-subscriptions-and-notifications-on-github/configuring-notifications#configuring-your-watch-settings-for-an-individual-repository) oder [abonnieren Sie den GitHub Releases RSS-Feed](https://github.com/stripe/stripe-terminal-ios/releases.atom). > > Informationen zur Migration von älteren Versionen des iOS SDK finden Sie im [Migrationsleitfaden für Stripe Terminal SDK](https://docs.stripe.com/terminal/references/sdk-migration-guide.md). ## App konfigurieren [Clientseitig] Damit Ihre App mit dem Stripe Terminal SDK verwendet werden kann, müssen Sie in Xcode einige Änderungen an Ihrer Datei **Info.plist** vornehmen. 1. Aktivieren Sie Standortdienste mit dem folgenden Schlüssel-Wert-Paar. | Datenschutz – „Location When In Use Usage Description“ | | ------------------------------------------------------ | | **Schlüssel** | [NSLocationWhenInUseUsageDescription](https://developer.apple.com/documentation/bundleresources/information_property_list/nslocationwheninuseusagedescription) | | **Wert** | **Zur Annahme von Zahlungen ist ein Standortzugriff erforderlich.** | Um das Risiko von Betrugsfällen bei Zahlungen zu reduzieren und Zahlungsanfechtungen zu minimieren, muss Stripe den Standort der getätigten Zahlungen kennen. Wenn das SDK den Standort des iOS-Geräts nicht ermitteln kann, werden alle Zahlungen bis zur Wiederherstellung des Standortzugriffs deaktiviert. 2. Stellen Sie sicher, dass Ihre App im Hintergrund ausgeführt wird und mit den Bluetooth-Lesegeräten verbunden bleibt. | Erforderliche Hintergrundmodi für Bluetooth-Lesegeräte | | ------------------------------------------------------ | | **Schlüssel** | [UIBackgroundModes](https://developer.apple.com/documentation/bundleresources/information_property_list/uibackgroundmodes) | | **Wert** | **bluetooth-central** (Verwendet Zubehör von Bluetooth LE) | Mit dem Festlegen des Hintergrundmodus [bluetooth-central](https://developer.apple.com/library/archive/documentation/NetworkingInternetWeb/Conceptual/CoreBluetooth_concepts/CoreBluetoothBackgroundProcessingForIOSApps/PerformingTasksWhileYourAppIsInTheBackground.html#//apple_ref/doc/uid/TP40013257-CH7-SW6) kann das Lesegerät im Standby-Modus bleiben, wenn die App im Hintergrund läuft oder wenn das iOS-Gerät gesperrt ist. Wird dieser Wert nicht angegeben, wird der Standby-Modus nicht aktiviert. Wenn Ihre App im Hintergrund läuft, kann sich das Lesegerät zum Energiesparen automatisch ausschalten. 3. Gestatten Sie Ihrer App, ein Dialogfeld für Bluetooth-Berechtigungen anzuzeigen. Der App-Store verlangt dies, auch wenn Ihre App die Verbindung mit Bluetooth-Lesegeräten nicht unterstützt. | Datenschutz – „Bluetooth Always Usage Description“ | | -------------------------------------------------- | | **Schlüssel** | [NSBluetoothAlwaysUsageDescription](https://developer.apple.com/documentation/bundleresources/information_property_list/NSBluetoothAlwaysUsageDescription) | | **Wert** | **Diese App verwendet Bluetooth, um sich mit unterstützten Kartenlesegeräten zu verbinden.** | iOS 13 führte spezifischere Berechtigungen für die Verwendung von Bluetooth-Peripheriegeräten durch eine App ein. Apps, die sich mit Core Bluetooth verbinden, müssen diesen Schlüssel in ihre Info.plist-Datei aufnehmen, um zu verhindern, dass die App beim ersten Start abstürzt. 4. App-Validierungsprüfungen bestehen, wenn Sie sie an den App Store übermittlen. Ab SDK-Version 3.4.0 ist diese Berechtigung nicht mehr erforderlich. | Datenschutz – „Bluetooth Peripheral Usage Description“ | | ------------------------------------------------------ | | **Schlüssel** | [NSBluetoothPeripheralUsageDescription](https://developer.apple.com/documentation/bundleresources/information_property_list/nsbluetoothperipheralusagedescription) | | **Wert** | **Für die Verbindung mit unterstützten Kartenlesegeräten ist Bluetooth-Zugriff erforderlich.** | Es handelt sich hierbei um ein Beispiel – Sie können die Aufforderung zur Nutzerberechtigung in Ihrer App umformulieren. 5. Speichern Sie die **Info.plist** Ihrer App. Die App ist jetzt korrekt konfiguriert und kann mit dem Stripe Terminal SDK verwendet werden. > Wenn Sie Tap to Pay auf dem iPhone verwenden, müssen Sie die Entwicklungsberechtigung für Tap to Pay auf dem iPhone von Ihrem Apple Entwicklerkonto aus [beantragen und konfigurieren](https://developer.apple.com/documentation/proximityreader/setting-up-the-entitlement-for-tap-to-pay-on-iphone). ## ConnectionToken-Endpoint einrichten [Serverseitig] [Clientseitig] ### Serverseitig Um sich mit einem Lesegerät verbinden zu können, muss das Backend dem SDK erlauben, das Lesegerät in Ihrem Stripe-Konto zu nutzen. Dazu stellt es dem SDK das [Geheimnis](https://docs.stripe.com/api/terminal/connection_tokens/object.md#terminal_connection_token_object-secret) aus einem [ConnectionToken](https://docs.stripe.com/api/terminal/connection_tokens.md) zur Verfügung. Das Backend muss nur Verbindungstoken für vertrauenswürdige Clients erstellen. #### curl ```bash curl https://api.stripe.com/v1/terminal/connection_tokens \ -u <>: \ -X "POST" ``` Beziehen Sie das Geheimnis aus dem `ConnectionToken` auf Ihrem Server und übergeben Sie es an den Client. #### Ruby ```ruby post '/connection_token' do token = # ... Create or retrieve the ConnectionToken {secret: token.secret}.to_json end ``` > Mit dem `secret` aus dem `ConnectionToken` können Sie sich mit einem beliebigen Stripe Terminal-Lesegerät verbinden und Zahlungen mit Ihrem Stripe-Konto annehmen. Stellen Sie sicher, dass Sie den Endpoint zum Erstellen von Verbindungstoken authentifizieren und diesen vor Cross Site Request Forgery (CSRF) schützen. ### Clientseitig Um dem SDK Zugriff auf diesen Endpoint zu ermöglichen, implementieren Sie das [ConnectionTokenProvider](https://stripe.dev/stripe-terminal-ios/docs/Protocols/SCPConnectionTokenProvider.html)-Protokoll in Ihrer App, das eine einzelne Funktion definiert, die einen `ConnectionToken` von Ihrem Backend anfordert. ```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() } } ``` Diese Funktion wird aufgerufen, wenn das SDK sich bei Stripe oder dem Lesegerät authentifizieren muss. Sie wird auch aufgerufen, wenn ein neues Verbindungstoken benötigt wird, um sich mit einem Lesegerät zu verbinden (z. B. wenn Ihre App sich von einem Lesegerät getrennt hat). Wenn das SDK kein neues Verbindungstoken von Ihrem Backend abrufen kann, schlägt die Verbindung zu einem Lesegerät mit einem Fehler von Ihrem Server fehl. > Speichern Sie den Verbindungstoken nicht im Cache und codieren Sie ihn nicht fest. Der Lifecycle des Verbindungstokens wird vom SDK verwaltet. > #### Certificate Pinning > > In den meisten Fällen sollten Sie Ihre Anwendung nicht mit Certificate Pinning konfigurieren. Erfordert Ihre Anwendung dies dennoch, so lesen Sie bitte die Dokumentation zum [Certificate Pinning](https://docs.stripe.com/tls-certificates.md#certificate-pinning). ## SDK initialisieren [Clientseitig] Die vom Stripe Terminal SDK bereitgestellte [Terminal](https://stripe.dev/stripe-terminal-ios/docs/Classes/SCPTerminal.html)-Klasse stellt eine allgemeine Schnittstelle zum Erkennen von Lesegeräten, zum Verbinden mit einem Lesegerät und zum Durchführen von Vorgängen auf dem Lesegerät bereit, wie z. B. Anzeigen von Warenkorbdetails, Erfassen von Zahlungen und Speichern von Karten für die zukünftige Verwendung. Geben Sie den `ConnectionTokenProvider` an, den Sie beim [Einrichten des Verbindungstokens](https://docs.stripe.com/terminal/payments/setup-integration.md#connection-token) implementiert haben. Rufen Sie `initWithTokenProvider` in Ihrer App nur einmal auf, bevor Sie auf `Terminal.shared` zugreifen, in der Regel in der `AppDelegate`-Methode `application:didFinishLaunchingWithOptions` oder im `init()` Ihres SwiftUI-`App`-Typs. Alternativ können Sie `dispatch_once` in Objective-C oder einen `statischen` Initialisierer in Swift verwenden. ```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 } // ... } ``` ## SDK-Aktualisierungen Stripe veröffentlicht regelmäßig Updates, die neue Funktionen, Fehlerkorrekturen und Sicherheitsupdates enthalten können. Aktualisieren Sie Ihr SDK, sobald eine neue Version verfügbar ist. Die derzeit verfügbaren SDKs sind: - [Stripe Terminal Android SDK](https://github.com/stripe/stripe-terminal-android/releases) - [Stripe Terminal iOS SDK](https://github.com/stripe/stripe-terminal-ios/releases) - [Stripe Terminal JavaScript SDK](https://docs.stripe.com/terminal/references/api/js-sdk.md#changelog) - [Stripe Terminal React Native SDK](https://github.com/stripe/stripe-terminal-react-native) ## Nächste Schritte - [Mit einem Lesegerät verbinden](https://docs.stripe.com/terminal/payments/connect-reader.md?terminal-sdk-platform=ios&reader-type=internet)