Stripe Java Bindings

You can sign up for a Stripe account at https://stripe.com.

Requirements

Java 1.8 or later.

Installation

Maven users

Add this dependency to your project's POM:

<dependency>
  <groupId>com.stripe</groupId>
  <artifactId>stripe-java</artifactId>
  <version>12.0.0</version>
</dependency>

Gradle users

Add this dependency to your project's build file:

compile "com.stripe:stripe-java:12.0.0"

Others

You'll need to manually install the following JARs:

• The Stripe JAR from https://github.com/stripe/stripe-java/releases/latest
• Google Gson from https://repo1.maven.org/maven2/com/google/code/gson/gson/2.8.5/gson-2.8.5.jar.

ProGuard

If you're planning on using ProGuard, make sure that you exclude the Stripe bindings. You can do this by adding the following to your proguard.cfg file:

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

Documentation

Please see the Java API docs for the most up-to-date documentation.

Usage

StripeExample.java

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

import com.stripe.Stripe;
import com.stripe.exception.StripeException;
import com.stripe.model.Charge;
import com.stripe.net.RequestOptions;

public class StripeExample {

    public static void main(String[] args) {
        Stripe.apiKey = "sk_test_...";

        Map<String, Object> chargeMap = new HashMap<String, Object>();
        chargeMap.put("amount", 100);
        chargeMap.put("currency", "usd");
        chargeMap.put("source", "tok_1234"); // obtained via Stripe.js

        try {
            Charge charge = Charge.create(chargeMap);
            System.out.println(charge);
        } catch (StripeException e) {
            e.printStackTrace();
        }
    }
}

See the project's functional tests for more examples.

Per-request Configuration

For apps that need to use multiple keys during the lifetime of a process, like one that uses Stripe Connect, it's also possible to set a per-request key and/or account:

RequestOptions requestOptions = new RequestOptionsBuilder()
    .setApiKey("sk_test_...")
    .setStripeAccount("acct_...")
    .build();

Charge.list(null, requestOptions);

Charge.retrieve("ch_18atAXCdGbJFKhCuBAa4532Z", requestOptions);

Configuring Timeouts

Connect and read timeouts can be configured globally:

Stripe.setConnectTimeout(30 * 1000); // in milliseconds
Stripe.setReadTimeout(80 * 1000);

Or on a finer grain level using RequestOptions:

RequestOptions options = RequestOptions.builder()
    .setConnectTimeout(30 * 1000) // in milliseconds
    .setReadTimeout(80 * 1000)
    .build();
Charge.create(params, options);

Please take care to set conservative read timeouts. Some API requests can take some time, and a short timeout increases the likelihood of a problem within our servers.

Writing a plugin

If you're writing a plugin that uses the library, we'd appreciate it if you identified using Stripe.setAppInfo():

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

This information is passed along when the library makes calls to the Stripe API.

Request latency telemetry

By default, the library sends request latency telemetry to Stripe. These numbers help Stripe improve the overall latency of its API for all users.

You can disable this behavior if you prefer:

Stripe.enableTelemetry = false;

Development

The test suite depends on stripe-mock, so make sure to fetch and run it from a background terminal (stripe-mock's README also contains instructions for installing via Homebrew and other methods):

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

You must have Gradle installed. To run the tests:

./gradlew test

You can run particular tests by passing --tests Class#method. Make sure you use the fully qualified class name. For example:

./gradlew test --tests com.stripe.model.AccountTest
./gradlew test --tests com.stripe.functional.ChargeTest
./gradlew test --tests com.stripe.functional.ChargeTest.testChargeCreate

The library uses Spotless along with google-java-format for code formatting. Code must be formatted before PRs are submitted, otherwise CI will fail. Run the formatter with:

./gradlew spotlessApply

The library uses Project Lombok. While it is not a requirement, you might want to install a plugin for your favorite IDE to facilitate development.