Terminal SDK-Migrationsleitfaden

Wenn Ihre Anwendung derzeit eine Terminal Android SDK-Version vor 3.0.0 verwendet, müssen Sie einige Änderungen vornehmen, um ein Upgrade vorzunehmen und weltweit Card-Present-Zahlungen zu akzeptieren. Eine detaillierte Liste der Änderungen von Version 3.10.0 auf 4.0.0 finden Sie im SDK changelog.

Speichern von Karten nach der Integration von PaymentIntents aktualisieren

Wenn Sie eine Zahlungsmethode nach einem erfolgreichen persönlichen PaymentIntent speichern, müssen Sie die folgenden Aktualisierungen an Ihrer Integration vornehmen:

• Übergeben Sie beim Erstellen von Terminal PaymentIntents den Parameter setup_future_usage, der Stripe darüber informiert, dass Sie zukünftige Zahlungen mit derselben Karte vornehmen möchten.
• Sie müssen auch allow_redisplay als ALWAYS oder LIMITED in CollectConfiguration übergeben. Übergeben Sie ALWAYS, wenn Sie möchten, dass die gespeicherte Karte des Kunden/der Kundin in allen zukünftigen Bezahlvorgängen angezeigt wird, und LIMITED, wenn sie nur im Rahmen der ursprünglich vorgesehenen Nutzung verwendet werden kann, zum Beispiel bei einem Abonnement.

Erfahren Sie mehr über das Speichern von Karten nach einer Zahlung.

Speichern von Karten ohne Zahlung mit SetupIntents-Integration aktualisieren

Um eine konsistente Integrationsform zwischen SetupIntents und PaymentIntents sowie persönlichen und Online-Transaktionen zu gewährleisten, haben in der collectSetupIntentPaymentMethod von Terminal den Parameter customerConsentCollected entfernt, der zuvor für alle SetupIntent-Transaktionen erforderlich war, und durch den Parameter allowRedisplay ersetzt.

Erfahren Sie mehr über das direkte Speichern ohne Abbuchung.

Aktualisieren Sie die Nutzung Ihrer discoverReader

• Wir haben einen neuen Enum-Wert DISCOVERING zu ConnectionStatus, um darzustellen, wann die Lesegerät-Erkennung ausgeführt wird. Stellen Sie sicher, dass Ihre Integration diesen neuen Status verarbeiten und Ihren Kunden/Kundinnen relevante Informationen bereitstellen kann.

• Wir haben die Handhabung mehrerer gleichzeitiger Erkennungsvorgänge für Lesegeräte verbessert. Zuvor hat das mehrfache Anrufen von Terminal::discoverReaders die Vorgänge in eine Warteschlange gestellt, was sich als unerwünscht erwies. Wenn nun ein neuer Terminal::discoverReaders aufgerufen wird, während ein bestehender bereits in Bearbeitung ist, bricht das SDK den laufenden Betrieb ab und gibt den Fehler CANCELED_DUE_TO_INTEGRATION_ERROR zurück. Der neue discoverReaders-Vorgang startet dann sofort.

• Das Entdecken von Smart- und Tap-to-Pay-Lesern ruft jetzt den Abschlussblock Terminal::discoverReaders auf, wenn der Vorgang endet. Diese Änderung spiegelt die Tatsache wider, dass die Entdeckung von Lesegeräten für diese Lesegerättypen kein langwieriger Vorgang ist.

Aktualisieren Sie die Nutzung Ihrer Lesegerätverbindung

• Um ein konsistentes Integrationsmuster für die Erkennung und Verbindung von Lesegeräten zu gewährleisten, haben wir alle Verbindungsmethoden für Lesegeräte (connectBluetoothReader, connectUsbReader, connectInternetReader, connectLocalMobileReader, connectHandoffReader) in Terminal::connectReader zusammengefasst. Der spezifische Verbindungstyp wird weiterhin durch die bereitgestellte Verbindungskonfiguration bestimmt.
• Bei mobilen Lesegeräten wurde der readerListener-Parameter aus den alten connectBluetoothReader, connectUsbReader-Methoden entfernt und in das jeweilige ConnectionConfiguration-Objekt verschoben, wodurch ReaderReconnectionListener ersetzt wurde. Bei Tap-to-Pay-Lesegeräten nimmt die TapToPayConnectionConfiguration jetzt einen TapToPayReaderListener-Parameter auf, wodurch ReaderReconnectionListener ersetzt wird.
• In Übereinstimmung mit anderen Lesegerättypen erwartet die InternetConnectionConfiguration des intelligenten Lesegeräts nun auch, dass ein InternetReaderListener übergeben wird, der Ihre Integration von Ereignissen einschließlich Verbindungstrennungen benachrichtigt.
• Für Apps auf Geräten im Übergabemodus wurde HandoffReaderListener von der alten connectHandoffReader-Methode als Parameter entfernt und in das HandoffConnectionConfiguration-Objekt verschoben.

Vor

val connectionConfig = ConnectionConfiguration.BluetoothConnectionConfiguration(
    
"{{LOCATION_ID}}"
)
Terminal.getInstance().connectBluetoothReader(
    selectedReader,
    connectionConfig,
    readerListener,
    object : ReaderCallback {
        override fun onSuccess(reader: Reader) {
            // Placeholder for handling successful operation
        }
        override fun onFailure(e: TerminalException) {
            // Placeholder for handling exception
        }
    }
)

Nach

// Implement your MobileReaderListener
val mobileReaderListener = yourMobileReaderListener
val autoReconnectOnUnexpectedDisconnect = true

val connectionConfig = BluetoothConnectionConfiguration(
    
"{{LOCATION_ID}}",
    autoReconnectOnUnexpectedDisconnect,
    mobileReaderListener
)

Terminal.getInstance().connectReader(
    selectedReader,
    connectionConfig,
    object : ReaderCallback {
        override fun onSuccess(reader: Reader) {
            // Placeholder for handling successful operation
        }

        override fun onFailure(e: TerminalException) {
            // Placeholder for handling exception
        }
    }
)

Weitere Informationen finden Sie in unserer Dokumentation zum Verbinden mit einem Lesegerät.

Die automatische Wiederverbindung ist jetzt standardmäßig für mobile und Tap-to-Pay-Lesegeräte aktiviert

• Um die Ausfallsicherheit Ihrer Terminal-Integration mit mobilen und Tap-to-Pay-Lesegeräten zu erhöhen, haben wir die automatische Wiederverbindung standardmäßig aktiviert, wenn das Lesegerät unerwartet die Verbindung trennt.
• Wir empfehlen, Benachrichtigungen in Ihrer App anzuzeigen, um die Nutzer/innen während des gesamten Wiederverbindungsvorgangs über den Lesegerätstatus zu informieren. Für die Handhabung von Wiederverbindungsmethoden für Lesegeräte wurde der ReaderReconnectionListener von den jeweiligen ReaderListenern übernommen. Verwenden Sie MobileReaderListener für mobile Lesegeräte und TapToPayReaderListener für Tap-to-Pay-Lesegeräte, um Wiederverbindungsereignisse zu verarbeiten.
• Wir haben den Parameter ReaderReconnectionListener aus den Verbindungskonfigurationen LocalMobileConnectionConfiguration, BluetoothConnectionConfiguration und UsbConnectionConfiguration entfernt und durch den entsprechenden ReaderListener ersetzt.

Wenn Sie Ihre eigene Wiederverbindungslogik für Lesegeräte implementiert haben und dieses Verhalten beibehalten möchten, können Sie die automatische Wiederverbindung deaktivieren, indem Sie autoReconnectOnUnexpectedDisconnect auf false setzen.

Vor

class CustomReaderReconnectionListener : ReaderReconnectionListener {
    override fun onReaderReconnectStarted(reader: Reader, cancelReconnect: Cancelable, reason: DisconnectReason) {
        // 1. Notified at the start of a reconnection attempt
        // Use cancelable to stop reconnection at any time
    }

    override fun onReaderReconnectSucceeded(reader: Reader) {
        // 2. Notified when reader reconnection succeeds
        // App is now connected
    }

    override fun onReaderReconnectFailed(reader: Reader) {
        // 3. Notified when reader reconnection fails
        // App is now disconnected
    }
}

Nach

class CustomMobileReaderListener : MobileReaderListener {
    // ...

    override fun onReaderReconnectStarted(reader: Reader, cancelReconnect: Cancelable, reason: DisconnectReason) {
        // 1. Notified at the start of a reconnection attempt
        // Use cancelable to stop reconnection at any time
    }

    override fun onReaderReconnectSucceeded(reader: Reader) {
        // 2. Notified when reader reconnection succeeds
        // App is now connected
    }

    override fun onReaderReconnectFailed(reader: Reader) {
        // 3. Notified when reader reconnection fails
        // App is now disconnected
    }

    // ...
}

Weitere Informationen finden Sie in unserer Dokumentation zum automatischen Wiederverbindungsversuch.

Aktualisieren Sie Ihre Handhabung beim Trennen der Lesegeräte

• Um informiert zu werden, wenn ein Lesegerät die Verbindung trennt, haben wir die Rückrufe der Leserverbindung für alle Lesertypen konsolidiert, indem wir TerminalListener::onUnexpectedReaderDisconnect entfernt haben. Implementieren Sie in Zukunft onDisconnect auf einem der folgenden Listener, um über die Trennung des entsprechenden Lesegeräts informiert zu werden: InternetReaderListener, MobileReaderListener, TapToPayReaderListener oder HandoffReaderListener. Bei mobilen Lesegeräten kann der DisconnectReason helfen, den Grund für die Trennung zu ermitteln.

Wenn die automatische Wiederverbindung aktiviert ist, werden sowohl onDisconnect als auch onReaderReconnectFailed-Methoden aufgerufen, wenn sich das SDK nicht wieder mit dem Lesegerät verbindet und die Verbindung getrennt wird.

Vor

class ReaderActivity : AppCompatActivity(), TerminalListener {
    // ...
    Terminal.getInstance().setTerminalListener(this)
    // ...
    override fun onUnexpectedReaderDisconnect(reader: Reader) {
        // Consider displaying a UI to notify the user and start rediscovering readers
    }
    // ...
}

Nach

class ReaderActivity : AppCompatActivity(), MobileReaderListener {
    // ...

    override fun onDisconnect(reason: DisconnectReason) {
        // Consider displaying a UI to notify the user and start rediscovering readers
    }

    // ...
}

Weitere Informationen finden Sie in unserer Dokumentation zum manuellen Umgang mit Verbindungsabbrüchen.

Aktualisieren Sie Ihre Integration für die Zahlungsannahme

• Sie können Terminal::confirmPaymentIntent mit dem zurückgegebenen Objekt Cancelable abbrechen. Dies ist nützlich für QR-Code-Zahlungen, die einen asynchronen Bestätigungsprozess haben. Auch Terminal::confirmSetupIntent und Terminal::confirmRefund können jetzt storniert werden.
• Um den Stornierungsfluss für PaymentIntents und SetupIntents zu verbessern, werden mit dem Aufruf von Terminal::cancelPaymentIntent oder Terminal::cancelSetupIntent nun auch alle laufenden Zahlungsvorgänge abgebrochen. Sie müssen Zahlungsvorgänge wie Terminal::collectPaymentMethod nicht mehr separat stornieren, bevor Sie den PaymentIntent stornieren.
• SetupIntent.id kann nun auf Null gesetzt werden, um mit PaymentIntent.id konsistent zu sein. Obwohl der Wert id weiterhin existiert, stellen Sie sicher, dass Ihr Code den Fall, in dem SetupIntent.id möglicherweise null ist, sicher verarbeitet, um Compiler-Fehler zu vermeiden.

Fehlerbehebung aktualisieren

• Wir haben TerminalException.TerminalErrorCode in eine eigenständige Aufzählung, TerminalErrorCode, verschoben. Achten Sie darauf, die Importanweisungen und die Terminal-Fehlercode-Definition zu aktualisieren, um die Funktionalität aufrechtzuerhalten.
• Wir haben den neuen Terminal-Fehlercode TerminalErrorCode.GENERIC_READER_ERROR hinzugefügt. Dieser Fehler kann auftreten, wenn das SDK nicht mehr aktuell ist, und kann den vom intelligenten Lesegerät zurückgegebenen Fehler nicht erkennen. Aktualisieren Sie Ihr Terminal-SDK, um diesen Fehler zu beheben.
• Für Tap-to-Pay auf Android kommt es bei Terminal::collectPaymentMethod und Terminal::collectSetupIntentPaymentMethod jetzt nach 60 Sekunden zu einer Zeitüberschreitung für Tap-to-Pay-Transaktionen auf Android. Es wird eine TerminalException mit dem Fehlercode TerminalErrorCode.CARD_READ_TIMED_OUT ausgelöst.
• Bei Tap to Pay auf Android wird, wenn die PIN-Erfassung für eine Zahlung angefordert wird, eine TerminalException mit dem Fehlercode FEATURE_NOT_ENABLED_ON_ACCOUNT anstelle von DECLINED_BY_STRIPE_API mit einem ONLINE_OR_OFFLINE_PIN_REQUIRED-ApiError ausgelöst.

Nutzung für Umbenennung und Refactoring aktualisieren

• ReaderListener wurde in MobileReaderListener umbenannt.
• Wir haben den allowedPaymentMethodTypes-Parameter in paymentMethodTypes in den Konstruktoren PaymentIntentParameters.Builder und SetupIntentParameter.Builder umbenannt.
• In ReaderSoftwareUpdate, haben wir UpdateTimeEstimate in UpdateDurationEstimate und estimatedUpdateTime in durationEstimate umbenannt,` um ihre Absicht besser darzustellen.
• Für die folgenden Felder haben wir java.util.Date-Referenzen in Millisekunden-Zeitstempel konvertiert: ReaderSoftwareUpdate::requiredAt, OfflineDetails::storedAt und OfflineSetupIntentDetails::storedAt. Stellen Sie sicher, dass Ihre Anwendung diese Zeitstempel korrekt interpretiert.
• Felder auf dem Location-Objekt können nicht mehr geändert werden.

Aktualisieren Sie Ihre Integration von Tap to Pay auf Android

• Die Maven-Koordinaten für die Funktion „Tap to Pay“ auf Android wurden in com.stripe:stripeterminal-taptopay:4.0.0 geändert. Aktualisieren Sie Ihre Build-Abhängigkeiten, um auf den neuen Artefaktnamen zu verweisen. Die alte wird nicht mehr aktualisiert.
• Wir haben alle LocalMobile-Funktionen und -Feldnamen in TapToPay umbenannt. Beispielsweise wurde LocalMobileDiscoveryConfiguration in TapToPayDiscoveryConfiguration umbenannt.
• TapToPayConnectionConfiguration verwendet jetzt den Parameter TapToPayReaderListener. Dieser Listener übernimmt Ereignisse sowohl von ReaderReconnectionListener als auch von ReaderDisconnectionListener und bietet einen einheitlichen Mechanismus für die Verarbeitung von Lesegerätereignissen.
• Wir haben den Hintergrundanwendungsprozess für das Erfassen von Tap-to-Pay-Transaktionen umbenannt, um die ID Ihrer Anwendung mit dem Suffix :stripetaptopay zu verwenden.