> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.mangopay.com/sdks/java/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mangopay.com/_mcp/server.

# 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](https://central.sonatype.com/artifact/com.mangopay/mangopay4-java-sdk)

> **Warning**
>
> **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).

> **Info**
>
> **Prerequisites**
>
> To run the Mangopay Java SDK, you’ll need:
>
> * A `ClientId` and an API key – if you don't have these, [contact Sales](https://mangopay.com/contact) to get access to the [Mangopay Dashboard](https://hub.mangopay.com/)
> * Java 8.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:

```shell
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:

```xml
<dependency>
    <groupId>com.mangopay</groupId>
    <artifactId>mangopay4-java-sdk</artifactId>
    <version>2.37.0</version>
</dependency>
```

#### 2. Initialize and configure the SDK

```java
import com.mangopay.MangoPayApi;

public class Main {
    public static void main(String[] args) throws Exception {
        MangoPayApi mangopay = new MangoPayApi();
        mangopay.getConfig().setClientId("your-client-id");
        mangopay.getConfig().setClientPassword("your-api-key");

        ...
    }
}
```

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

<table>
  <thead>
    <tr>
      <th class="header">
        Key
      </th>

      <th class="header">
        Type
      </th>

      <th class="header">
        Default value
      </th>

      <th class="header">
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td class="table-content">
        `setClientId`
      </td>

      <td class="table-content">
        string
      </td>

      <td class="table-content">
        None
      </td>

      <td class="table-content">
        Your Mangopay ClientId – can be found in the 

        [Dashboard](https://hub.mangopay.com/)

        .
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `setClientPassword`
      </td>

      <td class="table-content">
        string
      </td>

      <td class="table-content">
        None
      </td>

      <td class="table-content">
        Your Mangopay API key – can be found in the 

        [Dashboard](https://hub.mangopay.com/)

        .
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `setBaseUrl`
      </td>

      <td class="table-content">
        string
      </td>

      <td class="table-content">
        [https://api.sandbox.mangopay.com/v2.01/](https://api.sandbox.mangopay.com/v2.01/)
      </td>

      <td class="table-content">
        The API sandbox URL. Set to the sandbox environment by default. To enable production environment, set it to 

        [https://api.mangopay.com](https://api.mangopay.com)
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `setConnectTimeout`
      </td>

      <td class="table-content">
        integer
      </td>

      <td class="table-content">
        `60000`
      </td>

      <td class="table-content">
        Time to wait in milliseconds while trying to establish a connection before terminating the attempt and generating an error.
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `setReadTimeout`
      </td>

      <td class="table-content">
        integer
      </td>

      <td class="table-content">
        `60000`
      </td>

      <td class="table-content">
        Time to wait in milliseconds to receive a response before terminating the attempt and generating an error.
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `setDebugMode`
      </td>

      <td class="table-content">
        boolean
      </td>

      <td class="table-content">
        `false`
      </td>

      <td class="table-content">
        Activates the debug mode. Recommended only in Sandbox.
      </td>
    </tr>
  </tbody>
</table>

## 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](/api-reference/overview/idempotency) article.

**`Call - Create user with idempotency key`**

```java Call - Create user with idempotency key
import com.mangopay.MangoPayApi;
import com.mangopay.core.Address;
import com.mangopay.core.enumerations.CountryIso;
import com.mangopay.core.enumerations.UserCategory;
import com.mangopay.entities.User;
import com.mangopay.entities.UserNatural;

import java.lang.reflect.Field;

public class CreateNaturalUserWithKey {
    public static void main(String[] args) throws Exception {
        MangoPayApi mangopay = new MangoPayApi();
        mangopay.getConfig().setClientId("your-client-id");
        mangopay.getConfig().setClientPassword("your-api-key");

        UserNatural user = new UserNatural();
        Address address = new Address();

        address.setAddressLine1("27 Rue de Rivoli");
        address.setCity("Paris");
        address.setRegion("Île-de-France");
        address.setPostalCode("75001");
        address.setCountry(CountryIso.FR);

        user.setFirstName("Alex");
        user.setLastName("Smith");
        user.setEmail("alex.smith@mgp.com");
        user.setAddress(address);
        user.setBirthday(655772400);
        user.setNationality(CountryIso.FR);
        user.setCountryOfResidence(CountryIso.FR);
        user.setTermsAndConditionsAccepted(true);
        user.setTag("Created with the Mangopay Java SDK");
        user.setUserCategory(UserCategory.PAYER);

        var idempotencyKey = "pk7urhkW55-pTHf445678d";

        User createUser = mangopay.getUserApi().create(idempotencyKey, user);
        
        System.out.println(createUser);
    }
}
```

In order to retrieve the request made using this  idempotency:

**`Call - View API Response`**

```java Call - View API Response
import com.mangopay.MangoPayApi;
import com.mangopay.core.Address;
import com.mangopay.entities.IdempotencyResponse;

import java.lang.reflect.Field;

public class GetWithKey {
    public static void main(String[] args) throws Exception {
        MangoPayApi mangopay = new MangoPayApi();
        mangopay.getConfig().setClientId("your-client-id");
        mangopay.getConfig().setClientPassword("your-api-key");

        var idempotencyKey = "pk7urhkW55-pTHf445678d";

        IdempotencyResponse respone = mangopay.getIdempotencyApi().get(idempotencyKey);

        printObjectFields(respone);
        System.out.println("resource: ");
        printObjectFields(respone.getResource());
       
    }

    private static void printObjectFields(Object obj) {
        Class<?> objClass = obj.getClass();
        Field[] fields = objClass.getDeclaredFields();
        for (Field field : fields) {
            field.setAccessible(true);
            try {
                Object value = field.get(obj);
                if (value instanceof Address) {
                    Address address = (Address) value;
                    System.out.println(field.getName() + ": " + address.getAddressLine1() + ", " +
                                       address.getAddressLine2() + ", " +
                                       address.getPostalCode() + " " +
                                       address.getCity() + ", " +
                                       address.getRegion() + ", " +
                                       address.getCountry());
                } else {
                    System.out.println(field.getName() + ": " + value);
                }
            } catch (IllegalAccessException e) {
                e.printStackTrace();
            }
        }
    }
    
}
```

**`Output`**

```json Output
statusCode: 200
contentLength: 712
contentType: application/json; charset=utf-8
date: Fri, 22 Mar 2024 10:13:10 GMT
resource: com.mangopay.entities.UserNatural@b2c5e07
requestUrl: https://api.sandbox.mangopay.com/v2.01/your-client-id/users/natural
resource: 
firstName: Alex
lastName: Smith
address: 27 Rue de Rivoli, null, 75001 Paris, Île-de-France, FR
birthday: 0
birthplace: null
nationality: null
countryOfResidence: null
occupation: null
incomeRange: null
proofOfIdentity: null
proofOfAddress: null
capacity: NORMAL
```

### Pagination and filtering

For endpoints that support [pagination](/api-reference/overview/pagination) and [filtering](/api-reference/overview/filtering-sorting), 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:

```java
import com.mangopay.MangoPayApi;
import com.mangopay.entities.User;
import com.mangopay.core.Pagination;
import com.mangopay.core.Sorting;
import java.util.List;

MangoPayApi api = new MangoPayApi();

// get all users (with pagination and sorting)
Pagination pagination = new Pagination(1, 8); // get 1st page, 8 items per page
Sorting sort = new Sorting();
sort.addField("SortingField", SortDirection.asc); // Sorting is an enum, its values: none, asc, desc
List<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](/api-reference/overview/rate-limiting) article.

**`Call - Test rate limiting`**

```java Call - Test rate limiting
import com.mangopay.entities.RateLimit;

import java.lang.reflect.Field;

public class TryRateLimiting {

    private RateLimit rateLimit;

    public static int callCounter = 1;

    public TryRateLimiting(int intervalMinutes) {
        this.rateLimit = new RateLimit(intervalMinutes);
    }

    public static void main(String[] args) {
        // Rate limit with allowed calls equal to 10 for demonstration purposes)
        TryRateLimiting example = new TryRateLimiting(1); 
        example.rateLimit.setCallsRemaining(7); 
        example.rateLimit.setResetTimeSeconds(System.currentTimeMillis() / 1000 + (example.rateLimit.getIntervalMinutes() * 60)); // Set initial reset time

        var calls = 10;
        // Simulate multiple API calls
        for (int i = 0; i < calls; i++) {
            example.makeAPICall();
            callCounter++;
        }
    }
    
    // Simulate making an API call
    public void makeAPICall() {

        // Check if the current time has passed the reset time, if so reset the rate limit
        long currentTimeSeconds = System.currentTimeMillis() / 1000;
        if (currentTimeSeconds >= rateLimit.getResetTimeSeconds()) {
            rateLimit.setCallsMade(0);
            rateLimit.setCallsRemaining(rateLimit.getAllowedCalls());
            rateLimit.setResetTimeSeconds(currentTimeSeconds + (rateLimit.getIntervalMinutes() * 60));
        }

        if (rateLimit.getCallsRemaining() > 0) {
            System.out.println("Call #" + callCounter);
            System.out.println("API Call made");

            rateLimit.setCallsMade(rateLimit.getCallsMade() + 1);
            rateLimit.setCallsRemaining(rateLimit.getCallsRemaining() - 1);

            printObjectFields(rateLimit);
        } else {
            System.out.println("Call #" + callCounter);
            System.out.println("Rate limit exceeded. ");
        }
    }

    private static void printObjectFields(Object obj) {
        Class<?> objClass = obj.getClass();
        Field[] fields = objClass.getDeclaredFields();
        for (Field field : fields) {
            field.setAccessible(true);
            try {
                Object value = field.get(obj);
                System.out.println(field.getName() + ": " + value);
            } catch (IllegalAccessException e) {
                e.printStackTrace();
            }
        }
    }
}
```

**`Output`**

```json Output
Call #1
API Call made
intervalMinutes: 1
callsMade: 1
callsRemaining: 6
resetTimeSeconds: 1711115417
Call #2
API Call made
intervalMinutes: 1
callsMade: 2
callsRemaining: 5
resetTimeSeconds: 1711115417
Call #3
API Call made
intervalMinutes: 1
callsMade: 3
callsRemaining: 4
resetTimeSeconds: 1711115417
Call #4
API Call made
intervalMinutes: 1
callsMade: 4
callsRemaining: 3
resetTimeSeconds: 1711115417
Call #5
API Call made
intervalMinutes: 1
callsMade: 5
callsRemaining: 2
resetTimeSeconds: 1711115417
Call #6
API Call made
intervalMinutes: 1
callsMade: 6
callsRemaining: 1
resetTimeSeconds: 1711115417
Call #7
API Call made
intervalMinutes: 1
callsMade: 7
callsRemaining: 0
resetTimeSeconds: 1711115417
Call #8
Rate limit exceeded. 
Call #9
Rate limit exceeded. 
Call #10
Rate 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:

```java
try {
  this.api.getUserApi().getWallets(userId, pagination, filter, null);
} catch (ResponseException e) {
  assertEquals(401, e.getResponseHttpCode());
}
```