Migration guide for v23

• This release changes the pinned API version to 2023-08-16. Please read the API Upgrade Guide and carefully review the API changes before upgrading stripe-java.

"⚠️" symbol highlights breaking changes.

StripeClient

Introduces StripeClient and the service-based pattern, a new interface for calling the Stripe API with many benefits over the existing resource-based paradigm:

• No global config: you can simultaneously use multiple clients with different configuration options (such as API keys)
• No extra API calls. All API endpoints can be accessed with a single method call. You don't have to call retrieve before doing an update.
• No static methods. Much easier mocking.

While there are no plans yet to completely remove the previous resource-based call pattern, it will be deprecated soon and new API endpoints will be supported only in the new pattern. We strongly recommend migrating to the new service-based pattern as you begin to use new APIs. This will help you avoid mixing the two patterns in your integration, which can lead to confusion as you maintain your code.

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. XxxParams 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");

4. Convert XxxCollection method calls to to StripeClient calls. In these cases XxxParams classes will change from XxxCollectionParams to XxxPrams. Note: StripeClient always returns StripeCollection<Xxx> instead of XxxCollection and all methods that were available on XxxCollection are accessible thought StripeClient.

   // Before
   Account resource = Account.retrieve("acct_xxxxxxxxxxxxx");
   CapabilityCollection capabilities = resource.capabilities();
   CapabilityCollectionRetrieveParams params = CapabilityCollectionRetrieveParams.builder()
          .addExpand("account")
          .build();
   capabilities.retrieve("cap_123", params, null);
   
   // After
   CapabilityRetrieveParams params = CapabilityRetrieveParams.builder()
         .addExpand("account")
         .build();
   client.accounts().capabilities().retrieve("acct_xxxxxxxxxxxxx", "cap_123", params);

5. Convert nested resource operations to StripeClient calls:

   // Before
   Customer resource = Customer.retrieve("cus_xxxxxxxxxxxxx");
   CustomerBalanceTransactionCollection collection = resource.balanceTransactions();
    
   // After
   StripeCollection<CustomerBalanceTransaction> customer = client.
           customers().balanceTransactions().list("cus_xxxxxxxxxxxxx");

Type changes

• ⚠️ 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.
• ⚠️ RequestOptions.getReadTimeout(), getConnectTimeout(), getMaxNetworkRetries() now return Integer instead of int.

Removals, deprecations and renames

• ⚠️Remove support for values custom_account_update and custom_account_verification from enum AccountLinkCreateParams.type
  • These values are not fully operational. Please use account_update and account_onboarding instead (see API reference).
• ⚠️Remove support for available_on on BalanceTransactionListParams
  • Use of this parameter is discouraged. You may use .putExtraParam if sending the parameter is still required.
• ⚠️Remove support for alternate_statement_descriptors, destination, and dispute on Charge
  • Use of these fields is discouraged.
• ⚠️Remove support for shipping_rates on checkout.SessionCreateParams
• ⚠️Remove support for shipping_rates on checkout.SessionCreateParams
  • Please use shipping_options instead.
• ⚠️Remove support for coupon and trial_from_plan on checkout.SessionCreateParams.subscription_data
  • Please migrate to the Prices API, or use .putExtraParam if sending the parameter is still required.
• ⚠️Remove support for value card_present from enums CustomerListPaymentMethodsParams.type and PaymentMethodListParams.type
  • This value was not fully operational.
• ⚠️Remove support for blik on Mandate.payment_method_details, PaymentMethodUpdateParams, SetupAttempt.payment_method_details, SetupIntent.payment_method_options, SetupIntentConfirmParams.payment_method_options, SetupIntentCreateParams.payment_method_options, and SetupIntentUpdateParams.payment_method_options
  • These fields were mistakenly released.
• ⚠️Remove support for acss_debit, affirm, au_becs_debit, bacs_debit, cashapp, sepa_debit, and zip on PaymentMethodUpdateParams
  • These fields are empty.
• ⚠️Remove support for country on PaymentMethod.link
  • This field was not fully operational.
• ⚠️Remove support for recurring on PriceUpdateParams
  • This property should be set on create only.
• ⚠️Remove support for attributes, caption, and deactivate_on on ProductCreateParams, ProductUpdateParams, and Product
  • These fields are not fully operational.
  • ⚠️ addFullNameAliase renamed to addFullNameAlias in AccountCreateParams, AccountUpdateParams, PersonCollectionCreateParams, TokenCreateParams, PersonCollectionCreateParams, PersonUpdateParams.
  • ⚠️ addLookupKeys renamed to addLookupKey in PriceListParams
• Behavior Changes
  • ⚠️ 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.
• ⚠️ ApiResource.request(), requestStream(), requestCollection(), requestSearchResult() methods removed. * ⚠️ StripeResponseGetter.oauthRequest(...) was removed. OAuth requests are now performed via StripeResponseGetter.request with ApiMode.OAuth. * ⚠️ Deprecated ApiResource.className() singleClassUrl(), classUrl(), instanceUrl(), subresourceUrl() methods removed.