GoCardless Pro Java Client
Latest commit 2e8edcb Feb 23, 2017 @jacobpgn jacobpgn committed on GitHub Merge pull request #7 from gocardless/dev


Java Client for GoCardless Pro API

This library provides a simple wrapper around the GoCardless API.

Getting started

With Maven:


With Gradle:

compile 'com.gocardless:gocardless-pro:2.0.0'

Initializing the client

The client is initialised with an access token.

String accessToken = "AO00000123";
GoCardlessClient client = GoCardlessClient.create(accessToken);


Fetching resources

To fetch a single item, use the get method:

Mandate mandate = client.mandates().get("MD123").execute();

Listing resources

To fetch items in a collection, there are two options:

  • Fetching items one page at a time:
ListResponse<Customer> firstPage = client.customers().list().execute();
for (Customer customer : client.customers().list().execute()) {

String cursor = firstPage.getAfter();
ListResponse<Customer> nextPage = client.customers().list.withAfter(cursor).execute();
  • Iterating through all of the items in a collection:
for (Customer customer : client.customers().all().execute()) {

Creating resources

Resources can be created with the create method:

Creditor creditor = client.creditors().create()
    .withName("The Wine Club")
    .withAddressLine1("9 Acer Gardens")
    .withPostalCode("B4 7NJ")

Updating resources

Resources can be updates with the update method:

Subscription subscription = client.subscriptions().update("SU123")
    .withName("New name")

Retrying requests

The library will attempt to retry most failing requests automatically (with the execption of some that are not safe to retry). If you want to override this behaviour (for example, to provide your own retry mechanism), then you can use the executeWrapped method in place of execute. This returns an ApiResponse object, which also gives access to the response status code and headers.

Handling errors

Any errors will result in a GoCardlessException being thrown. If the error is due to an error response from the API, then an appropriate subclass of GoCardlessApiException will be thrown, providing more information about the nature of the error. This will be one of:

  • GoCardlessInternalException
  • InvalidApiUsageException
  • InvalidStateException
  • ValidationFailedException

See the documentation for more details.


This library requires JDK version 7 or above.


All requests are logged at INFO level using SLF4J. Logs will only be sent if you have an SLF4J binding on your classpath - we recommend using Logback.


Full Javadoc can be found here.


This client is auto-generated from Crank, a toolchain that we hope to soon open source. Issues should for now be reported on this repository. Please do not modify the source code yourself, your changes will be overridden!