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 ClientId and 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:

$repositories {
> mavenCentral()
>}
$
$dependencies {
> implementation 'com.mangopay:mangopay4-java-sdk:[release-number]'
> // All of your other dependencies
>}

Installation with Maven

Add the Mangopay dependency to your pom.xml file:

1<dependency>
2 <groupId>com.mangopay</groupId>
3 <artifactId>mangopay4-java-sdk</artifactId>
4 <version>2.37.0</version>
5</dependency>

2. Initialize and configure the SDK

1import com.mangopay.MangoPayApi;
2
3public class Main {
4 public static void main(String[] args) throws Exception {
5 MangoPayApi mangopay = new MangoPayApi();
6 mangopay.getConfig().setClientId("your-client-id");
7 mangopay.getConfig().setClientPassword("your-api-key");
8
9 ...
10 }
11}

The configuration object of the SDK supports all the following properties:

KeyTypeDefault valueDescription
setClientIdstringNoneYour Mangopay ClientId – can be found in the Dashboard.
setClientPasswordstringNoneYour Mangopay API key – can be found in the Dashboard.
setBaseUrlstringhttps://api.sandbox.mangopay.com/v2.01/The API sandbox URL. Set to the sandbox environment by default. To enable production environment, set it to https://api.mangopay.com
setConnectTimeoutinteger60000Time to wait in milliseconds while trying to establish a connection before terminating the attempt and generating an error.
setReadTimeoutinteger60000Time to wait in milliseconds to receive a response before terminating the attempt and generating an error.
setDebugModebooleanfalseActivates the debug mode. Recommended only in Sandbox.

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.

Call - Create user with idempotency key
1import com.mangopay.MangoPayApi;
2import com.mangopay.core.Address;
3import com.mangopay.core.enumerations.CountryIso;
4import com.mangopay.core.enumerations.UserCategory;
5import com.mangopay.entities.User;
6import com.mangopay.entities.UserNatural;
7
8import java.lang.reflect.Field;
9
10public class CreateNaturalUserWithKey {
11 public static void main(String[] args) throws Exception {
12 MangoPayApi mangopay = new MangoPayApi();
13 mangopay.getConfig().setClientId("your-client-id");
14 mangopay.getConfig().setClientPassword("your-api-key");
15
16 UserNatural user = new UserNatural();
17 Address address = new Address();
18
19 address.setAddressLine1("27 Rue de Rivoli");
20 address.setCity("Paris");
21 address.setRegion("Île-de-France");
22 address.setPostalCode("75001");
23 address.setCountry(CountryIso.FR);
24
25 user.setFirstName("Alex");
26 user.setLastName("Smith");
27 user.setEmail("alex.smith@mgp.com");
28 user.setAddress(address);
29 user.setBirthday(655772400);
30 user.setNationality(CountryIso.FR);
31 user.setCountryOfResidence(CountryIso.FR);
32 user.setTermsAndConditionsAccepted(true);
33 user.setTag("Created with the Mangopay Java SDK");
34 user.setUserCategory(UserCategory.PAYER);
35
36 var idempotencyKey = "pk7urhkW55-pTHf445678d";
37
38 User createUser = mangopay.getUserApi().create(idempotencyKey, user);
39
40 System.out.println(createUser);
41 }
42}

In order to retrieve the request made using this  idempotency:

Call - View API Response
1import com.mangopay.MangoPayApi;
2import com.mangopay.core.Address;
3import com.mangopay.entities.IdempotencyResponse;
4
5import java.lang.reflect.Field;
6
7public class GetWithKey {
8 public static void main(String[] args) throws Exception {
9 MangoPayApi mangopay = new MangoPayApi();
10 mangopay.getConfig().setClientId("your-client-id");
11 mangopay.getConfig().setClientPassword("your-api-key");
12
13 var idempotencyKey = "pk7urhkW55-pTHf445678d";
14
15 IdempotencyResponse respone = mangopay.getIdempotencyApi().get(idempotencyKey);
16
17 printObjectFields(respone);
18 System.out.println("resource: ");
19 printObjectFields(respone.getResource());
20
21 }
22
23 private static void printObjectFields(Object obj) {
24 Class<?> objClass = obj.getClass();
25 Field[] fields = objClass.getDeclaredFields();
26 for (Field field : fields) {
27 field.setAccessible(true);
28 try {
29 Object value = field.get(obj);
30 if (value instanceof Address) {
31 Address address = (Address) value;
32 System.out.println(field.getName() + ": " + address.getAddressLine1() + ", " +
33 address.getAddressLine2() + ", " +
34 address.getPostalCode() + " " +
35 address.getCity() + ", " +
36 address.getRegion() + ", " +
37 address.getCountry());
38 } else {
39 System.out.println(field.getName() + ": " + value);
40 }
41 } catch (IllegalAccessException e) {
42 e.printStackTrace();
43 }
44 }
45 }
46
47}
Output
1statusCode: 200
2contentLength: 712
3contentType: application/json; charset=utf-8
4date: Fri, 22 Mar 2024 10:13:10 GMT
5resource: com.mangopay.entities.UserNatural@b2c5e07
6requestUrl: https://api.sandbox.mangopay.com/v2.01/your-client-id/users/natural
7resource:
8firstName: Alex
9lastName: Smith
10address: 27 Rue de Rivoli, null, 75001 Paris, Île-de-France, FR
11birthday: 0
12birthplace: null
13nationality: null
14countryOfResidence: null
15occupation: null
16incomeRange: null
17proofOfIdentity: null
18proofOfAddress: null
19capacity: NORMAL

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:

1import com.mangopay.MangoPayApi;
2import com.mangopay.entities.User;
3import com.mangopay.core.Pagination;
4import com.mangopay.core.Sorting;
5import java.util.List;
6
7MangoPayApi api = new MangoPayApi();
8
9// get all users (with pagination and sorting)
10Pagination pagination = new Pagination(1, 8); // get 1st page, 8 items per page
11Sorting sort = new Sorting();
12sort.addField("SortingField", SortDirection.asc); // Sorting is an enum, its values: none, asc, desc
13List<User> users = api.getUserApi().getAll(pagination, sort);

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.

Call - Test rate limiting
1import com.mangopay.entities.RateLimit;
2
3import java.lang.reflect.Field;
4
5public class TryRateLimiting {
6
7 private RateLimit rateLimit;
8
9 public static int callCounter = 1;
10
11 public TryRateLimiting(int intervalMinutes) {
12 this.rateLimit = new RateLimit(intervalMinutes);
13 }
14
15 public static void main(String[] args) {
16 // Rate limit with allowed calls equal to 10 for demonstration purposes)
17 TryRateLimiting example = new TryRateLimiting(1);
18 example.rateLimit.setCallsRemaining(7);
19 example.rateLimit.setResetTimeSeconds(System.currentTimeMillis() / 1000 + (example.rateLimit.getIntervalMinutes() * 60)); // Set initial reset time
20
21 var calls = 10;
22 // Simulate multiple API calls
23 for (int i = 0; i < calls; i++) {
24 example.makeAPICall();
25 callCounter++;
26 }
27 }
28
29 // Simulate making an API call
30 public void makeAPICall() {
31
32 // Check if the current time has passed the reset time, if so reset the rate limit
33 long currentTimeSeconds = System.currentTimeMillis() / 1000;
34 if (currentTimeSeconds >= rateLimit.getResetTimeSeconds()) {
35 rateLimit.setCallsMade(0);
36 rateLimit.setCallsRemaining(rateLimit.getAllowedCalls());
37 rateLimit.setResetTimeSeconds(currentTimeSeconds + (rateLimit.getIntervalMinutes() * 60));
38 }
39
40 if (rateLimit.getCallsRemaining() > 0) {
41 System.out.println("Call #" + callCounter);
42 System.out.println("API Call made");
43
44 rateLimit.setCallsMade(rateLimit.getCallsMade() + 1);
45 rateLimit.setCallsRemaining(rateLimit.getCallsRemaining() - 1);
46
47 printObjectFields(rateLimit);
48 } else {
49 System.out.println("Call #" + callCounter);
50 System.out.println("Rate limit exceeded. ");
51 }
52 }
53
54 private static void printObjectFields(Object obj) {
55 Class<?> objClass = obj.getClass();
56 Field[] fields = objClass.getDeclaredFields();
57 for (Field field : fields) {
58 field.setAccessible(true);
59 try {
60 Object value = field.get(obj);
61 System.out.println(field.getName() + ": " + value);
62 } catch (IllegalAccessException e) {
63 e.printStackTrace();
64 }
65 }
66 }
67}
Output
1Call #1
2API Call made
3intervalMinutes: 1
4callsMade: 1
5callsRemaining: 6
6resetTimeSeconds: 1711115417
7Call #2
8API Call made
9intervalMinutes: 1
10callsMade: 2
11callsRemaining: 5
12resetTimeSeconds: 1711115417
13Call #3
14API Call made
15intervalMinutes: 1
16callsMade: 3
17callsRemaining: 4
18resetTimeSeconds: 1711115417
19Call #4
20API Call made
21intervalMinutes: 1
22callsMade: 4
23callsRemaining: 3
24resetTimeSeconds: 1711115417
25Call #5
26API Call made
27intervalMinutes: 1
28callsMade: 5
29callsRemaining: 2
30resetTimeSeconds: 1711115417
31Call #6
32API Call made
33intervalMinutes: 1
34callsMade: 6
35callsRemaining: 1
36resetTimeSeconds: 1711115417
37Call #7
38API Call made
39intervalMinutes: 1
40callsMade: 7
41callsRemaining: 0
42resetTimeSeconds: 1711115417
43Call #8
44Rate limit exceeded.
45Call #9
46Rate limit exceeded.
47Call #10
48Rate limit exceeded.

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:

1try {
2 this.api.getUserApi().getWallets(userId, pagination, filter, null);
3} catch (ResponseException e) {
4 assertEquals(401, e.getResponseHttpCode());
5}