Terminal SDK 移行ガイド

アプリケーションが 4.0.0 より前のバージョンの Terminal iOS SDK を使用している場合、更新してカードの対面支払いをグローバルに受け付けるには変更がいくつか必要です。バージョン 3.9.1 から 4.0.0 への変更点のリストについては、SDK 変更ログをご覧ください。

iOS 14 以降のミニマムサポートバージョンに関する更新

Stripe は、開発者サポート業務を効率化するために SDK のミニマムサポートバージョンを定期的に更新しています。

現行の Terminal iOS SDK バージョン 3.X は、引き続き iOS 13 以降で動作するデバイスをサポートします。

PaymentIntent 設定後のカードの保存システムに関する更新

対面での PaymentIntent が成功した後に支払い方法を保存する場合、システムで以下の更新を行う必要があります。

• Terminal の PaymentIntent を作成する際に、setup_future_usage パラメーターを渡します。これは、今後の支払いを同じカードを使用することを Stripe に通知します。

• また、allow_redisplay を always または limited にして SCPCollectConfiguration に渡す必要があります。顧客の保存したカードを今後すべての決済フローで表示する場合は always を、サブスクリプションのような最初に設定した用途でのみ使用する場合は limited を渡します。

  支払い後にカードを保存で詳細をご確認ください。

SetupIntent の支払いを使用しないカードの保存システムに関する更新

SetupIntent と PaymentIntent 間、また対面取引とオンライン取引間でシステムの形が統一されるよう、以前まですべての SetupIntent トランザクションで必須だった customerConsentCollected パラメーターを削除し、代わりに allowRedisplay パラメーターを SCPTerminal の collectSetupIntentPaymentMethod に追加しました。

支払わずに直接保存で詳細をご確認ください。

discoverReaders の使用に関する更新

• リーダー検出の実行状況を示す新しい列挙値 discovering を SCPConnectionStatus に追加しました。構築済みのシステムがこの新しい列挙値に対応できることを確認し、関連する情報を顧客に伝達してください。

• リーダー検出操作の複数同時処理を改善しました。以前までは、discoverReaders を複数回呼び出すと、操作がキューに入れられていました。新しい discoverReaders では、既存の操作の実行中に呼び出しが行われると、SDK が実行中の操作をキャンセルし、SCPErrorCanceledDueToIntegrationError エラーを返します。その後、discoverReaders の新しい操作が直ちに開始されます。

• スマートリーダーおよび Tap to Pay リーダーを見つけると、操作の終了時に discoverReaders の完了ブロックが呼び出されるようになりました。この変更は、これらのリーダータイプに対するリーダー検出が長時間実行される操作ではないことを表しています。

リーダー接続の利用に関する更新

• リーダーの検出と接続で一貫したシステムパターンが保たれるように、以前のリーダー接続メソッド (connectBluetoothReader、connectInternetReader、connectLocalMobileReader) をすべて connectReader に統合しました。正確な接続タイプは、渡された接続設定によって決定されます。

• モバイルリーダーと Tap to Pay リーダーでは、ReaderDelegate パラメーターが connectReader メソッドから削除され、代わりに以前 SCPReconnectionDelegate だった connectionConfig に移動しました。他のリーダータイプと同様に、スマートリーダーの InternetConnectionConfiguration も InternetReaderDelegate が渡されることを想定しています。これは、リーダーの切断などのイベントをシステムに警告します。

移行前

// Call `connectBluetoothReader` with the selected reader and a connection config
// to register to a location as set by your app.
let connectionConfig: BluetoothConnectionConfiguration
do {
    connectionConfig = try BluetoothConnectionConfigurationBuilder(locationId: 
"{{LOCATION_ID}}").build()
} catch {
    // Handle the error building the connection configuration
    return
}
Terminal.shared.connectBluetoothReader(selectedReader, delegate: readerDelegate, connectionConfig: connectionConfig) { reader, error in
    if let reader = reader {
        print("Successfully connected to reader: \(reader)")
    } else if let error = error {
        print("connectBluetoothReader failed: \(error)")
    }
}

移行後

// Call `connectReader` with the selected reader and a connection config
// to register to a location as set by your app.
let connectionConfig: BluetoothConnectionConfiguration
do {
    connectionConfig = try BluetoothConnectionConfigurationBuilder(delegate: yourMobileReaderDelegate, locationId: 
"{{LOCATION_ID}}")
    .build()
} catch {
    // Handle the error building the connection configuration
    return
}
Terminal.shared.connectReader(selectedReader, connectionConfig: connectionConfig) { reader, error in
    if let reader = reader {
        print("Successfully connected to reader: \(reader)")
    } else if let error = error {
        print("connectReader failed: \(error)")
    }
}

詳しくは、リーダーへの接続に関する Stripeドキュメントをご覧ください。

モバイルリーダーと Tap to Pay リーダーで自動再接続がデフォルトで有効になりました

• モバイルリーダーおよび Tap to Pay リーダーの Terminal のシステムの回復力を高めるため、リーダーが予期せず切断された場合の自動再接続がデフォルトで有効になります。

• 再接続プロセスの間、ユーザーにリーダーの状態を知らせるために、アプリに通知を表示させることをお勧めします。SCPReconnectionDelegate は、リーダーの再接続メソッドを処理するために削除されました。その役割は、それぞれの ReaderDelegate に統合されています。再接続イベントを処理するには、モバイルリーダーの場合 MobileReaderDelegate を、Tap to Pay リーダーの場合 TapToPayReaderDelegate を使用します。

• 独自のリーダー再接続ロジックを実装し、この動作を維持したい場合は、setAutoReconnectOnUnexpectedDisconnect を false に設定して自動再接続をオフにします。

移行前

import StripeTerminal

extension ReaderViewController: ReconnectionDelegate {
    // MARK: ReconnectionDelegate
    func terminal(_ terminal: Terminal, didStartReaderReconnect cancelable: Cancelable) {
        // 1. Notified at the start of a reconnection attempt
        // Use cancelable to stop reconnection at any time
    }

    func terminalDidSucceedReaderReconnect(_ terminal: Terminal) {
        // 2. Notified when reader reconnection succeeds
        // App is now connected
    }
    func terminalDidFailReaderReconnect(_ terminal: Terminal) {
        // 3. Notified when reader reconnection fails
        // App is now disconnected
    }
}

移行後

import StripeTerminal

extension ReaderViewController: MobileReaderDelegate {
    // MARK: MobileReaderDelegate

    func reader(_ reader: Reader, didStartReconnect cancelable: Cancelable, disconnectReason: DisconnectReason) {
        // 1. Notified at the start of a reconnection attempt
        // Use cancelable to stop reconnection at any time
    }

    func readerDidSucceedReconnect(_ reader: Reader) {
        // 2. Notified when reader reconnection succeeds
        // App is now connected
    }
    func readerDidFailReconnect(_ reader: Reader) {
        // 3. Notified when reader reconnection fails
        // App is now disconnected
    }
}

詳細およびコードスニペットの内容については、自動再接続の試行に関する Stripe ドキュメントをご覧ください。

リーダー切断の処理に関する更新

• SCPTerminalDelegate から terminal:didReportUnexpectedReaderDisconnect: が削除され、リーダーの切断が生じた場合に通知されるよう、すべてのリーダータイプの切断コールバックを統一しました。ReaderDelegates の一部として reader:didDisconnect: を使用した場合、リーダーの切断時に通知が届きます。モバイルリーダーの場合、SCPDisconnectReason で切断の理由を確認できます。

自動再接続が有効になっている場合、SDK がリーダーとの再接続に失敗して切断されると、-readerDidFailReconnect: メソッドと reader:didDisconnect: メソッドの両方が呼び出されます。

移行前

import StripeTerminal

class ReaderViewController: UIViewController, TerminalDelegate {
    override func viewDidLoad() {
        super.viewDidLoad()
        Terminal.shared.delegate = self
    }

    // ...
    // MARK: TerminalDelegate
    func terminal(_ terminal: Terminal, didReportUnexpectedReaderDisconnect reader: Reader) {
        // Consider displaying a UI to notify the user and start rediscovering readers
    }
}

移行後

import StripeTerminal

class ReaderViewController: UIViewController, MobileReaderDelegate {
    override func viewDidLoad() {
        super.viewDidLoad()
        // Set the reader delegate when connecting to a reader
    }

    // ...



    func reader(_ reader: Reader, didDisconnect reason: DisconnectReason) {
        // Consider displaying a UI to notify the user and start rediscovering readers
    }
}

詳しくは、切断の手動処理に関する Stripeドキュメントをご覧ください。

決済の受け付けシステムに関する更新

• 返された Cancelable オブジェクトを使用して confirmPaymentIntent をキャンセルできるようになりました。これは、確認プロセスが非同期である QR コード決済に有効です。同様に、confirmSetupIntent と confirmRefund もキャンセルできるようになりました。
• paymentMethodTypes の指定方法 (SCPPaymentIntentParameters と SCPSetupIntentParameters) を更新しました。これにより、安全性とモバイル SDK 間の一貫性が改善されます。以前は、このパラメーターが文字列の配列で表記されていました ([card_present] など)。現在は SCPPaymentMethodType の列挙値が使用されています。
• Terminal::cancelPaymentIntent または Terminal::cancelSetupIntent を呼び出した場合に、実行中の支払い処理がキャンセルされるようになりました。これは、PaymentIntent と SetupIntent のキャンセルフローを改善するために行われた変更です。PaymentIntent をキャンセルする前に .collectPaymentMethod などの支払い処理を個別にキャンセルする必要はありません。
• SCPPaymentIntent.stripeId との一貫性を持たせるために、SCPSetupIntent.stripeId の null 指定が可能になりました。stripeId の値は引き続き有効ですが、コンパイルエラーを回避するために、SCPSetupIntent.stripeId が null になるケースをコードで安全に処理できるかご確認ください。

名称変更および廃止に関する更新

• BluetoothReaderDelegate は MobileReaderDelegate に名前を変更しました。
• SCPReaderSoftwareUpdate, で、SCPUpdateTimeEstimate を SCPUpdateDurationEstimate に、estimatedUpdateTime をdurationEstimate に名前を変更しました。これにより、インテントが把握しやすくなります。
• SCPOfflineDetails で、オフライン中に支払いが作成または確認されたときに利用できる支払いの詳細を表示すようにしました。オフラインの支払いが発生した時間の名前を collectedAt から storedAt に変更し、Terminal Android SDK の命名規則に合わせました。
• すべての SDK の関数名とエラーコードにおいて、「local mobile 」と 「apple built in 」の名前を「Tap To Pay 」に変更しました。