Java
Introduction
The Mangopay Java SDK makes working with the Mangopay API easier in a Java environment.
The SDK package is available on Maven Central: mangopay4-java-sdk
Caution – Use only the mangopay4 package (late Nov 2025)
Please ensure you use only the package with mangopay4 in the name (this is the package name and has no connection with the SDK version number).
Any other package must not be used. You need to update your package manually.
Since November 25, 2025, Mangopay’s official SDKs are no longer accessible on GitHub (with the exception of PHP for publication reasons).
Prerequisites
To run the Mangopay Java SDK, you’ll need:
- A
ClientIdand an API key – if you don’t have these, contact Sales to get access to the Mangopay Dashboard - Java 7.0+
- Your preferred build automation tools: Maven or Gradle
Getting started
1. Install the Mangopay package
The SDK is published as an artifact on Mangopay’s Maven Central Repository and can be used with Gradle or Maven.
Installation with Gradle
Add the following to your build.gradle file:
Installation with Maven
Add the Mangopay dependency to your pom.xml file:
2. Initialize and configure the SDK
The configuration object of the SDK supports all the following properties:
SDK usage
In the Mangopay documentation, you’ll find detailed information of all endpoints paired with its corresponding Java SDK method implementation example. Be sure to customize the provided code to suit your specific requirements.
Idempotency support
To make a request with idempotency support, add idempotencyKey parameter to your function.
For more information, see the Idempotency article.
In order to retrieve the request made using this idempotency:
Pagination and filtering
For endpoints that support pagination and filtering, you can use the Pagination and Sorting objects.
In the Pagination object, you need to specify the page and items per page to return.
In the Sorting object, you need to use the addField() method to specify the sort direction.
As a result, the answer will be paginated, and the total number of items and the total number of pages will be provided. For example, with the List all Users endpoint:
Rate limiting status
Rate limiting in Mangopay restricts the frequency of API requests a client can make over a defined period, automatically updating the limit with each request and blocking additional requests if the limit is exceeded until it resets. For more information, see the rate limiting article.
Unit tests
All JUnit tests are placed under the tests directory.
Error handling
The SDK provides the ResponseException class to wrap HTTP errors returned by the API. You can use a standard Java try-catch block to handle API errors, for example: