Terminal SDK 移行ガイド

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

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

対面支払いで PaymentIntent が成功した後に決済手段を保存する場合、システムを次のように更新する必要があります。

• Terminal の PaymentIntent を作成する際に、setup_future_usage パラメーターを渡します。これは、今後の支払いを同じカードを使用することを Stripe に通知します。
• また、allow_redisplay を ALWAYS または LIMITED にして CollectConfiguration に渡す必要があります。顧客の保存したカードを今後すべての決済フローで表示する場合は ALWAYS を、サブスクリプションのような最初に設定した用途でのみ使用する場合は LIMITED を渡します。

支払い後にカードを保存する方法についてご紹介します。

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

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

請求なしで直接保存する方法についてご紹介します。

discoverReaders の使用に関する更新

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

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

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

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

• リーダーの検出と接続で一貫したシステムパターンが保たれるように、リーダー接続メソッド (connectBluetoothReader、connectUsbReader、connectInternetReader、connectLocalMobileReader、connectHandoffReader) をすべて Terminal::connectReader に統合しました。正確な接続タイプは、指定された接続設定によって決定されます。
• モバイルリーダーでは、readerListener パラメーターが以前の connectBluetoothReader メソッドと connectUsbReader メソッドから削除され、代わりにそれぞれの ConnectionConfiguration オブジェクトに移動し、ReaderReconnectionListener が置き換えられました。Tap to Pay リーダーでは、ReaderReconnectionListener の代わりに TapToPayConnectionConfiguration が TapToPayReaderListener パラメーターを受け取るようになりました。
• 他のリーダータイプと同様に、スマートリーダーの InternetConnectionConfiguration も InternetReaderListener が渡されることを想定されるようになりました。 これにより、リーダーの切断などのイベントがあった場合にシステムに警告が通知されます。
• ハンドオフモードのデバイスのアプリでは、HandoffReaderListener が以前の connectHandoffReader メソッドからパラメーターとして削除され、HandoffConnectionConfiguration オブジェクトに移動しました。

移行前

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
        }
    }
)

移行後

// 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
        }
    }
)

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

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

• モバイルリーダーおよび Tap to Pay リーダーの Terminal のシステムの回復力を高めるため、リーダーが予期せず切断された場合の自動再接続がデフォルトで有効になります。
• 再接続プロセスの間、ユーザーにリーダーの状態を知らせるために、アプリに通知を表示させることをお勧めします。リーダーの再接続メソッドを処理するために、 ReaderReconnectionListener はそれぞれの ReaderListeners に引き継がれています。再接続イベントを処理するには、モバイルリーダーの場合 MobileReaderListener を、Tap to Pay リーダーの場合 TapToPayReaderListener を使用します。
• LocalMobileConnectionConfiguration、BluetoothConnectionConfiguration、UsbConnectionConfiguration の接続設定から ReaderReconnectionListener パラメーターを削除し、適切な ReaderListener に置き換えました。

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

移行前

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
    }
}

移行後

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
    }

    // ...
}

詳細については、自動再接続の試行に関する Stripe ドキュメントをご覧ください。

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

• リーダーの切断が生じた場合に通知されるように、TerminalListener::onUnexpectedReaderDisconnect を削除して、すべてのリーダータイプの切断コールバックを統一しました。今後は、対応するリーダーの切断が通知されるよう、以下のリスナーのいずれかに onDisconnect を実装してください: InternetReaderListener、MobileReaderListener、TapToPayReaderListener、HandoffReaderListener。モバイルリーダーの場合、DisconnectReason で切断の理由を確認できます。

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

移行前

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
    }
    // ...
}

移行後

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

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

    // ...
}

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

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

• 返された Cancelable オブジェクトを使用して Terminal::confirmPaymentIntent をキャンセルできるようになりました。これは、確認プロセスが非同期である QR コード決済に有効です。同様に、Terminal::confirmSetupIntent と Terminal::confirmRefund もキャンセルできるようになりました。
• Terminal::cancelPaymentIntent または Terminal::cancelSetupIntent を呼び出した場合に、実行中の支払い処理がキャンセルされるようになりました。これは、PaymentIntent と SetupIntent のキャンセルフローを改善するために行われた変更です。PaymentIntent をキャンセルする前に Terminal::collectPaymentMethod などの支払い処理を個別にキャンセルする必要はありません。
• PaymentIntent.id との一貫性を持たせるために、SetupIntent.id の null 指定が可能になりました。id の値は引き続き表示されますが、コンパイルエラーを回避するために、SetupIntent.id が null になるケースをコードで安全に処理できるかご確認ください。

エラー処理に関する更新

• TerminalException.TerminalErrorCodeをスタンドアロンの列挙型TerminalErrorCodeに移動しました。機能を維持するために、import ステートメントと Terminal のエラーコードの定義を更新してください。
• 新しい Terminal のエラーコード TerminalErrorCode.GENERIC_READER_ERROR を追加しました。これは、SDK が期限切れであり、スマートリーダーから返されたエラーを認識できない場合に発生します。このエラーを解決するには、Terminal SDK を更新する必要があります。
• Android のタッチ決済では、Terminal::collectPaymentMethod および Terminal::collectSetupIntentPaymentMethod が取引から 60 秒後にタイムアウトするようになりました。TerminalException がエラーコード TerminalErrorCode.CARD_READ_TIMED_OUT で発生します。
• Android のタッチ決済では、PIN の収集が支払いのためにリクエストされると、ONLINE_OR_OFFLINE_PIN_REQUIRED、ApiError が指定された DECLINED_BY_STRIPE_API ではなく、エラーコード FEATURE_NOT_ENABLED_ON_ACCOUNT の TerminalException が発生します。

名称変更およびリファクタリングに関する更新

• ReaderListener は MobileReaderListener に名前が変更されています。
• PaymentIntentParameters.Builder と SetupIntentParameter.Builder コンストラクターの allowedPaymentMethodTypes パラメータの名前を paymentMethodTypes に変更しました。
• ReaderSoftwareUpdate, で、UpdateTimeEstimate を UpdateDurationEstimate に、estimatedUpdateTime をdurationEstimate に名前を変更しました。これにより、インテントが把握しやすくなります。
• ReaderSoftwareUpdate::requiredAt フィールド、OfflineDetails::storedAt フィールド、OfflineSetupIntentDetails::storedAt フィールドのjava.util.Date リファレンスをミリ秒単位のタイムスタンプに変換しました。アプリケーションがこれらのタイムスタンプを正しく解釈できているかご確認ください。
• Location オブジェクトのフィールドは編集できなくなりました。

Android のタッチ決済システムに関する更新

• Android のタッチ決済機能の Maven 座標が com.stripe:stripeterminal-taptopay:4.0.0 に変更されました。ビルドの依存関係を更新して、新しいアーティファクト名を指定する必要があります。古いものは更新されなくなります。
• すべての LocalMobile の関数名とフィールド名を TapToPay に変更しました。たとえば、LocalMobileDiscoveryConfiguration は TapToPayDiscoveryConfiguration に名前が変更されています。
• TapToPayConnectionConfiguration が TapToPayReaderListener パラメーターを受け取るようになりました。このリスナーは ReaderReconnectionListener と ReaderDisconnectionListener の両方からイベントを引き継ぎ、リーダーイベントを処理するための統一メカニズムを提供します。
• Tap to Pay 取引の収集に使用されるバックグラウンドアプリケーションプロセスの名前を変更しました。アプリケーションの ID の末尾に :stripetaptopay が配置されるようになります。