[Feature] Expose `STPPaymentHandler` Initializer to configure APIClient dynamically

[woohyunjin06]

Is your feature request related to a problem? Please describe.

Our app supports multiple regions, and each region requires a different Stripe publishableKey.
To support this, we need to configure STPAPIClient dynamically at runtime.

In the case of Apple Pay, we’re able to set STPApplePayContext.apiClient after initialization.

let context = STPApplePayContext(
  paymentRequest: paymentRequest,
  delegate: delegate
)
context?.apiClient = STPAPIClient(publishableKey: publishableKey)

However, during the confirm setup intent flow, we need to inject a new STPAPIClient with a different publishableKey into STPPaymentHandler.
The problem is that STPPaymentHandler does not expose a public initializer, so we can’t pass in a custom API client.

We’re using @_spi(STP) import Stripe to access the internal initializer, which works — but is it OK to use in production for now?

Describe the solution you'd like

We’d like the initializer for STPPaymentHandler that accepts a custom STPAPIClient to be made public

Describe alternatives you've considered

• Relying on @_spi(STP) access
• Mutating STPPaymentHandler.shared().apiClient, which is unsafe in concurrent scenarios.

[wooj-stripe]

Hi @woohyunjin06,

Thank you for the suggestion! We revisit our roadmap periodically and will keep this idea in mind. It sounds like you need support for having two instances of STPAPIClient with different publishable keys, simultaneously? Can we know a little bit more about your use case and why it isn't okay to mutate STPPaymentHandler.shared().apiClient when you need to switch publishable keys?

In general, we don't recommend relying on @_spi(STP) access as APIs can change and may cause breaking changes between versions. That being said, it does seem like a reasonable work around in the short term.

[woohyunjin06]

Hi @wooj-stripe,

We fetch the publishableKey from our server based on the user’s current location.
In practice, we don’t have two publishableKeys in use simultaneously, so it would be possible to mutate STPPaymentHandler.shared().apiClient.

However, we’d prefer a session-like approach — creating a new STPAPIClient for each request and disposing of it afterwards, rather than mutating a shared instance.
This is the same approach we’ve been using for our Apple Pay integration, and we wanted to apply a consistent pattern to the Confirm Setup Intent flow as well.

[wooj-stripe]

Makes sense that is what you prefer! Thanks for taking the time to explain your integration! Unfortunately, I don't have a timeline, but will update this thread with any updates.