Add setHttpClient to StripeClientBuilder; clean up apiKey/authenticator coupling (#2182)

* Clean up apiKey/authenticator coupling

* Add setHttpClient to StripeClientBuilder

Allow users to provide a custom HttpClient implementation when building
a StripeClient, rather than always using the default
HttpURLConnectionClient. This is useful for testing and for integrating
alternative HTTP libraries.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Committed-By-Agent: claude

* Fix fomatting

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: mbroshi-stripe

src/main/java/com/stripe/StripeClient.java

@@ -1048,6 +1048,7 @@ public static final class StripeClientBuilder {
     private String meterEventsBase = Stripe.METER_EVENTS_API_BASE;
     private String stripeAccount;
     private String stripeContext;
+    private HttpClient httpClient;
 
     /**
      * Constructs a request options builder with the global parameters (API key and client ID) as
@@ -1059,19 +1060,29 @@ public Authenticator getAuthenticator() {
       return this.authenticator;
     }
 
+    /**
+     * Sets the authenticator used to authorize requests. Use this for custom authentication
+     * strategies. For standard API key authentication, prefer {@link #setApiKey(String)}.
+     *
+     * <p>This shares a backing field with {@link #setApiKey(String)} — calling one overwrites the
+     * other.
+     *
+     * @param authenticator the authenticator to use
+     */
     public StripeClientBuilder setAuthenticator(Authenticator authenticator) {
       this.authenticator = authenticator;
       return this;
     }
 
-    public String getApiKey() {
-      if (authenticator instanceof BearerTokenAuthenticator) {
-        return ((BearerTokenAuthenticator) authenticator).getApiKey();
-      }
-
-      return null;
-    }
-
+    /**
+     * Sets the API key for bearer token authentication. This is a convenience method equivalent to
+     * calling {@code setAuthenticator(new BearerTokenAuthenticator(apiKey))}.
+     *
+     * <p>This shares a backing field with {@link #setAuthenticator(Authenticator)} — calling one
+     * overwrites the other.
+     *
+     * @param apiKey the API key; if null, clears the authenticator
+     */
     public StripeClientBuilder setApiKey(String apiKey) {
       if (apiKey == null) {
         this.authenticator = null;
@@ -1179,7 +1190,8 @@ public StripeClientBuilder setProxyCredential(PasswordAuthentication proxyCreden
      * Set the base URL for the Stripe API. By default this is "https://api.stripe.com".
      *
      * <p>This only affects requests made with a {@link com.stripe.net.BaseAddress} of API. Use
-     * {@link setFilesBase} or {@link setConnectBase} to interpect requests with other bases.
+     * {@link #setFilesBase}, {@link #setConnectBase} or {@link #setMeterEventsBase} to interpect
+     * requests with other bases.
      */
     public StripeClientBuilder setApiBase(String address) {
       this.apiBase = address;
@@ -1256,9 +1268,23 @@ public String getStripeContext() {
       return this.stripeContext;
     }
 
+    /**
+     * Sets the HTTP client to use for making requests to the Stripe API. If not set, a default
+     * {@link HttpURLConnectionClient} will be created.
+     *
+     * <p>This is useful for providing a custom HTTP client implementation, e.g. for testing or for
+     * using a different HTTP library.
+     *
+     * @param httpClient the HTTP client to use
+     */
+    public StripeClientBuilder setHttpClient(HttpClient httpClient) {
+      this.httpClient = httpClient;
+      return this;
+    }
+
     /** Constructs a {@link StripeResponseGetterOptions} with the specified values. */
     public StripeClient build() {
-      return new StripeClient(new LiveStripeResponseGetter(buildOptions(), null));
+      return new StripeClient(new LiveStripeResponseGetter(buildOptions(), this.httpClient));
     }
 
     StripeResponseGetterOptions buildOptions() {

src/main/java/com/stripe/net/Authenticator.java

@@ -2,7 +2,16 @@
 
 import com.stripe.exception.StripeException;
 
-/** * Represents a request authentication mechanism. */
+/**
+ * Interface for applying authentication to a request. This is used by {@link StripeResponseGetter}
+ * to apply authentication to requests before they are sent. Implementations of this interface
+ * should not modify the request in-place, but should instead return a new request with the
+ * appropriate authentication headers applied. The default implementation of this interface is
+ * {@link BearerTokenAuthenticator}, which applies the API key as a Bearer token in the
+ * Authorization header. Users can also implement this interface to provide custom authentication
+ * logic, often by wrapping the BearerTokenAuthenticator and applying additional headers or logic as
+ * needed.
+ */
 public interface Authenticator {
   /**
    * * Authenticate the request

src/main/java/com/stripe/net/RequestOptions.java

@@ -85,14 +85,6 @@ public Authenticator getAuthenticator() {
     return this.authenticator;
   }
 
-  public String getApiKey() {
-    if (authenticator instanceof BearerTokenAuthenticator) {
-      return ((BearerTokenAuthenticator) authenticator).getApiKey();
-    }
-
-    return null;
-  }
-
   public String getClientId() {
     return clientId;
   }
@@ -210,19 +202,29 @@ public Authenticator getAuthenticator() {
       return this.authenticator;
     }
 
+    /**
+     * Sets the authenticator used to authorize requests. Use this for custom authentication
+     * strategies. For standard API key authentication, prefer {@link #setApiKey(String)}.
+     *
+     * <p>This shares a backing field with {@link #setApiKey(String)} — calling one overwrites the
+     * other.
+     *
+     * @param authenticator the authenticator to use
+     */
     public RequestOptionsBuilder setAuthenticator(Authenticator authenticator) {
       this.authenticator = authenticator;
       return this;
     }
 
-    public String getApiKey() {
-      if (authenticator instanceof BearerTokenAuthenticator) {
-        return ((BearerTokenAuthenticator) authenticator).getApiKey();
-      }
-
-      return null;
-    }
-
+    /**
+     * Sets the API key for bearer token authentication. This is a convenience method equivalent to
+     * calling {@code setAuthenticator(new BearerTokenAuthenticator(apiKey))}.
+     *
+     * <p>This shares a backing field with {@link #setAuthenticator(Authenticator)} — calling one
+     * overwrites the other.
+     *
+     * @param apiKey the API key; if null, clears the authenticator
+     */
     public RequestOptionsBuilder setApiKey(String apiKey) {
       if (apiKey == null) {
         this.authenticator = null;

src/test/java/com/stripe/StripeClientTest.java

@@ -303,6 +303,23 @@ public void parsesUnknownEventNotification()
     assertInstanceOf(Event.class, e.fetchEvent());
   }
 
+  @Test
+  public void builderUsesProvidedHttpClient() throws StripeException {
+    HttpClient customHttpClient = Mockito.spy(new HttpURLConnectionClient());
+
+    StripeClient client =
+        StripeClient.builder()
+            .setApiKey(TEST_API_KEY)
+            .setApiBase(getStripeMockUrl())
+            .setHttpClient(customHttpClient)
+            .build();
+
+    client.customers().create();
+
+    ArgumentCaptor<StripeRequest> requestCaptor = ArgumentCaptor.forClass(StripeRequest.class);
+    Mockito.verify(customHttpClient, Mockito.atLeastOnce()).request(requestCaptor.capture());
+  }
+
   @Test
   public void stripeClientWithStripeAccount() throws StripeException {
 

src/test/java/com/stripe/model/PagingIteratorTest.java

@@ -343,7 +343,9 @@ public void testAutoPaginationRequestOptionsPropagation() throws StripeException
     Stripe.apiKey = null;
     final PageableModelCollection collection =
         PageableModel.list(page0Params, RequestOptions.builder().setApiKey("sk_test_xyz").build());
-    assertEquals(collection.getRequestOptions().getApiKey(), "sk_test_xyz");
+    assertEquals(
+        new BearerTokenAuthenticator("sk_test_xyz"),
+        collection.getRequestOptions().getAuthenticator());
     final List<PageableModel> models = new ArrayList<>();
 
     for (PageableModel model : collection.autoPagingIterable()) {

src/test/java/com/stripe/model/SearchPagingIteratorTest.java

@@ -235,7 +235,9 @@ public void testAutoPaginationRequestOptionsPropagation() throws StripeException
     final SearchableModelCollection collection =
         SearchableModel.search(
             page0Params, RequestOptions.builder().setApiKey("sk_test_xyz").build());
-    assertEquals(collection.getRequestOptions().getApiKey(), "sk_test_xyz");
+    assertEquals(
+        new BearerTokenAuthenticator("sk_test_xyz"),
+        collection.getRequestOptions().getAuthenticator());
     final List<SearchableModel> models = new ArrayList<>();
 
     for (SearchableModel model : collection.autoPagingIterable()) {

src/test/java/com/stripe/net/RequestOptionsTest.java

@@ -34,7 +34,7 @@ public void testPersistentValuesInToBuilder() {
 
     // only api keys and account should persist
     // assuming these are stable across a given stripe integration
-    assertEquals("sk_foo", optsRebuilt.getApiKey());
+    assertEquals(new BearerTokenAuthenticator("sk_foo"), optsRebuilt.getAuthenticator());
     assertEquals("acct_bar", optsRebuilt.getStripeAccount());
 
     assertNull(optsRebuilt.getClientId());
@@ -158,7 +158,7 @@ public void mergeOverwritesClientOptions() {
             .build();
 
     RequestOptions merged = RequestOptions.merge(clientOptions, requestOptions);
-    assertEquals("key2", merged.getApiKey());
+    assertEquals(new BearerTokenAuthenticator("key2"), merged.getAuthenticator());
     assertEquals(3, merged.getConnectTimeout());
     assertEquals(4, merged.getMaxNetworkRetries());
     assertEquals(5, merged.getReadTimeout());
@@ -242,7 +242,7 @@ public void mergeFallsBackToClientOptions() {
     RequestOptions requestOptions = RequestOptions.builder().build();
 
     RequestOptions merged = RequestOptions.merge(clientOptions, requestOptions);
-    assertEquals("key1", merged.getApiKey());
+    assertEquals(new BearerTokenAuthenticator("key1"), merged.getAuthenticator());
     assertEquals(1, merged.getConnectTimeout());
     assertEquals(1, merged.getMaxNetworkRetries());
     assertEquals(1, merged.getReadTimeout());
@@ -257,7 +257,7 @@ public void mergeFallsBackToClientOptions() {
   @Test
   public void defaultsToAllNullValues() {
     RequestOptions merged = RequestOptions.getDefault();
-    assertEquals(null, merged.getApiKey());
+    assertNull(merged.getAuthenticator());
     assertEquals(null, merged.getConnectTimeout());
     assertEquals(null, merged.getMaxNetworkRetries());
     assertEquals(null, merged.getReadTimeout());