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.

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.