{"id":20290646,"url":"https://github.com/gocardless/gocardless-pro-java","last_synced_at":"2026-04-02T12:01:32.138Z","repository":{"id":29757778,"uuid":"33301481","full_name":"gocardless/gocardless-pro-java","owner":"gocardless","description":"GoCardless Java Client","archived":false,"fork":false,"pushed_at":"2026-03-24T13:26:52.000Z","size":12836,"stargazers_count":22,"open_issues_count":6,"forks_count":14,"subscribers_count":87,"default_branch":"master","last_synced_at":"2026-03-25T13:11:54.256Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gocardless.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2015-04-02T09:47:10.000Z","updated_at":"2026-03-24T10:40:05.000Z","dependencies_parsed_at":"2026-01-16T08:10:06.195Z","dependency_job_id":null,"html_url":"https://github.com/gocardless/gocardless-pro-java","commit_stats":null,"previous_names":[],"tags_count":146,"template":false,"template_full_name":null,"purl":"pkg:github/gocardless/gocardless-pro-java","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gocardless%2Fgocardless-pro-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gocardless%2Fgocardless-pro-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gocardless%2Fgocardless-pro-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gocardless%2Fgocardless-pro-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gocardless","download_url":"https://codeload.github.com/gocardless/gocardless-pro-java/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gocardless%2Fgocardless-pro-java/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31305971,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T09:48:21.550Z","status":"ssl_error","status_checked_at":"2026-04-02T09:48:19.196Z","response_time":89,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-14T15:08:35.457Z","updated_at":"2026-04-02T12:01:32.091Z","avatar_url":"https://github.com/gocardless.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Java Client for GoCardless API\n\nThis library provides a simple wrapper around the [GoCardless API](http://developer.gocardless.com/api-reference).\n\n- [\"Getting started\" guide](https://developer.gocardless.com/getting-started/api/introduction/?lang=java) with copy and paste Java code samples\n- [API Reference](https://developer.gocardless.com/api-reference/2015-07-06)\n- [Example application](https://github.com/gocardless/gocardless-pro-java-example)\n\n## Getting started\n\nWith Maven:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.gocardless\u003c/groupId\u003e\n    \u003cartifactId\u003egocardless-pro\u003c/artifactId\u003e\n    \u003cversion\u003e8.2.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nWith Gradle:\n\n```\nimplementation 'com.gocardless:gocardless-pro:8.2.0'\n```\n\n## Initializing the client\n\nThe client is initialised with an access token, and is configured to use GoCardless' live environment by default:\n\n```java\nimport com.gocardless.GoCardlessClient;\n\nString accessToken = \"AO00000123\";\n\nGoCardlessClient client = GoCardlessClient.newBuilder(accessToken).build();\n```\n\nOptionally, the client can be customised with an environment, base URL, proxy and/or SSL socket factory, custom no of retries,\nwait time between retries by calling `.withX` methods on the `Builder`, max no of allowed retries are 3 :\n\n```java\nimport com.gocardless.GoCardlessClient;\nimport java.net.InetSocketAddress;\nimport java.net.Proxy;\n\nString accessToken = \"AO00000123\";\nProxy proxy = new Proxy(Proxy.Type.HTTP, new InetSocketAddress(\"127.0.0.1\", 8080));\n\nGoCardlessClient client = GoCardlessClient.newBuilder(accessToken)\n    .withEnvironment(GoCardlessClient.Environment.SANDBOX)\n    .withMaxNoOfRetries(2)\n    .withWaitBetweenRetriesInMilliSeconds(200)\n    .withProxy(proxy)\n    .build();\n```\n\nTo see the configurable options in full, see the documentation for `GoCardlessClient.Builder`.\n\nIf you're upgrading from v2.x, you'll need to update your code for initialising `GoCardlessClient`. See the\n\"Upgrading from v2.x to v3.x or above\" section below.\n\n## Examples\n\n### Fetching resources\n\nTo fetch a single item, use the `get` method:\n\n```java\nMandate mandate = client.mandates().get(\"MD123\").execute();\nSystem.out.println(mandate.getReference());\n```\n\n### Listing resources\n\nTo fetch items in a collection, there are two options:\n\n* Fetching items one page at a time:\n\n```java\nListResponse\u003cCustomer\u003e firstPage = client.customers().list().execute();\nfor (Customer customer : firstPage.getItems()) {\n    System.out.println(customer.getGivenName());\n}\n\nString cursor = firstPage.getAfter();\nListResponse\u003cCustomer\u003e nextPage = client.customers().list().withAfter(cursor).execute();\n```\n\n* Iterating through all of the items in a collection:\n\n```java\nfor (Customer customer : client.customers().all().execute()) {\n    System.out.println(customer.getGivenName());\n}\n```\n\n### Creating resources\n\nResources can be created with the `create` method:\n\n```java\nCreditor creditor = client.creditors().create()\n    .withName(\"The Wine Club\")\n    .withAddressLine1(\"9 Acer Gardens\")\n    .withCity(\"Birmingham\")\n    .withPostalCode(\"B4 7NJ\")\n    .withCountryCode(\"GB\")\n    .execute();\n```\n\n### Updating resources\n\nResources can be updates with the `update` method:\n\n```java\nSubscription subscription = client.subscriptions().update(\"SU123\")\n    .withName(\"New name\")\n    .execute();\n```\n\n### Retrying requests\n\nThe library will attempt to retry most failing requests automatically (with the exception\nof those which are not safe to retry).\n\n`GET` requests are considered safe to retry, and will be retried automatically. Certain\n`POST` requests are made safe to retry by the use of an idempotency key, generated\nautomatically by the library, so we'll automatically retry these too.\n\nIf you want to override this behaviour\n(for example, to provide your own retry mechanism), then you can use the `executeWrapped`\nmethod in place of `execute`.  This returns an `ApiResponse` object, which also gives\naccess to the response status code and headers.\n\n### Setting custom headers\n\nYou shouldn't generally need to customise the headers sent by the library, but you wish to\nin some cases (for example if you want to send an `Accept-Language` header when\n[creating a mandate PDF](https://developer.gocardless.com/api-reference/#mandate-pdfs-create-a-mandate-pdf)).\n\nTo do this, the library's request objects have a\n`withHeader(String headerName, String headerValue)` method which you can chain before you\ncall `execute()` to actually make the request:\n\n```java\nMandatePdf mandatePdf = client.mandatePdfs.create()\n  .withIban(\"FR14BARC20000055779911\")\n  .withHeader(\"Accept-Language\", \"fr-FR\")\n  .execute();\n```\n\nCustom headers you specify will override any headers generated by the library itself (for\nexample, an `Authorization` header with your configured access token or an\n`Idempotency-Key` header with a randomly-generated value or one you've configured\nmanually). Custom headers always take precedence.\n\nWhen you use the `execute()` method to create a resource, if your idempotency key has\nalready been used, we'll automatically fetch the already-created resource from the API\nusing the same headers, and will return it to you.\n\n### Handling errors\n\nAny 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:\n\n* GoCardlessInternalException\n* InvalidApiUsageException\n* InvalidStateException\n* ValidationFailedException\n\nSee the [documentation](http://gocardless.github.io/gocardless-pro-java/com/gocardless/errors/package-summary.html) for more details.\n\n### Handling webhooks\n\nGoCardless supports webhooks, allowing you to receive real-time notifications when things happen in your account, so you can take automatic actions in response, for example:\n\n* When a customer cancels their mandate with the bank, suspend their club membership\n* When a payment fails due to lack of funds, mark their invoice as unpaid\n* When a customer’s subscription generates a new payment, log it in their “past payments” list\n\nThe client allows you to validate that a webhook you receive is genuinely from GoCardless, and to parse it into `com.gocardless.resources.Event` objects which are easy to work with:\n\n```java\npackage myintegration;\n\n// Use the POM file at\n// https://raw.githubusercontent.com/gocardless/gocardless-pro-java-maven-example/master/pom.xml\n\nimport java.util.List;\nimport com.gocardless.Webhook;\nimport com.gocardless.errors.InvalidSignatureException;\nimport com.gocardless.resources.Event;\nimport org.springframework.http.HttpStatus;\nimport org.springframework.web.bind.annotation.RestController;\nimport org.springframework.web.bind.annotation.PostMapping;\nimport org.springframework.web.bind.annotation.RequestBody;\nimport org.springframework.web.bind.annotation.RequestHeader;\nimport org.springframework.http.ResponseEntity;\n\npublic class WebhookHandler {\n    @PostMapping(\"/\")\n    public ResponseEntity\u003cString\u003e handlePost(\n            @RequestHeader(\"Webhook-Signature\") String signatureHeader,\n            @RequestBody String requestBody) {\n        /*\n         * When you create a webhook endpoint, you can specify a secret. When GoCardless\n         * sends you a webhook, it'll sign the body using that secret. Since only you and\n         * GoCardless know the secret, you can check the signature and ensure that the\n         * webhook is truly from GoCardless.\n         *\n         * We recommend storing your webhook endpoint secret in an environment variable\n         * for security, but you could include it as a string directly in your code.\n         */\n        String webhookEndpointSecret = System.getenv(\"GOCARDLESS_WEBHOOK_ENDPOINT_SECRET\");\n\n        try {\n            List\u003cEvent\u003e events = Webhook.parse(requestBody, signatureHeader, webhookEndpointSecret);\n\n            // Work through your list of events...\n\n            return new ResponseEntity\u003cString\u003e(\"OK\", HttpStatus.OK);\n        } catch(InvalidSignatureException e) {\n            return new ResponseEntity\u003cString\u003e(\"Incorrect Signature\", HttpStatus.BAD_REQUEST);\n        }\n    }\n}\n```\n\nFor more details on working with webhooks, see our [\"Getting started\" guide](https://developer.gocardless.com/getting-started/api/introduction/?lang=java).\n\n## Upgrading from older versions\n\nIf you're upgrading from v7 or earlier to v8 or later, see: MIGRATION_V8.md\n\n## Compatibility\n\nThis library requires JDK version 8 or above.\n\n## Logging\n\nAll requests are logged at `INFO` level using [SLF4J](http://www.slf4j.org/).  Logs will only be sent if you have an SLF4J binding on your classpath - we recommend using [Logback](http://logback.qos.ch/).\n\n## Documentation\n\nFull Javadoc can be found [here](http://gocardless.github.io/gocardless-pro-java/com/gocardless/package-summary.html).\n\n## Contributing\n\nThis 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!__\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgocardless%2Fgocardless-pro-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgocardless%2Fgocardless-pro-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgocardless%2Fgocardless-pro-java/lists"}