Use institution_selected API when consent is already acquired

Author: mats-stripe

StripeFinancialConnections/StripeFinancialConnections.xcodeproj/project.pbxproj

@@ -69,6 +69,7 @@
 		497142BC2C514B08000DFA64 /* FlowRouterTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 497142BB2C514B08000DFA64 /* FlowRouterTests.swift */; };
 		499EEAFD2D3E948B00E1BE85 /* FinancialConnectionsAPIClientLogger.swift in Sources */ = {isa = PBXBuildFile; fileRef = 499EEAFC2D3E948B00E1BE85 /* FinancialConnectionsAPIClientLogger.swift */; };
 		49A0B5862C5D2F3C00D697D9 /* FinancialConnectionsAPIClientTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 49A0B5852C5D2F3C00D697D9 /* FinancialConnectionsAPIClientTests.swift */; };
+		49AC00C22D7B5C90005BFD57 /* FinancialConnectionsSelectInstitution.swift in Sources */ = {isa = PBXBuildFile; fileRef = 49AC00C12D7B5C90005BFD57 /* FinancialConnectionsSelectInstitution.swift */; };
 		49AC518C2C52DE2C00B712CC /* FinancialConnectionsLinkLoginPane.swift in Sources */ = {isa = PBXBuildFile; fileRef = 49AC518B2C52DE2C00B712CC /* FinancialConnectionsLinkLoginPane.swift */; };
 		49AED8FF2D4D244B00FD7C23 /* [email protected] in Resources */ = {isa = PBXBuildFile; fileRef = 49AED8FE2D4D244B00FD7C23 /* [email protected] */; };
 		49B5BF762D43E1D500AB6C3F /* FinancialConnectionsAppearance.swift in Sources */ = {isa = PBXBuildFile; fileRef = 49B5BF752D43E1D500AB6C3F /* FinancialConnectionsAppearance.swift */; };
@@ -339,6 +340,7 @@
 		497142BB2C514B08000DFA64 /* FlowRouterTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = FlowRouterTests.swift; sourceTree = "<group>"; };
 		499EEAFC2D3E948B00E1BE85 /* FinancialConnectionsAPIClientLogger.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = FinancialConnectionsAPIClientLogger.swift; sourceTree = "<group>"; };
 		49A0B5852C5D2F3C00D697D9 /* FinancialConnectionsAPIClientTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = FinancialConnectionsAPIClientTests.swift; sourceTree = "<group>"; };
+		49AC00C12D7B5C90005BFD57 /* FinancialConnectionsSelectInstitution.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = FinancialConnectionsSelectInstitution.swift; sourceTree = "<group>"; };
 		49AC518B2C52DE2C00B712CC /* FinancialConnectionsLinkLoginPane.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = FinancialConnectionsLinkLoginPane.swift; sourceTree = "<group>"; };
 		49AED8FE2D4D244B00FD7C23 /* [email protected] */ = {isa = PBXFileReference; lastKnownFileType = image.png; path = "[email protected]"; sourceTree = "<group>"; };
 		49B5BF752D43E1D500AB6C3F /* FinancialConnectionsAppearance.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = FinancialConnectionsAppearance.swift; sourceTree = "<group>"; };
@@ -789,6 +791,7 @@
 				49AC518B2C52DE2C00B712CC /* FinancialConnectionsLinkLoginPane.swift */,
 				6A384A832C24DD720044AB99 /* FinancialConnectionsGenericInfoScreen.swift */,
 				49F047542C63C2E5006BAD3E /* FinancialConnectionsPaymentDetails.swift */,
+				49AC00C12D7B5C90005BFD57 /* FinancialConnectionsSelectInstitution.swift */,
 			);
 			path = Models;
 			sourceTree = "<group>";
@@ -1409,6 +1412,7 @@
 				97C528CE821C6A55D58F68A4 /* ConsentFooterView.swift in Sources */,
 				8927328EE28A0C94B5AB69DB /* ConsentLogoView.swift in Sources */,
 				E9866D5CA186A242BBEA69E1 /* ConsentViewController.swift in Sources */,
+				49AC00C22D7B5C90005BFD57 /* FinancialConnectionsSelectInstitution.swift in Sources */,
 				D9D84D6FF624CF4363D87CEB /* InstitutionDataSource.swift in Sources */,
 				6D29E55F6A3864ED52799169 /* InstitutionPickerViewController.swift in Sources */,
 				C6B99A1C34886D3B5E1AF1A2 /* InstitutionSearchBar.swift in Sources */,

StripeFinancialConnections/StripeFinancialConnections/Source/API Bindings/FinancialConnectionsAPIClient.swift

@@ -189,6 +189,8 @@ protocol FinancialConnectionsAPI {
 
     func cancelAuthSession(clientSecret: String, authSessionId: String) -> Promise<FinancialConnectionsAuthSession>
 
+    func selectInstitution(clientSecret: String, institutionId: String) -> Promise<FinancialConnectionsSelectInstitution>
+
     func retrieveAuthSession(
         clientSecret: String,
         authSessionId: String
@@ -466,6 +468,18 @@ extension FinancialConnectionsAPIClient: FinancialConnectionsAPI {
         )
     }
 
+    func selectInstitution(clientSecret: String, institutionId: String) -> Promise<FinancialConnectionsSelectInstitution> {
+        let body: [String: Any] = [
+            "client_secret": clientSecret,
+            "currently_selected_institution": institutionId,
+        ]
+        return self.post(
+            resource: APIEndpointInstitutionSelected,
+            parameters: body,
+            useConsumerPublishableKeyIfNeeded: true
+        )
+    }
+
     func repairAuthSession(clientSecret: String, coreAuthorization: String) -> Promise<FinancialConnectionsRepairSession> {
         let body: [String: Any] = [
             "client_secret": clientSecret,
@@ -1317,6 +1331,7 @@ private let APIEndpointSessionReceipt = "link_account_sessions/session_receipt"
 private let APIEndpointGenerateHostedURL = "link_account_sessions/generate_hosted_url"
 private let APIEndpointConsentAcquired = "link_account_sessions/consent_acquired"
 private let APIEndpointLinkMoreAccounts = "link_account_sessions/link_more_accounts"
+private let APIEndpointInstitutionSelected = "link_account_sessions/institution_selected"
 private let APIEndpointComplete = "link_account_sessions/complete"
 private let APIEndpointFeaturedInstitutions = "connections/featured_institutions"
 private let APIEndpointSearchInstitutions = "connections/institutions"

StripeFinancialConnections/StripeFinancialConnections/Source/API Bindings/FinancialConnectionsAsyncAPIClient+Legacy.swift

@@ -103,6 +103,12 @@ extension FinancialConnectionsAsyncAPIClient: FinancialConnectionsAPI {
         }
     }
 
+    func selectInstitution(clientSecret: String, institutionId: String) -> Promise<FinancialConnectionsSelectInstitution> {
+        wrapAsyncToPromise {
+            try await self.selectInstitution(clientSecret: clientSecret, institutionId: institutionId)
+        }
+    }
+
     func repairAuthSession(clientSecret: String, coreAuthorization: String) -> Promise<FinancialConnectionsRepairSession> {
         wrapAsyncToPromise {
             try await self.repairAuthSession(clientSecret: clientSecret, coreAuthorization: coreAuthorization)

StripeFinancialConnections/StripeFinancialConnections/Source/API Bindings/FinancialConnectionsAsyncAPIClient.swift

@@ -211,6 +211,8 @@ protocol FinancialConnectionsAsyncAPI {
 
     func cancelAuthSession(clientSecret: String, authSessionId: String) async throws -> FinancialConnectionsAuthSession
 
+    func selectInstitution(clientSecret: String, institutionId: String) async throws -> FinancialConnectionsSelectInstitution
+
     func retrieveAuthSession(
         clientSecret: String,
         authSessionId: String
@@ -463,6 +465,14 @@ extension FinancialConnectionsAsyncAPIClient: FinancialConnectionsAsyncAPI {
         return try await post(endpoint: .authSessions, parameters: parameters)
     }
 
+    func selectInstitution(clientSecret: String, institutionId: String) async throws -> FinancialConnectionsSelectInstitution {
+        let parameters: [String: Any] = [
+            "client_secret": clientSecret,
+            "currently_selected_institution": institutionId,
+        ]
+        return try await post(endpoint: .selectInstitution, parameters: parameters)
+    }
+
     func repairAuthSession(clientSecret: String, coreAuthorization: String) async throws -> FinancialConnectionsRepairSession {
         let parameters: [String: Any] = [
             "client_secret": clientSecret,
@@ -1132,6 +1142,7 @@ enum APIEndpoint: String {
     case consentAcquired = "link_account_sessions/consent_acquired"
     case linkMoreAccounts = "link_account_sessions/link_more_accounts"
     case complete = "link_account_sessions/complete"
+    case selectInstitution = "link_account_sessions/institution_selected"
 
     // Connections
     case synchronize = "financial_connections/sessions/synchronize"
@@ -1180,7 +1191,7 @@ enum APIEndpoint: String {
              .authSessionsCancel, .authSessionsRetrieve, .authSessionsOAuthResults,
              .authSessionsAuthorized, .authSessionsAccounts, .authSessionsSelectedAccounts,
              .authSessionsEvents, .networkedAccounts, .shareNetworkedAccount, .paymentDetails,
-             .authSessionsRepair:
+             .authSessionsRepair, .selectInstitution:
             return true
         case .listAccounts, .sessionReceipt, .consentAcquired, .disableNetworking,
              .linkStepUpAuthenticationVerified, .linkVerified, .saveAccountsToLink,

StripeFinancialConnections/StripeFinancialConnections/Source/API Bindings/Models/FinancialConnectionsSelectInstitution.swift

@@ -0,0 +1,12 @@
+//
+//  FinancialConnectionsSelectInstitution.swift
+//  StripeFinancialConnections
+//
+//  Created by Mat Schmid on 2025-03-07.
+//
+
+import Foundation
+
+struct FinancialConnectionsSelectInstitution: Decodable {
+    let manifest: FinancialConnectionsSessionManifest
+}

StripeFinancialConnections/StripeFinancialConnections/Source/API Bindings/Models/FinancialConnectionsSessionManifest.swift

@@ -84,6 +84,7 @@ struct FinancialConnectionsSessionManifest: Decodable {
     let assignmentEventId: String?
     let businessName: String?
     let cancelUrl: String?
+    let consentAcquiredAt: String?
     let consentRequired: Bool
     let customManualEntryHandling: Bool
     let disableLinkMoreAccounts: Bool
@@ -110,10 +111,10 @@ struct FinancialConnectionsSessionManifest: Decodable {
     let skipSuccessPane: Bool?
     let stepUpAuthenticationRequired: Bool?
     let successUrl: String?
+    let theme: Theme?
 
-    private let _theme: Theme?
     var appearance: FinancialConnectionsAppearance {
-        FinancialConnectionsAppearance(from: _theme)
+        FinancialConnectionsAppearance(from: theme)
     }
 
     var shouldAttachLinkedPaymentMethod: Bool {
@@ -132,6 +133,10 @@ struct FinancialConnectionsSessionManifest: Decodable {
         appVerificationEnabled ?? false
     }
 
+    var consentAcquired: Bool {
+        !consentRequired || (consentRequired && consentAcquiredAt != nil)
+    }
+
     init(
         accountholderCustomerEmailAddress: String? = nil,
         accountholderIsLinkConsumer: Bool? = nil,
@@ -145,6 +150,7 @@ struct FinancialConnectionsSessionManifest: Decodable {
         assignmentEventId: String? = nil,
         businessName: String? = nil,
         cancelUrl: String? = nil,
+        consentAcquiredAt: String? = nil,
         consentRequired: Bool,
         customManualEntryHandling: Bool,
         disableLinkMoreAccounts: Bool,
@@ -171,7 +177,7 @@ struct FinancialConnectionsSessionManifest: Decodable {
         skipSuccessPane: Bool? = nil,
         stepUpAuthenticationRequired: Bool? = nil,
         successUrl: String? = nil,
-        _theme: FinancialConnectionsSessionManifest.Theme? = nil
+        theme: Theme? = nil
     ) {
         self.accountholderCustomerEmailAddress = accountholderCustomerEmailAddress
         self.accountholderIsLinkConsumer = accountholderIsLinkConsumer
@@ -186,6 +192,7 @@ struct FinancialConnectionsSessionManifest: Decodable {
         self.businessName = businessName
         self.cancelUrl = cancelUrl
         self.consentRequired = consentRequired
+        self.consentAcquiredAt = consentAcquiredAt
         self.customManualEntryHandling = customManualEntryHandling
         self.disableLinkMoreAccounts = disableLinkMoreAccounts
         self.displayText = displayText
@@ -211,50 +218,6 @@ struct FinancialConnectionsSessionManifest: Decodable {
         self.skipSuccessPane = skipSuccessPane
         self.stepUpAuthenticationRequired = stepUpAuthenticationRequired
         self.successUrl = successUrl
-        self._theme = _theme
-    }
-
-    // MARK: - Coding Keys
-
-    enum CodingKeys: String, CodingKey {
-        case accountholderCustomerEmailAddress
-        case accountholderIsLinkConsumer
-        case accountholderPhoneNumber
-        case accountholderToken
-        case accountDisconnectionMethod
-        case activeAuthSession
-        case activeInstitution
-        case allowManualEntry
-        case appVerificationEnabled
-        case assignmentEventId
-        case businessName
-        case cancelUrl
-        case consentRequired
-        case customManualEntryHandling
-        case disableLinkMoreAccounts
-        case displayText
-        case experimentAssignments
-        case features
-        case hostedAuthUrl
-        case id
-        case initialInstitution
-        case instantVerificationDisabled
-        case institutionSearchDisabled
-        case isEndUserFacing
-        case isLinkWithStripe
-        case isNetworkingUserFlow
-        case isStripeDirect
-        case livemode
-        case manualEntryMode
-        case manualEntryUsesMicrodeposits
-        case nextPane
-        case paymentMethodType
-        case permissions
-        case product
-        case singleAccount
-        case skipSuccessPane
-        case stepUpAuthenticationRequired
-        case successUrl
-        case _theme = "theme"
+        self.theme = theme
     }
 }

StripeFinancialConnections/StripeFinancialConnections/Source/Native/InstitutionPicker/InstitutionDataSource.swift

@@ -17,6 +17,7 @@ protocol InstitutionDataSource: AnyObject {
     func fetchInstitutions(searchQuery: String) -> Future<FinancialConnectionsInstitutionSearchResultResource>
     func fetchFeaturedInstitutions() -> Future<[FinancialConnectionsInstitution]>
     func createAuthSession(institutionId: String) -> Future<FinancialConnectionsAuthSession>
+    func selectInstitution(institutionId: String) -> Future<FinancialConnectionsSelectInstitution>
 }
 
 class InstitutionAPIDataSource: InstitutionDataSource {
@@ -67,4 +68,11 @@ class InstitutionAPIDataSource: InstitutionDataSource {
             institutionId: institutionId
         )
     }
+
+    func selectInstitution(institutionId: String) -> Future<FinancialConnectionsSelectInstitution> {
+        return apiClient.selectInstitution(
+            clientSecret: clientSecret,
+            institutionId: institutionId
+        )
+    }
 }

StripeFinancialConnections/StripeFinancialConnections/Source/Native/InstitutionPicker/InstitutionPickerViewController.swift

@@ -20,6 +20,11 @@ protocol InstitutionPickerViewControllerDelegate: AnyObject {
         didFinishSelecting institution: FinancialConnectionsInstitution,
         authSession: FinancialConnectionsAuthSession
     )
+    func institutionPickerViewController(
+        _ viewController: InstitutionPickerViewController,
+        didFinishSelecting institution: FinancialConnectionsInstitution,
+        manifest: FinancialConnectionsSessionManifest
+    )
     func institutionPickerViewControllerDidSelectManuallyAddYourAccount(
         _ viewController: InstitutionPickerViewController
     )
@@ -180,6 +185,23 @@ class InstitutionPickerViewController: UIViewController {
             exceptForInstitution: institution
         )
 
+        // If consent is already acquired, create an auth session.
+        // Otherwise, select the institution and update the manifest.
+        if dataSource.manifest.consentAcquired {
+            createAuthSession(institution) {
+                showLoadingView(false)
+            }
+        } else {
+            selectInstitution(institution) {
+                showLoadingView(false)
+            }
+        }
+    }
+
+    private func createAuthSession(
+        _ institution: FinancialConnectionsInstitution,
+        completion: @escaping () -> Void
+    ) {
         dataSource.createAuthSession(institutionId: institution.id)
             .observe { [weak self] result in
                 guard let self else { return }
@@ -204,7 +226,32 @@ class InstitutionPickerViewController: UIViewController {
                         didReceiveError: error
                     )
                 }
-                showLoadingView(false)
+                completion()
+            }
+    }
+
+    private func selectInstitution(
+        _ institution: FinancialConnectionsInstitution,
+        completion: @escaping () -> Void
+    ) {
+        dataSource.selectInstitution(institutionId: institution.id)
+            .observe { [weak self] result in
+                guard let self else { return }
+                switch result {
+                case .success(let synchronizePayload):
+                    self.delegate?.institutionPickerViewController(
+                        self,
+                        didFinishSelecting: institution,
+                        manifest: synchronizePayload.manifest
+                    )
+                    self.hideOverlayView()
+                case .failure(let error):
+                    self.delegate?.institutionPickerViewController(
+                        self,
+                        didReceiveError: error
+                    )
+                }
+                completion()
             }
     }
 

StripeFinancialConnections/StripeFinancialConnections/Source/Native/NativeFlowController.swift

@@ -745,7 +745,6 @@ extension NativeFlowController: ConsentViewControllerDelegate {
 // MARK: - InstitutionPickerViewControllerDelegate
 
 extension NativeFlowController: InstitutionPickerViewControllerDelegate {
-
     func institutionPickerViewController(
         _ viewController: InstitutionPickerViewController,
         didSelect institution: FinancialConnectionsInstitution
@@ -778,6 +777,26 @@ extension NativeFlowController: InstitutionPickerViewControllerDelegate {
         }
     }
 
+    func institutionPickerViewController(
+        _ viewController: InstitutionPickerViewController,
+        didFinishSelecting institution: FinancialConnectionsInstitution,
+        manifest: FinancialConnectionsSessionManifest
+    ) {
+        delegate?.nativeFlowController(
+            self,
+            didReceiveEvent: FinancialConnectionsEvent(
+                name: .institutionSelected,
+                metadata: FinancialConnectionsEvent.Metadata(
+                    institutionName: institution.name
+                )
+            )
+        )
+        dataManager.institution = institution
+        dataManager.manifest = manifest
+
+        pushPane(manifest.nextPane, animated: true)
+    }
+
     func institutionPickerViewControllerDidSelectManuallyAddYourAccount(
         _ viewController: InstitutionPickerViewController
     ) {

StripeFinancialConnections/StripeFinancialConnections/Source/Native/Shared/NetworkingOTPView/NetworkingOTPView.swift

@@ -245,7 +245,7 @@ private struct NetowrkingOTPViewRepresentable: UIViewRepresentable {
                 permissions: [],
                 product: "product",
                 singleAccount: true,
-                _theme: theme
+                theme: theme
             ),
             customEmailType: nil,
             connectionsMerchantName: nil,