Migration guide for v23

StripeClient

StripeClient and the new service-based pattern is introduced. StripeClient has multiple benefits over existing resource-based patterns:

1. Allows to have multiple clients with different connection options (different API keys).
2. All operations can be performed in a single HTTP call.

   // Before: creating funding instructions takes two HTTP calls
   Customer customer = Customer.retrieve("cus_123"); // HTTP call 1
   customer.createFundingInstructions(..); // HTTP call 2
   
   // After: creating funding instructions is a single HTTP call
   StripeClient client = new StripeClient();
   client.customers().createFundingInstructions("cus_123", ...); // HTTP call 1

3. StripeClient is easier to mock for testing as all methods are instance methods.

Migration

To migrate from resource-based to service-based pattern:

1. Initialize a StripeClient instance.

   // Before
   Stripe.apiKey = "sk_test_123"
   
   // After
   StripeClient client = new StripeClient("sk_test_123");

2. Convert static resource method calls to StripeClient calls:

   // Before
   Customer customer = Customer.retrieve("cus_123");
   
   // After
   client.customers().retrieve("cus_123");

3. Convert instance resource method calls to StripeClient calls. Params classes will, in most cases, stay the same as you used for resource-based calls.

   // Before
   Customer customer = Customer.retrive("cus_123");
   customer.delete();
   
   // After
   client.customers().delete("cus_123");
   
   // After
   client.customers().delete(customer.id);
   PaymentMethod pm = client.customers().retrievePaymentMethod(customer.id, "pm_123");

Breaking changes

• RequestOptions.getReadTimeout(), getConnectTimeout(), getMaxNetworkRetries() now return Integer instead of int.
• RequestOptions.getDefault() does not apply global configuration options from Stripe class, all fields are initialized to null.
• RequestOptionsBuilder does not apply global configuration options from Stripe class, all fields are initialized to null.
• StripeResponseGetter.oauthRequest(...) was removed. OAuth requests are now performed via StripeResponseGetter.request with ApiMode.OAuth.
• StripeResponseGetter.request(...), streamRequest(...) signatures changed.
  • BaseAddress parameter added.
  • url renamed to path and is a relative to the base address
  • apiMode parameter added to control how request is sent and response is handled, V1 and OAuth are supported values.
• Deprecated ApiResource.className() singleClassUrl(), classUrl(), instanceUrl(), subresourceUrl() methods removed.
• ApiResource.request(), requestStream(), requestCollection(), requestSearchResult() methods removed.