deprecated start auth flow request method as opposed to breaking change

Author: dili91

CHANGELOG.md

@@ -5,14 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
-## [18.0.0] - 2025-x-x
+## [17.6.0] - 2025-x-x
 ### Added 
+* New ProviderSelection builder method on the StartAuthorizationFlowRequest builder
 * New Icon object to ProviderSelection in authorization flow requests
 * New Consent type properties within the authorization flow request
 
 ### Changed
-* ⚠️ Breaking: replaced the `withProviderSelection()` flag on authorization flow request builder with a `providerSelection(...)` utility
-that helps to set the provider icon object if needed
+* ⚠️ Deprecated `withProviderSelection()` flag on authorization flow request builder
 * Various dependency updates
 
 ## [17.5.1] - 2025-10-31

src/main/java/com/truelayer/java/payments/entities/StartAuthorizationFlowRequest.java

@@ -8,7 +8,7 @@
 import lombok.*;
 
 @Getter
-@Builder
+@RequiredArgsConstructor
 @ToString
 @EqualsAndHashCode
 public class StartAuthorizationFlowRequest {
@@ -25,11 +25,85 @@ public class StartAuthorizationFlowRequest {
 
     private final Map<String, String> userAccountSelection;
 
+    public static StartAuthorizationFlowRequestBuilder builder() {
+        return new StartAuthorizationFlowRequestBuilder();
+    }
+
+    // TODO: remove in future major version, as we will no longer support empty provider selection
+    public static class StartAuthorizationFlowRequestBuilder {
+        private boolean withProviderSelection;
+
+        private ProviderSelection providerSelection;
+
+        private Map<String, String> schemeSelection;
+
+        private Redirect redirect;
+
+        private Consent consent;
+
+        private Form form;
+
+        private Map<String, String> userAccountSelection;
+
+        /**
+         * Include an empty provider selection object in the request
+         * @deprecated use providerSelection(ProviderSelection) instead
+         * @return the builder object
+         */
+        @Deprecated
+        public StartAuthorizationFlowRequestBuilder withProviderSelection() {
+            this.withProviderSelection = true;
+            return this;
+        }
+
+        public StartAuthorizationFlowRequestBuilder providerSelection(ProviderSelection providerSelection) {
+            this.providerSelection = providerSelection;
+            return this;
+        }
+
+        public StartAuthorizationFlowRequestBuilder schemeSelection(Map<String, String> schemeSelection) {
+            this.schemeSelection = schemeSelection;
+            return this;
+        }
+
+        public StartAuthorizationFlowRequestBuilder redirect(Redirect redirect) {
+            this.redirect = redirect;
+            return this;
+        }
+
+        public StartAuthorizationFlowRequestBuilder consent(Consent consent) {
+            this.consent = consent;
+            return this;
+        }
+
+        public StartAuthorizationFlowRequestBuilder form(Form form) {
+            this.form = form;
+            return this;
+        }
+
+        public StartAuthorizationFlowRequestBuilder userAccountSelection(Map<String, String> userAccountSelection) {
+            this.userAccountSelection = userAccountSelection;
+            return this;
+        }
+
+        public StartAuthorizationFlowRequest build() {
+            if (withProviderSelection && providerSelection == null) {
+                providerSelection = new ProviderSelection();
+            }
+
+            return new StartAuthorizationFlowRequest(
+                    providerSelection, schemeSelection, redirect, consent, form, userAccountSelection);
+        }
+    }
+
     @Builder
     @ToString
     @EqualsAndHashCode
+    @AllArgsConstructor
     public static class ProviderSelection {
-        private final Icon icon;
+        private Icon icon;
+
+        public ProviderSelection() {}
 
         @NoArgsConstructor
         @AllArgsConstructor

src/test/java/com/truelayer/java/acceptance/PaymentsAcceptanceTests.java

@@ -448,6 +448,45 @@ public void shouldCompleteAnAuthorizationFlowForAPaymentWithPreselectedProvider(
         assertCanBrowseLink(bankPage);
     }
 
+    @SneakyThrows
+    @Test
+    @Deprecated
+    @DisplayName(
+            "It should complete an authorization flow for a payment with a preselected provider with deprecated provider selection method")
+    public void shouldCompleteAnAuthorizationFlowForAPaymentWithPreselectedProviderDeprecatedProviderSelection() {
+        // create payment
+        CreatePaymentRequest paymentRequest =
+                buildPaymentRequestWithProviderSelection(buildPreselectedProviderSelection(), CurrencyCode.GBP);
+
+        ApiResponse<CreatePaymentResponse> createPaymentResponse =
+                tlClient.payments().createPayment(paymentRequest).get();
+
+        assertNotError(createPaymentResponse);
+        assertTrue(createPaymentResponse.getData().isAuthorizationRequired());
+
+        // start the auth flow
+        StartAuthorizationFlowRequest startAuthorizationFlowRequest = StartAuthorizationFlowRequest.builder()
+                .redirect(Redirect.builder().returnUri(URI.create(RETURN_URI)).build())
+                .withProviderSelection()
+                .build();
+        ApiResponse<AuthorizationFlowResponse> startAuthorizationFlowResponse = tlClient.payments()
+                .startAuthorizationFlow(createPaymentResponse.getData().getId(), startAuthorizationFlowRequest)
+                .get();
+
+        assertNotError(startAuthorizationFlowResponse);
+
+        // assert that the link returned is good to be browsed
+        URI bankPage = startAuthorizationFlowResponse
+                .getData()
+                .asAuthorizing()
+                .getAuthorizationFlow()
+                .getActions()
+                .getNext()
+                .asRedirect()
+                .getUri();
+        assertCanBrowseLink(bankPage);
+    }
+
     @SneakyThrows
     @Test
     @DisplayName("It should complete an authorization flow for a payment with provider return")