Stripe Java

https://github.com/stripe/stripe-java
Admin
The official Stripe Java client library provides a convenient way for Java developers to integrate...
Tokens:32,389
Snippets:225
Trust Score:9.7
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Create a Customer with StripeClient

Source: https://github.com/stripe/stripe-java/blob/master/README.md

Example of creating a customer using the StripeClient class. It demonstrates building CustomerCreateParams and calling client.v1().customers().create(params). The example uses a test secret key and a test payment method.

```java
import java.util.HashMap;
import java.util.Map;

import com.stripe.StripeClient;
import com.stripe.exception.StripeException;
import com.stripe.model.Customer;
import com.stripe.net.RequestOptions;
import com.stripe.param.CustomerCreateParams;

public class StripeExample {

    public static void main(String[] args) {
        StripeClient client = new StripeClient("sk_test_...");
        CustomerCreateParams params =
            CustomerCreateParams
                .builder()
                .setDescription("Example description")
                .setEmail("test@example.com")
                .setPaymentMethod("pm_card_visa")  // obtained via Stripe.js
                .build();

        try {
            Customer customer = client.v1().customers().create(params);
            System.out.println(customer);
        } catch (StripeException e) {
            e.printStackTrace();
        }
    }
}
```

--------------------------------

### V2 Amount type consolidation: before and after

Source: https://github.com/stripe/stripe-java/wiki/Migration-guide-for-v32

Shows the migration from per-field Amount classes to the shared com.stripe.v2.Amount type. The before example imports the old per-field class; the after example uses the new shared type with identical value and currency fields.

```java
import com.stripe.model.v2.core.Account;
Account.Identity.BusinessDetails.AnnualRevenue.Amount amount =
    account.getIdentity().getBusinessDetails().getAnnualRevenue().getAmount();
```

```java
import com.stripe.v2.Amount;
Amount amount = account.getIdentity().getBusinessDetails().getAnnualRevenue().getAmount();
System.out.println(amount.getValue());    // long
System.out.println(amount.getCurrency()); // String, e.g. "usd"
```

--------------------------------

### Setting V2 decimal params (Before) - String

Source: https://github.com/stripe/stripe-java/wiki/Migration-guide-for-v32

Before v32, V2 decimal params like percentOwnership were set as String. This example shows the old way using setPercentOwnership("75.25").

```java
AccountCreateParams params = AccountCreateParams.builder()
    .setIdentity(AccountCreateParams.Identity.builder()
        .setIndividual(AccountCreateParams.Identity.Individual.builder()
            .setRelationship(AccountCreateParams.Identity.Individual.Relationship.builder()
                .setPercentOwnership("75.25")  // was String
                .build())
            .build())
        .build())
    .build();
```

--------------------------------

### Reading V2 decimal responses (Before) - String

Source: https://github.com/stripe/stripe-java/wiki/Migration-guide-for-v32

Before v32, reading a V2 decimal field returned a String. This example shows the old way of reading percentOwnership as String and converting to BigDecimal.

```java
String pctString = account.getIdentity().getIndividual().getRelationship().getPercentOwnership();
BigDecimal pct = new BigDouble(pctString);
```

--------------------------------

### Illustration of schema incompatibility failure with JSON example

Source: https://github.com/stripe/stripe-java/wiki/Migration-guide-for-v8----version-upgrade

This JSON example shows an event with an old API version (2012-09-24) where the 'lines' field is an array instead of a paginated collection, causing deserialization failure with recent Java model classes. It illustrates why backward compatibility is needed.

```json5
{
  "id": "evt_123",
  "object": "event",
  "api_version": "2012-09-24",
  "created": 1549056424,
  "data": {
    "object": { // event data object of rendered at `api_version`
      "id": "in_1DwEmi2eZvKYlo2C5EbZEeaM",
      "object": "invoice", // tells deseiralizer this object should be `Invoice`
      "amount_due": 999,
      "amount_paid": 0,
      "lines": [ // not the paginated collection object as in recent API versions
        {
          "id": "sli_fde81ddce855c9",
          "object": "line_item",
          "amount": 999,
          "type": "subscription"
        }
      ],
      "status": "draft"
    }
  },
  "livemode": false,
  "pending_webhooks": 0,
  "request": {
    "id": null,
    "idempotency_key": null
  },
  "type": "invoice.updated"
}
```

--------------------------------

### Mock HTTP client with Mockito for request mocking

Source: https://github.com/stripe/stripe-java/wiki/Migration-guide-for-v17

Demonstrates using Mockito to mock HttpClient and StripeResponseGetter for testing, allowing you to simulate API responses without a real HTTP call. The example mocks a request to return a StripeResponse with a JSON body, then retrieves a Charge.

```java
HttpClient httpClient = Mockito.mock(
    HttpClient.class,
    withSettings().useConstructor().defaultAnswer(Mockito.CALLS_REAL_METHODS));
StripeResponseGetter srg = new LiveStripeResponseGetter(myClient);
ApiResource.setStripeResponseGetter(srg);

HttpHeaders emptyHeaders = HttpHeaders.of(Collections.emptyMap());
String json = "{\"id\": \"ch_123\", \"object\": \"charge\"}";

Mockito.when(this.client.request(any(StripeRequest.class)))
    .thenReturn(new StripeResponse(200, emptyHeaders, json));

Charge charge = Charge.retrieve("ch_123");
```

--------------------------------

### Reading V2 decimal responses (After) - BigDecimal

Source: https://github.com/stripe/stripe-java/wiki/Migration-guide-for-v32

After v32, reading a V2 decimal field returns a BigDecimal directly. This example shows the new way of reading percentOwnership.

```java
BigDecimal pct = account.getIdentity().getIndividual().getRelationship().getPercentOwnership();
```

--------------------------------

### Setting V2 decimal params (After) - BigDecimal

Source: https://github.com/stripe/stripe-java/wiki/Migration-guide-for-v32

After v32, V2 decimal params like percentOwnership must be set as BigDecimal. This example shows the new way using new BigDecimal("75.25").

```java
import java.math.BigDecimal;

AccountCreateParams params = AccountCreateParams.builder()
    .setIdentity(AccountCreateParams.Identity.builder()
        .setIndividual(AccountCreateParams.Identity.Individual.builder()
            .setRelationship(AccountCreateParams.Identity.Individual.Relationship.builder()
                .setPercentOwnership(new BigDecimal("75.25"))  // now BigDecimal
                .build())
            .build())
        .build())
    .build();
```

--------------------------------

### Pass undocumented parameters with putExtraParam

Source: https://github.com/stripe/stripe-java/blob/master/README.md

Use putExtraParam() on a request parameter builder to send undocumented parameters to Stripe. This example shows setting email and extra secret parameters before creating a customer.

```java
CustomerCreateParams params =
  CustomerCreateParams.builder()
    .setEmail("jenny.rosen@example.com")
    .putExtraParam("secret_feature_enabled", "true")
    .putExtraParam("secret_parameter[primary]", "primary value")
    .putExtraParam("secret_parameter[secondary]", "secondary value")
    .build();

client.v1().customers().create(params);
```

--------------------------------

### Replace StripeResponse.headers().get() with firstValue().orElse()

Source: https://github.com/stripe/stripe-java/wiki/Migration-guide-for-v17

Use this snippet to access custom headers from a StripeResponse in v17. The headers() method now returns HttpHeaders instead of StripeHeaders, and get() has been replaced by firstValue().orElse().

```java
stripeResponse.headers().get("My-Header")
```

```java
stripeResponse.headers().firstValue("My-Header").orElse(null)
```

--------------------------------

### Using rawRequest to send a custom request to an undocumented API

Source: https://github.com/stripe/stripe-java/blob/master/README.md

Use this snippet to send a request to an undocumented Stripe API endpoint or to bypass the SDK's method definitions. It creates a RawRequestOptions object with a custom Stripe-Version header, makes a POST request to /v1/customers, and deserializes the response. The response body can be deserialized to a StripeObject or cast to a typed response class like Customer. Pass ApiMode.V2 if the endpoint starts with "/v2", otherwise use ApiMode.V1.

```java
// (Optional) Create a RawRequestOptions object, allowing you to set per-request
// configuration options like additional headers.
Map<String, String> stripeVersionHeader = new HashMap<>();
stripeVersionHeader.put("Stripe-Version", "2024-09-30.acacia");
RawRequestOptions options = RawRequestOptions.builder()
        .setAdditionalHeaders(stripeVersionHeader)
        .build();

// Make the request using the StripeClient.rawRequest() method.
StripeClient client = new StripeClient("sk_test_...");
final StripeResponse response =
        client.rawRequest(
                ApiResource.RequestMethod.POST, "/v1/customers", "name=johndoe&email=johndoe@example.com", options);

// (Optional) response.body() is a string. You can call
// StripeClient.deserialize() to get a StripeObject
// Pass ApiMode.V2 if the endpoint you are targeting starts with "/v2", else pass ApiMode.V1
StripeObject object = client.deserialize(response.body(), ApiMode.V1);
// or cast it if a corresponding response class exists in the SDK
Customer customer = (Customer) client.deserialize(response.body(), ApiMode.V1);
```

--------------------------------

### Retrieve undocumented properties from raw JSON

Source: https://github.com/stripe/stripe-java/blob/master/README.md

Use getRawJsonObject() on the top-level object returned by an API call to access undocumented properties as native types. This example retrieves a customer and extracts boolean and string values from the raw JSON.

```java
final Customer customer = client.v1().customers().retrieve("cus_1234");
Boolean featureEnabled =
  customer.getRawJsonObject()
    .getAsJsonPrimitive("secret_feature_enabled")
    .getAsBoolean();
String primaryValue =
  customer.getRawJsonObject()
    .getAsJsonObject("secret_parameter")
    .getAsJsonPrimitive("primary")
    .getAsString();
String secondaryValue =
  customer.getRawJsonObject()
    .getAsJsonObject("secret_parameter")
    .getAsJsonPrimitive("secondary")
    .getAsString();
```

--------------------------------

### Run tests

Source: https://github.com/stripe/stripe-java/blob/master/README.md

Run the test suite using just or Gradle.

```sh
just test
# or: ./gradlew test
```

--------------------------------

### Format code

Source: https://github.com/stripe/stripe-java/blob/master/README.md

Run the code formatter using just or Gradle.

```sh
just format
# or: ./gradlew spotlessApply
```

--------------------------------

### Initialize StripeClient with API key

Source: https://github.com/stripe/stripe-java/wiki/Migration-guide-for-v23

Shows the before/after of setting the API key. Before, the global Stripe.apiKey was set; after, a StripeClient instance is created with the key. This removes the need for global configuration.

```java
// Before
Stripe.apiKey = "sk_test_123"

// After
StripeClient client = new StripeClient("sk_test_123");
```

--------------------------------

### Per-request Configuration with RequestOptions

Source: https://github.com/stripe/stripe-java/blob/master/README.md

Shows how to use RequestOptions to set an API key, idempotency key, and Stripe account for individual requests. The options are passed to list and retrieve methods.

```java
RequestOptions requestOptions = RequestOptions.builder()
    .setApiKey("sk_test_...")
    .setIdempotencyKey("a1b2c3...")
    .setStripeAccount("acct_...")
    .build();

client.v1().customers().list(requestOptions);

client.v1().customers().retrieve("cus_123456789", requestOptions);
```

--------------------------------

### Fetch and run stripe-mock

Source: https://github.com/stripe/stripe-java/blob/master/README.md

Fetch and run stripe-mock from a background terminal. Required for the test suite.

```sh
go get -u github.com/stripe/stripe-mock
stripe-mock
```

--------------------------------

### Convert instance resource method calls to StripeClient

Source: https://github.com/stripe/stripe-java/wiki/Migration-guide-for-v23

Shows converting instance methods like customer.delete() to client.customers().delete(). Also demonstrates retrieving a payment method via the client. XxxParams classes remain mostly the same.

```java
// 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");
```

--------------------------------

### Testing migration with toMap()

Source: https://github.com/stripe/stripe-java/wiki/Migration-guide-for-v9

Shows how to compare untyped parameters with typed parameters using toMap() to ensure safe migration. This is useful for verifying that the new typed parameters produce the same map as the old untyped ones.

```java
  Map<String, Object> untypedParams = getUntypedParams();
  ApiRequestParams typedParams = getTypedParams();
  Map<String, Object> typedParamsAsMap = typedParams.toMap();
  assertEquals(untypedParams, typedParamsAsMap);
```

--------------------------------

### Builder for lists and maps in parameters

Source: https://github.com/stripe/stripe-java/wiki/Migration-guide-for-v9

Shows how to add elements to lists and maps using add/addAll and put/putAll methods in typed parameters.

```java
  PaymentIntentRetrieveParams typedParams = PaymentIntentRetrieveParams.builder()
      // support both adding individual element or the whole list
      .addExpand("application")
      .addExpand("on_behalf_of")
      .addAllExpand(Arrays.asList("review", "source", "transfer_data.destination"))
      .build();

  CustomerUpdateParams customerUpdateParams = CustomerUpdateParams.builder()
       // support both putting individual entry or the whole map
       .putMetadata("key1", "value1")
       .putAllMetadata(ImmutableMap.of("key2", "value2"))
       .build();
```

--------------------------------

### New typed parameters for Charge.create

Source: https://github.com/stripe/stripe-java/wiki/Migration-guide-for-v9

Shows the new way of using typed parameters with builder-style constructors for Charge.create. This is the recommended approach in version 9.

```java
  ChargeCreateParams typedParams = ChargeCreateParams.builder()
      .setAmount(100L)
      .setCurrency("usd")
      .setSource("card_123")
      .build();

  Charge charge = Charge.create(typedParams);
```

--------------------------------

### Run all checks

Source: https://github.com/stripe/stripe-java/blob/master/README.md

Run all checks including tests and code formatting.

```sh
./gradlew check
```

--------------------------------

### Replace String API key with RequestOptions

Source: https://github.com/stripe/stripe-java/wiki/Migration-guide-for-v6

Shows the old and new ways to pass an API key or Stripe-Account header when creating a Charge. The old method passes the key as a String; the new method uses RequestOptions with setApiKey or setStripeAccount.

```java
// Don't do this
Charge charge = Charge.create(chargeParams, "sk_...");

// Instead do this
RequestOptions options = (new RequestOptionsBuilder()).setApiKey("sk_...").build();
Charge charge = Charge.create(chargeParams, options);

// Or even better, use the `Stripe-Account` header
RequestOptions options = (new RequestOptionsBuilder()).setStripeAccount("acct_...").build();
Charge charge = Charge.create(chargeParams, options);
```

--------------------------------

### Set custom HTTP client with LiveStripeResponseGetter

Source: https://github.com/stripe/stripe-java/wiki/Migration-guide-for-v17

Shows how to register a custom HttpClient implementation with the library by creating a LiveStripeResponseGetter and setting it via ApiResource.setStripeResponseGetter(). This is required to use a custom HTTP client.

```java
import com.stripe.net.ApiResource;
import com.stripe.net.HttpClient;
import com.stripe.net.LiveStripeResponseGetter;
import com.stripe.net.StripeResponseGetter;

HttpClient myClient = new MyCustomClient();
StripeResponseGetter srg = new LiveStripeResponseGetter(myClient);
ApiResource.setStripeResponseGetter(srg);
```

--------------------------------

### SDK Migrator execute command

Source: https://github.com/stripe/stripe-java/wiki/v1-namespace-in-StripeClient

Runs the migrator with --execute to actually modify the files. Ensure code is committed before running.

```bash
npx @stripe/sdk-migrator --language java --migration v1-namespace -d <path-to-your-codebase> --execute
```

--------------------------------

### Configure Timeouts with RequestOptions

Source: https://github.com/stripe/stripe-java/blob/master/README.md

Sets connect and read timeouts on a per-request basis using RequestOptions. The options are then passed to the create method.

```java
RequestOptions options = RequestOptions.builder()
    .setConnectTimeout(30 * 1000) // in milliseconds
    .setReadTimeout(80 * 1000)
    .build();
client.v1().customers().create(params, options);
```

--------------------------------

### SDK Migrator dry-run command

Source: https://github.com/stripe/stripe-java/wiki/v1-namespace-in-StripeClient

Runs the migrator to preview which files will be changed. Replace <path-to-your-codebase> with the actual path. Does not modify files.

```bash
npx @stripe/sdk-migrator --language java --migration v1-namespace -d <path-to-your-codebase>
```

--------------------------------

### Run particular tests

Source: https://github.com/stripe/stripe-java/blob/master/README.md

Run specific tests by fully qualified class name or method. Use --tests with Gradle.

```sh
just test-one com.stripe.model.AccountTest
just test-one com.stripe.functional.CustomerTest
just test-one com.stripe.functional.CustomerTest.testCustomerCreate
# or: ./gradlew test --tests com.stripe.model.AccountTest
# or: ./gradlew test --tests com.stripe.functional.CustomerTest
# or: ./gradlew test --tests com.stripe.functional.CustomerTest.testCustomerCreate
```

--------------------------------

### Current untyped parameters for Charge.create

Source: https://github.com/stripe/stripe-java/wiki/Migration-guide-for-v9

Shows the old way of passing untyped Map parameters to Charge.create. This is the current usage before migrating to typed parameters.

```java
  Map<String, Object> untypedParams = new HashMap<>();
  params.put("amount", 100);
  params.put("currency", "usd");
  params.put("source", "card_123");

  Charge charge = Charge.create(untypedParams);
```

--------------------------------

### Identify your plugin with Stripe.setAppInfo

Source: https://github.com/stripe/stripe-java/blob/master/README.md

Call Stripe.setAppInfo() with your plugin's name, version, and URL so the library can identify your plugin when making API calls.

```java
Stripe.setAppInfo("MyAwesomePlugin", "1.2.34", "https://myawesomeplugin.info");
```

--------------------------------

### Convert static resource method calls to StripeClient

Source: https://github.com/stripe/stripe-java/wiki/Migration-guide-for-v23

Shows converting a static Customer.retrieve call to the service-based client.customers().retrieve(). The new pattern avoids the extra API call that the static method would make.

```java
// Before
Customer customer = Customer.retrieve("cus_123");

// After
client.customers().retrieve("cus_123");
```

--------------------------------

### V2 error handling: catch RateLimitException directly

Source: https://github.com/stripe/stripe-java/wiki/Migration-guide-for-v32

Shows the before and after for catching V2 rate limit errors. Previously RateLimitException extended ApiException; now it extends StripeException directly, so catch it separately from generic API errors.

```java
// Before: RateLimitException extended ApiException
try {
    client.v2().core().events().list(params);
} catch (ApiException e) {
    // This caught RateLimitException and generic API errors
}
```

```java
// After: RateLimitException extends StripeException directly
try {
    client.v2().core().events().list(params);
} catch (RateLimitException e) {
    // Handle rate limiting specifically
} catch (ApiException e) {
    // Handle other API errors
}
```

--------------------------------

### Convert nested resource operations to StripeClient

Source: https://github.com/stripe/stripe-java/wiki/Migration-guide-for-v23

Shows converting nested resource operations like Customer.balanceTransactions() to client.customers().balanceTransactions().list(). The new pattern avoids the need to retrieve the parent resource first.

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

--------------------------------

### Add beta version header for preview features

Source: https://github.com/stripe/stripe-java/blob/master/README.md

Use Stripe.addBetaVersion to set the Stripe-Version header for preview features that require a name and version, like feature_beta=v3. This is only available in public preview SDKs.

```java
Stripe.addBetaVersion("feature_beta", "v3");
```

--------------------------------

### V2 errors now typed like V1: before and after

Source: https://github.com/stripe/stripe-java/wiki/Migration-guide-for-v32

Shows the change from catching generic ApiException for all V2 errors to catching typed exceptions. V2 errors now throw InvalidRequestException, AuthenticationException, RateLimitException, etc., matching V1 behavior.

```java
// Before: V2 errors were all generic ApiException
try {
    client.v2().core().events().list(params);
} catch (ApiException e) {
    // Caught everything
}
```

```java
// After: V2 errors are now typed like V1
try {
    client.v2().core().events().list(params);
} catch (RateLimitException e) {
    // 429
} catch (InvalidRequestException e) {
    // 400, 404
} catch (AuthenticationException e) {
    // 401
} catch (StripeException e) {
    // Everything else
}
```

--------------------------------

### Builder for nested objects in SkuCreateParams

Source: https://github.com/stripe/stripe-java/wiki/Migration-guide-for-v9

Shows how to build nested objects separately using builder() and then use them in the root-level parameters. Note that nested objects are not shared between different parameter classes.

```java
  SkuCreateParams.Inventory inventoryParams = SkuCreateParams.Inventory.builder()
      .setQuantity(4L)
      .build();

  SkuCreateParams createParams = SkuCreateParams.builder()
      .setPrice(99L)
      .setCurrency("usd")
      .setInventory(inventoryParams)
      .setProduct("prod_123")
      .build();
  Sku sku = Sku.create(createParams);
```

--------------------------------

### Configure Global Timeouts

Source: https://github.com/stripe/stripe-java/blob/master/README.md

Sets connect and read timeouts globally on the StripeClient. Timeouts are specified in milliseconds.

```java
StripeClient client = StripeClient.builder()
        .setConnectTimeout(30 * 1000); // in milliseconds
        .setReadTimeout(80 * 1000);
        .build();
```

--------------------------------

### Enable Automatic Retries with RequestOptions

Source: https://github.com/stripe/stripe-java/blob/master/README.md

Configures automatic retries on a per-request basis using RequestOptions. The options are then passed to the create method.

```java
RequestOptions options = RequestOptions.builder()
    .setMaxNetworkRetries(2)
    .build();
client.v1().customers().create(params, options);
```

--------------------------------

### Builder for enums in WebhookEndpointCreateParams

Source: https://github.com/stripe/stripe-java/wiki/Migration-guide-for-v9

Shows how to use specific enums for parameters that require enum values, such as enabled events and API version.

```java
  WebhookEndpointCreateParams createParams = WebhookEndpointCreateParams
      .builder()
      .addEnabledEvent(WebhookEndpointCreateParams.EnabledEvent.CHARGE__SUCCEEDED)
      .setApiVersion(WebhookEndpointCreateParams.ApiVersion.VERSION_2019_03_14)
      .setUrl("https://myEndPoint.com")
      .build();
```

--------------------------------

### Use unsafeSetStripeVersionOverride as a workaround

Source: https://github.com/stripe/stripe-java/wiki/Migration-guide-for-v22

This snippet shows the workaround for per-request version overrides using `unsafeSetStripeVersionOverride`. It is discouraged and may lead to unexpected errors.

```java
RequestOptions.RequestOptionsBuilder builder = RequestOptions.builder();
builder.setApiKey(...)
            .setClientId(...);

RequestOptionsBuilder.unsafeSetStripeVersionOverride(builder, "2022-11-15");
```

--------------------------------

### Gradle dependency for stripe-java

Source: https://github.com/stripe/stripe-java/blob/master/README.md

Add this dependency to your project's build file to use the Stripe Java client library with Gradle.

```groovy
implementation "com.stripe:stripe-java:33.4.2"
```

--------------------------------

### Maven dependency for stripe-java

Source: https://github.com/stripe/stripe-java/blob/master/README.md

Add this dependency to your project's POM to use the Stripe Java client library with Maven.

```xml
<dependency>
  <groupId>com.stripe</groupId>
  <artifactId>stripe-java</artifactId>
  <version>33.4.2</version>
</dependency>
```

--------------------------------

### Convert XxxCollection method calls to StripeClient

Source: https://github.com/stripe/stripe-java/wiki/Migration-guide-for-v23

Shows converting a collection operation from resource-based to service-based. Note the change from XxxCollectionParams to XxxParams and that StripeClient always returns StripeCollection<Xxx>.

```java
// 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);
```

--------------------------------

### Manual migration diff: add v1() to StripeClient calls

Source: https://github.com/stripe/stripe-java/wiki/v1-namespace-in-StripeClient

Shows the required change for version 29.5.0+ where non-v2 services are moved under v1(). The diff removes the direct call to customers() and adds v1() before it.

```diff
StripeClient client = new StripeClient("sk_test...")

- client.customers().retrieve("cus_123");
+ client.v1().customers().retrieve("cus_123");
```

--------------------------------

### Set Stripe version using EphemeralKeyCreateParamsBuilder

Source: https://github.com/stripe/stripe-java/wiki/Migration-guide-for-v22

Use this snippet to set the Stripe version when creating an EphemeralKey, replacing the removed `RequestOptions.setStripeVersionOverride` methods.

```java
EphemeralKeyCreateParams params = EphemeralKeyCreateParams.builder()
  .setStripeVersion("XXXX-YY-ZZ")
  .build();
```

--------------------------------

### Automatic-Module-Name change: before and after

Source: https://github.com/stripe/stripe-java/wiki/Migration-guide-for-v32

Shows the required update to module-info.java when using JPMS. The module name changes from stripe.java to com.stripe; no action is needed if you don't have a module-info.java file.

```java
module my.app {
    requires stripe.java;
}
```

```java
module my.app {
    requires com.stripe;
}
```

--------------------------------

### ProGuard keep rule for Stripe client

Source: https://github.com/stripe/stripe-java/blob/master/README.md

Add this rule to your proguard.cfg file to exclude the Stripe client library from ProGuard obfuscation.

```text
-keep class com.stripe.** { *; }
```

--------------------------------

### Define and use a CompatibilityTransformer for invoice events

Source: https://github.com/stripe/stripe-java/wiki/Migration-guide-for-v8----version-upgrade

Use this snippet to handle invoice events created on older Stripe API versions by transforming the JSON to match the latest model. It defines an `invoiceTransformer` that applies version-specific changes (e.g., paginating `lines`, setting `auto_advance`, mapping `forgiven` to `uncollectible`) and then deserializes the event data with `deserializeUnsafeWith`. The transformer filters by `eventType` and uses `apiVersion` to apply only eligible transformations.

```java
EventDataObjectDeserializer dataObjectDeserializer = event.getDataObjectDeserializer();
EventDataObjectDeserializer.CompatibilityTransformer invoiceTransformer =
    new com.stripe.model.EventDataObjectDeserializer.CompatibilityTransformer() {
      @Override
      public JsonObject transform(JsonObject rawJsonObject, String apiVersion,
                                  String eventType) {
        // Attempt to be forward compatible only for invoice events
        if (!eventType.startsWith("invoice.")) {
          return rawJsonObject;
        }
        
        // update guide on Invoice: https://stripe.com/docs/upgrades#2012-10-26
        // `lines` for line items are in the form of paginated collection
        // supposed the old schema for `lines` is a JSON array
        if (versionToDate(apiVersion).before(versionToDate("2012-10-26"))) {
          JsonArray lines = rawJsonObject.get("lines").getAsJsonArray();
          JsonObject paginatedLines = new JsonObject();
          paginatedLines.add("data", lines);
          paginatedLines.add("has_more", new JsonPrimitive(false));
          paginatedLines.add("total_count", new JsonPrimitive(lines.size()));
          rawJsonObject.add("lines", paginatedLines);
        }
        
        // update guide on Invoice: https://stripe.com/docs/upgrades#2017-12-14
        // invoice item description is always set, if you downstream application
        // code expects non-null description, consider adding default values
        if (versionToDate(apiVersion).before(versionToDate("2017-12-14"))) {
          // add you default values to the line item
        }
        
        // update guide on Invoice: https://stripe.com/docs/upgrades#2018-05-21
        // change in semantics of `id` for invoice line items, but schema remains the same
    
        // update guide on Invoice: https://stripe.com/docs/upgrades#2018-10-31
        // billing_reason taking a new enum, but the old enum is still valid, so no change.

        // following update guide on Invoice: https://stripe.com/docs/upgrades#2018-11-08
        if (versionToDate(apiVersion).before(versionToDate("2018-11-08"))) {
          // From change log, `closed` is deprecated in favor of `auto_advance`
          // when `closed` is true, `auto_advance` is false.
          boolean closedValue = rawJsonObject.get("closed").getAsBoolean();
          rawJsonObject.add("auto_advance", new JsonPrimitive(!closedValue));

          // From change log, `forgiven` is deprecated in favor of `uncollectible` status.
          if (rawJsonObject.get("forgiven").getAsBoolean()) {
            rawJsonObject.add("status", new JsonPrimitive("uncollectible"));
          }
        }
        return rawJsonObject;
      }
    };
StripeObject deserialized = dataObjectDeserializer.deserializeUnsafeWith(invoiceTransformer);
Invoice invoice = (Invoice) deserialized;
```

--------------------------------

### Type-check and cast ExternalAccount to BankAccount or Card

Source: https://github.com/stripe/stripe-java/wiki/Migration-guide-for-v8

Use this pattern to retrieve the underlying object from an ExternalAccount instance. It checks for BankAccount and Card subtypes, and throws an error if neither matches, which can be confidently raised to Stripe if it ever happens.

```java
ExternalAccount externalAccount = createExternalAccount();
if (externalAccount instanceOf BankAccount) {
  BankAccount bankAccount = (BankAccount) externalAccount;
} else if (externalAccount instanceOf Card) {
  Card card = (Card) externalAccount;
} else {
  // you can confidently throw error and raise to Stripe if this ever happens.
}
```

--------------------------------

### Best-effort field getter for invoice ID and status

Source: https://github.com/stripe/stripe-java/wiki/Migration-guide-for-v8----version-upgrade

Use this snippet to safely retrieve invoice ID and status from an event data object. It first attempts safe deserialization, then falls back to unsafe deserialization, and finally parses raw JSON if needed. The unsafe path throws EventDataObjectDeserializationException, and raw JSON is accessible in the exception.

```java
String invoiceId = null;
String status = null;
if (dataObjectDeserializer.deserialize()) {
  Invoice invoice = (Invoice) dataObjectDeserializer.getObject();
  invoiceId = invoice.getId();
  status = invoice.getStatus();
} else {
  try {
    Invoice invoice = (Invoice) dataObjectDeserializer.deserializeUnsafe();
    invoiceId = invoice.getId();
    status = invoice.getStatus();
  } catch (EventDataObjectDeserializationException e) {
    JsonElement parsed = new JsonParser().parse(e.getRawJson());
    invoiceId = parsed.getAsJsonObject().get("id").getAsString();
    status = parsed.getAsJsonObject().get("status").getAsString();
  }
}
```

--------------------------------

### Event deserialization: new usage with Optional and isPresent()

Source: https://github.com/stripe/stripe-java/wiki/Migration-guide-for-v9

Shows the new v9 pattern for handling event data object deserialization. Uses Optional<StripeObject> from getObject() and checks isPresent() to handle absence. The else branch suggests using deserializeUnsafe or deserializeUnsafeWith for absent data objects, with details in the EventDataObjectDeserializer javadoc.

```java
    Event event = getEventFromWebhookOrEndpoint();
    EventDataObjectDeserializer dataObjectDeserializer = event.getDataObjectDeserializer();
    if (dataObjectDeserializer.getObject().isPresent()) {      
      StripeObject stripeObject = dataObjectDeserializer.getObject().get();
      doSomething(stripeObject);
    } else {
      // Handle absent data object with `deserializeUnsafe` or `deserializeUnsafeWith`.
      // Please see the usage details in java doc on the class `EventDataObjectDeserializer`.
    }
```

--------------------------------

### Using EventDataObjectDeserializer proxy object for event retrieval

Source: https://github.com/stripe/stripe-java/wiki/Migration-guide-for-v8----version-upgrade

Use this snippet to retrieve an event and access its data object deserializer. The deprecated method event.getData().getObject() throws a runtime JsonParseException on schema-incompatible JSON, while the new proxy object defers deserialization and provides explicit handling.

```java
Event event = Event.retrieve("evt_123");
// deprecated method
EventData eventData = event.getData();
try {
  event.getData().getObject();
} catch (JsonParseException e) {
  // run-time exception on schema incompatible JSON
}
// instead use this proxy object
EventDataObjectDeserializer dataObjectDeserializer = event.getDataObjectDeserializer();
```

--------------------------------

### Enable Automatic Retries Globally

Source: https://github.com/stripe/stripe-java/blob/master/README.md

Configures the StripeClient to automatically retry requests that fail due to intermittent network problems or other non-deterministic errors. Sets the maximum number of retries to 2.

```java
StripeClient client = StripeClient.builder()
        .setMaxNetworkRetries(2)
        .build();
```

--------------------------------

### Event deserialization: current usage with deserialize()

Source: https://github.com/stripe/stripe-java/wiki/Migration-guide-for-v9

Shows the old pattern for handling event data object deserialization in Stripe Java v8 and earlier. Uses EventDataObjectDeserializer#deserialize() to check success before retrieving the StripeObject. This pattern is no longer valid in v9.

```java
    Event event = getEventFromWebhookOrEndpoint();
    EventDataObjectDeserializer dataObjectDeserializer = event.getDataObjectDeserializer();
    if (dataObjectDeserializer.deserialize()) {
       StripeObject stripeObject = dataObjectDeserializer.getObject();
       doSomething(stripeObject);
    }
```

--------------------------------

### Disable DNS cache in v17

Source: https://github.com/stripe/stripe-java/wiki/Migration-guide-for-v17

Use this snippet to disable the DNS cache in your own code, as the library no longer does it automatically. Set the networkaddress.cache.ttl property to "0".

```java
java.security.Security.setProperty("networkaddress.cache.ttl", "0");
```

--------------------------------

### Safe webhook event deserialization with EventDataObjectDeserializer

Source: https://github.com/stripe/stripe-java/wiki/Migration-guide-for-v8----version-upgrade

Use this snippet to safely deserialize webhook events when the event's API version matches the library's pinned API version. The new method getObject() on EventDataObjectDeserializer returns the object only when API versions match, otherwise null. The old method event.getData().getObject() is deprecated.

```java
Event event = Webhook.constructEvent(payload, signature, secret);
if (event.getType().equals("charge.succeeded")) {
   // Current, now deprecated
   Charge charge = (Charge) event.getData().getObject();
   // New returning value only when API versions matche and null otherwise.
   Charge charge = (Charge) event.getDataObjectDeserializer().getObject();
}
```

--------------------------------

### Access raw JSON from list calls

Source: https://github.com/stripe/stripe-java/blob/master/README.md

For list calls, getRawJsonObject() is only available on the top-level List<T> object, not on individual items. To access undocumented properties on list items, go through the list's raw JSON array.

```java
var cards = stripeClient
  .v1()
  .issuing()
  .cards()
  .list(params);

// doesn't work:
cards
  .getData()
  .get(0)
  .getRawJsonObject(); // null

// instead, go through the list:
cards
 .getRawJsonObject()
 .getAsJsonArray("data")
 .get(0)
 .getAsJsonObject()
 .getAsJsonPrimitive("undocumented-val")
 .getAsString(); // "some-val"
```

--------------------------------

### Disable request latency telemetry

Source: https://github.com/stripe/stripe-java/blob/master/README.md

Set Stripe.enableTelemetry to false to disable sending request latency telemetry to Stripe. This is optional; telemetry is enabled by default.

```java
Stripe.enableTelemetry = false;
```

--------------------------------

### Update enum check for Account verification disabledReason

Source: https://github.com/stripe/stripe-java/wiki/Migration-guide-for-v8----version-upgrade

When upgrading to stripe-java version 8, the enum value for Account#Verification#getDisabledReason changed from 'other' to 'under_review' in the 2017-06-05 API version. Update your code to check for 'under_review' instead of 'other' to correctly detect accounts under review.

```java
Account account = Account.retrieve();
// need to change "other" to "under_review" instead
if (account.getVerification().disabledReason.equals("other")) {
  // code path assuming account is still under review
}
```
Tokens:
Raw