repository·master·Indexed 21 days ago
https://github.com/stripe/stripe-javaThe official Java client library for integrating Stripe's APIs. It features the StripeClient for API resource access, support for JDK 8 through 25, and tools for managing request options, automatic retries, and timeouts. The SDK provides mechanisms for using undocumented parameters via putExtraParam and getRawJsonObject, as well as rawRequest for private betas. It is available via Maven Central (version 33.2.0) and requires Google Gson 2.10.1 or newer.
google-java-format. Code must be formatted before submitting PRs to avoid CI failure. Use just format or ./gradlew spotlessApply to apply formatting.just format
# or:
./gradlew spotlessApplyThe Stripe Java client library is available via Maven Central. Depending on your build tool, follow the instructions below to add the dependency.
### Gradle
```groovy
implementation "com.stripe:stripe-java:33.2.0"<dependency>
<groupId>com.stripe</groupId>
<artifactId>stripe-java</artifactId>
<version>33.2.0</version>
</dependency>If you need to use beta features or undocumented parameters that are not yet part of the typed SDK, you can use the following methods:
Use putExtraParam(String key, String value) on the parameter builder to include extra fields in your request.
Use .getRawJsonObject() on the returned object to access the underlying JSON. This allows you to extract properties using standard JSON navigation.
Important: .getRawJsonObject() is only available on top-level objects. For list results (e.g., .list()), you must navigate through the raw JSON array of the response to access the raw JSON of an individual item.
// Passing parameters
CustomerCreateParams params = CustomerCreateParams.builder()
.setEmail("jenny.rosen@example.com")
.putExtraParam("secret_feature_enabled", "true")
.build();
// Retrieving properties
Customer customer = client.v1().customers().retrieve("cus_1234");
Boolean featureEnabled = customer.getRawJsonObject()
.getAsJsonPrimitive("secret_feature_enabled")
.getAsBoolean();
// Accessing undocumented values in a list
var cards = client.v1().issuing().cards().list(params);
String val = cards.getRawJsonObject()
.getAsJsonArray("data")
.get(0)
.getAsJsonObject()
.getAsJsonPrimitive("undocumented-val")
.getAsString();Stripe provides preview versions of the SDK for testing upcoming features:
-beta.X suffix (e.g., 25.2.0-beta.2).-alpha.X suffix (e.g., 25.2.0-alpha.2).Important Considerations:
Stripe-Version header. Use Stripe.addBetaVersion(name, version) to set this.// Setting a beta version header
Stripe.addBetaVersion("feature_beta", "v3");The library supports Long Term Support (LTS) versions of the JDK. Supported versions include:
If you are not using Gradle or Maven, you must manually add the following JARs to your project's classpath:
stripe-java-33.2.0.jar) from Maven Central.2.10.1 is recommended for guaranteed compatibility.To run the full test suite, use the just test command or the Gradle wrapper. You can also run specific tests by providing the fully qualified class name or a specific method using the --tests flag.
# Run all tests
just test
# or:
./gradlew test
# Run a specific test class
just test-one com.stripe.model.AccountTest
# or:
./gradlew test --tests com.stripe.model.AccountTest
# Run a specific test method
just test-one com.stripe.functional.CustomerTest.testCustomerCreate
# or:
./gradlew test --tests com.stripe.functional.CustomerTest.testCustomerCreateThe test suite depends on stripe-mock. You must fetch and run it in a background terminal to allow the tests to interact with a mock Stripe API.
go get -u github.com/stripe/stripe-mock
stripe-mockIf you use ProGuard for code shrinking or obfuscation, you must exclude the Stripe client library to prevent issues. Add the following rule to your proguard.cfg file:
-keep class com.stripe.** { *; }You can set connect and read timeouts to manage how long the library waits for a response. These can be set globally via the StripeClient builder or per-request via RequestOptions.
Warning: Use conservative read timeouts; setting them too short may cause failures for API requests that naturally take longer to process.
// Global configuration
StripeClient client = StripeClient.builder()
.setConnectTimeout(30 * 1000) // in milliseconds
.setReadTimeout(80 * 1000)
.build();
// Per-request configuration
RequestOptions options = RequestOptions.builder()
.setConnectTimeout(30 * 1000)
.setReadTimeout(80 * 1000)
.build();
client.v1().customers().create(params, options);By default, the library sends request latency telemetry to Stripe to help improve API performance. You can disable this by setting Stripe.enableTelemetry to false.
Stripe.enableTelemetry = false;The library can automatically retry requests that fail due to intermittent network issues. You can configure this globally when building the StripeClient or on a per-request basis using RequestOptions.
Note: Using idempotency keys ensures that these retries are safe.
// Global configuration
StripeClient client = StripeClient.builder()
.setMaxNetworkRetries(2)
.build();
// Per-request configuration
RequestOptions options = RequestOptions.builder()
.setMaxNetworkRetries(2)
.build();
client.v1().customers().create(params, options);