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

# Java SDK

**Package:** [mangopay4-java-sdk](https://central.sonatype.com/artifact/com.mangopay/mangopay4-java-sdk)

---

## 2.70.0 - Oct 1, 2026

#### [2.70.0 - Oct 1, 2026](/release-notes/sdk/java/2-70-0)

Added

* Extended Preauthorization feature to rename Deposit Preauthorization
* `createExtendedPreauthorizedPayIn` on `PayInApi`
* `ExtendedPreauthorizationId` on `Transaction`
* Extended Preauthorization event types
* Settlement event types
* `ProfilingAttemptReference` on SCA users

Deprecated

* Deposit Preauthorization feature deprecated

## 2.69.0 - Sep 2, 2026

#### [2.69.0 - Sep 2, 2026](/release-notes/sdk/java/2-69-0)

Changed

* Test framework migrated from JUnit 4 to JUnit 5
* Updated dependencies

## 2.68.0 - Sep 1, 2026

#### [2.68.0 - Sep 1, 2026](/release-notes/sdk/java/2-68-0)

Added

* `KycInformation` containing `KycRenewalDeadline` on regulatory status endpoint
* Account funding transactions (AFT) on card direct pay-ins
* GET Acquiring PayPal Data Collection
* Idempotency key on `POST Create a PayPal PayIn` (v2)

Deprecated

* `PayInPaymentDetailsPayPal.ShippingAddress` accessors

## 2.67.0 - Aug 18, 2026

#### [2.67.0 - Aug 18, 2026](/release-notes/sdk/java/2-67-0)

Added

* Support for multi-session PSC flow on hosted KYB for Business
* Identity verification event types
* GET List Intent external providers

Changed

* `Tag` on intents and splits

## 2.66.0 - Jul 14, 2026

#### [2.66.0 - Jul 14, 2026](/release-notes/sdk/java/2-66-0)

Fixed

* Echo Settlement validation errors response mapping

Deprecated

* Non-SCA user methods and models
* Deposit PayIn complement endpoints

## 2.65.0 - June 24, 2026

#### [2.65.0 - June 24, 2026](/release-notes/sdk/java/2-65-0)

Added

* `FlowDescriptor` for declaring pay-in `Beneficiaries`
* Support for `Email` on webhooks
* Support for `CreateReport.DateRangeBy` on reports (replacing `DateFilterBy`)

Deprecated

* `CreateReport.DateFilterBy`

## 2.64.0 - May 21, 2026

#### [2.64.0 - May 21, 2026](/release-notes/sdk/java/2-64-0)

Added

* Recurring Apple Pay and Google Pay pay-ins
* PayPal deposit preauthorizations
* Extra fields on existing card pay-in responses
* Local Virtual Account properties for DK, AU, LI

Deprecated

* Legacy recurring pay-in methods on `PayInApi`

Fixed

* Serialization and deserialization bugs surfaced while wiring recurring pay-ins

Changed

* `DepositDeserializer` returns the correct deposit subtype

## 2.63.0 - May 4, 2026

#### [2.63.0 - May 4, 2026](/release-notes/sdk/java/2-63-0)

Added

* `IdempotencyResponse.errorResource` for failed idempotent calls

## 2.62.1 - Apr 30, 2026

#### [2.62.1 - Apr 30, 2026](/release-notes/sdk/java/2-62-1)

Fixed

* SCA `RedirectUrl` rendering on 401 responses with no body

## 2.62.0 - Mar 30, 2026

#### [2.62.0 - Mar 30, 2026](/release-notes/sdk/java/2-62-0)

Breaking change

* Idempotency resource mapping overhaul
* Removal of deprecated items

Added

* Klarna discount property on line items

---

## 2.61.0 - Mar 23, 2026

### Added

#### Support for mTLS authentication

To support mTLS authentication for [SCA on platforms](/guides/sca/platform), which is required for platforms taking [SCA-triggering action under proxy](/guides/sca/proxy-management):

* Added `keyStore`, `keyStorePassword` and `cachedSslContext` to  `Configuration.java`
* Added `buildSslContext()` method to `Configuration.java` which initializes, caches and returns a `SSLContext `
* Updated the `configureSslContext()` method in `RestTool.java` to use the `buildSslContext()` method from above
* Updated the requests logic to add the mTLS certificate if present
* Updated `README.md` file with details on [how to configure mTLS for the SDK](/guides/sca/platform#4-integrate-mtls-in-the-sdk)

**Note:** The SDK requires **TLS 1.2+** for TLS compliance, even for non-mTLS connections, in line with [Mangopay's security guidelines](/security#2-a-tls-and-https).

## 2.60.1 - Feb 19, 2026

### Added

#### ChargeBearer body parameter on payouts

On [POST Create a Payout](/api-reference/payouts/create-payout), platforms can now request to pay all SWIFT fees using the `OUR` value of the new `ChargeBearer` property ([API release note](/release-notes/api/2026-02-16)):

* Added `ChargeBearer` param (String) to `PayOutPaymentDetailsBankWire` class
* Updated the `PayOutSerializer` to include `ChargeBearer` on `PayOutPaymentDetailsBankWire` serialization
* Updated the `PayOutDeserializer` to deserialize the `ChargeBearer` and include it in `PayOutPaymentDetailsBankWire`
* Updated tests

#### AuthenticationType response property on card pay-ins

The `AuthenticationResult.AuthenticationType` response property is now returned on card pay-ins ([API release note](/release-notes/api/2026-02-23)):

* Added the `AuthenticationResult` class
* Added `AuthenticationResult` param (Object containing AuthenticationType) to `CardPreauthorization`, `CardValidation`, `Deposit`, `PayIn` classes
* Updated tests

#### TelephoneOrder body parameter on recurring card pay-ins (CIT and MIT)

To support the `TelephoneOrder` property on [POST Create a Recurring PayIn](/api-reference/recurring-card-payins/create-recurring-card-payin) (both CIT and MIT payloads):

* Added `PaymentCategory` (String) to `RecurringPayInCIT` and `RecurringPayInMIT` classes
* Updated the `RecurringPayInDeserializer` to deserialize the `PaymentCategory` and include it in `PayInPaymentDetailsCard`
* Updated tests

## 2.60.0 - Feb 12, 2026

### Users

### Possible breaking change

#### User serializer for natural Owner users

> **Warning**
>
> **Caution - Possible breaking change**
>
> * In the `UserSerializer`, the `Birthday` property of the `NaturalUser` now defaults to `NULL` instead of `0` if not set. This change prevents inadvertently updating the `Birthday` for `OWNER` Users, but it **may introduce an error** when **creating** an Owner user if you didn't previously set the `Birthday`.

### FX

### Breaking change

#### Custom fees

To support percentage-based FX fees ([API release note](/release-notes/api/2026-02-11)):

> **Warning**
>
> **Caution - Breaking change**
>
> * The `CreateInstantConversion.Fees` type is now `CustomFees` instead of `Money`, to support the new FX fees structure of `Type` (`PERCENTAGE` | `FIXED`) and `Value`

* Added `Fees` to `CreateConversionQuote`
* Added `Fees` and `RequestedFees` to `ConversionQuote`
* Added `RequestedFees` to `Conversion`

### Added

#### User margin

To support the FX user margin ([API release note](/release-notes/api/2026-02-11)):

* Added `UserMargin` to `CreateInstantConversion` and `CreateConversionQuote`
* Added `MarginsResponse` to `Conversion` and `ConversionQuote`

### Echo

### Breaking change

#### Settlement upload endpoints

To support the new behavior of the [POST Create a Settlement](/api-reference/settlements/create-settlement) endpoint to obtain an `UploadUrl`:

* Updated `settlement_sample.csv` and tests
* Added `FileName` and `UploadUrl` to `Settlement`

> **Warning**
>
> **Caution - Breaking change**
>
> * Replaced `upload` method in `SettlementApi` with `generateUploadUrl`:
>
> ```java Java
> // null idempotencyKey in this example
> Settlement settlement = api.getSettlementApi().generateUploadUrl(settlementFileName, null); 
> ```

> **Warning**
>
> **Caution - Breaking change**
>
> * Replaced `update` method in `SettlementApi` with `generateNewUploadUrl`:
>
> ```java Java
> Settlement dto = new Settlement().setFileName("new_file_name_settlement.csv");
> dto.setId(existingSettlement.getSettlementId()); 
> Settlement newUploadUrl = api.getSettlementApi().generateNewUploadUrl(dto);
> ```

### Added

#### GET validations for a Settlement endpoint

To support the [GET View validation errors for a Settlement](/api-reference/settlements/view-settlement-validations) endpoint:

* Added `SettlementValidation`, `SettlementValidationFooter`, `SettlementValidationLine` classes
* Added `getValidations` method to `SettlementApi`

**`Java`**

```java Java
// in this example, Pagination is null
SettlementValidation validation = api.getSettlementApi().getValidations(settlement.getSettlementId(), null);
```

#### PUT Cancel a Settlement endpoint

To support the [PUT Cancel a Settlement](/api-reference/settlements/cancel-settlement) endpoint:

* Added `cancel` method to `SettlementApi`

**`Java`**

```java Java
// in this case, the IdempotencyKey is null
Settlement canceled = api.getSettlementApi().cancel(settlement.getSettlementId(), null);
```

#### Intent unfunded amounts and source wallet

* Added `SplitOriginWalletId` to `PayInIntentLineItem` and `PayInIntentSplit`
* Added `UnfundedSellerAmount` to `PayInIntentLineItem`
* Added `UnfundedAmount` to `PayInIntent`

#### POST Create an Intent Refund

To support [POST Create an Intent Refund](/api-reference/intents/create-intent-refund):

* Added `Refund` and `Capture` to `PayInIntent`
* Added `createPayInIntentRefund` method to `PayInApi`:

**`Java`**

```java Java
// idempotencyKey is null in this example
api.getPayInApi().createPayInIntentRefund(intentId, refundToBeCreated, null);
```

#### POST Reverse an Intent Refund

To support [POST Reverse an Intent Refund](/api-reference/intents/create-intent-refund):

* Added `reversePayInIntentRefund` method to `PayInApi`:

**`Java`**

```java Java
// idempotencyKey is null in this example
PayInIntent reverseResult = api.getPayInApi().reversePayInIntentRefund(intent.getId(), intent.getRefund().getId(), reverseToBeCreated, null);
```

#### POST Create an Intent Dispute

To support [POST Create an Intent Dispute](/api-reference/intents/create-intent-refund):

* Added `Dispute` to `PayInIntent`
* Added `createPayInIntentDispute` method to `PayInApi`:

**`Java`**

```java Java
// idempotencyKey is null in this example
PayInIntent disputeResult = api.getPayInApi().createPayInIntentDispute(intent.getId(), intent.getCapture().getId(), disputeToBeCreated, null);
```

#### PUT Update an Intent Dispute

To support [PUT Update an Intent Dispute](/api-reference/intents/create-intent-dispute):

* Added `Decision` to `PayInIntent`
* Added `updatePayInIntentDisputeOutcome` method to `PayInApi`:

**`Java`**

```java Java
PayInIntent dto = new PayInIntent().setDecision("DEFENDED");
PayInIntent updatedDispute = api.getPayInApi().updatePayInIntentDisputeOutcome(intent.getId(), intent.getCapture().getId(), intent.getDispute().getId(), dto);
```

## 2.59.0 - Jan 30, 2026

### Added

#### Support for new SCA status endpoint

The SDK now supports the new [GET View the SCA status of a User](/api-reference/users/view-user-sca-status) endpoint.

New method in `UserApi`:

**`Java`**

```java Java
import com.mangopay.entities.subentities.ScaStatus;

/**
    * Get SCA status
    * @param userId User identifier
    * @return ScaStatus instance
    * @throws Exception
    */
   ScaStatus getScaStatus(String userId) throws Exception;
```

New `ScaStatus` class:

**`Java expandable`**

```java Java expandable
package com.mangopay.entities.subentities;

import com.google.gson.annotations.SerializedName;
import com.mangopay.core.Dto;

public class ScaStatus extends Dto {
    @SerializedName("UserStatus")
    private String userStatus;

    @SerializedName("IsEnrolled")
    private Boolean isEnrolled;

    @SerializedName("LastEnrollmentDate")
    private Long lastEnrollmentDate;

    @SerializedName("LastConsentCollectionDate")
    private Long lastConsentCollectionDate;

    @SerializedName("ConsentScope")
    private ConsentScope consentScope;

    public String getUserStatus() {
        return userStatus;
    }

    public ScaStatus setUserStatus(String userStatus) {
        this.userStatus = userStatus;
        return this;
    }

    public Boolean getEnrolled() {
        return isEnrolled;
    }

    public ScaStatus setEnrolled(Boolean enrolled) {
        isEnrolled = enrolled;
        return this;
    }

    public Long getLastEnrollmentDate() {
        return lastEnrollmentDate;
    }

    public ScaStatus setLastEnrollmentDate(Long lastEnrollmentDate) {
        this.lastEnrollmentDate = lastEnrollmentDate;
        return this;
    }

    public Long getLastConsentCollectionDate() {
        return lastConsentCollectionDate;
    }

    public ScaStatus setLastConsentCollectionDate(Long lastConsentCollectionDate) {
        this.lastConsentCollectionDate = lastConsentCollectionDate;
        return this;
    }

    public ConsentScope getConsentScope() {
        return consentScope;
    }

    public ScaStatus setConsentScope(ConsentScope consentScope) {
        this.consentScope = consentScope;
        return this;
    }
}
```

New `ConsentScope` class:

**`Java expandable`**

```java Java expandable
package com.mangopay.entities.subentities;

import com.google.gson.annotations.SerializedName;
import com.mangopay.core.Dto;

public class ConsentScope extends Dto {
    @SerializedName("ContactInformationUpdate")
    private String contactInformationUpdate;

    @SerializedName("RecipientRegistration")
    private String recipientRegistration;

    @SerializedName("Transfer")
    private String transfer;

    @SerializedName("ViewAccountInformation")
    private String viewAccountInformation;

    public String getContactInformationUpdate() {
        return contactInformationUpdate;
    }

    public ConsentScope setContactInformationUpdate(String contactInformationUpdate) {
        this.contactInformationUpdate = contactInformationUpdate;
        return this;
    }

    public String getRecipientRegistration() {
        return recipientRegistration;
    }

    public ConsentScope setRecipientRegistration(String recipientRegistration) {
        this.recipientRegistration = recipientRegistration;
        return this;
    }

    public String getTransfer() {
        return transfer;
    }

    public ConsentScope setTransfer(String transfer) {
        this.transfer = transfer;
        return this;
    }

    public String getViewAccountInformation() {
        return viewAccountInformation;
    }

    public ConsentScope setViewAccountInformation(String viewAccountInformation) {
        this.viewAccountInformation = viewAccountInformation;
        return this;
    }
}
```

New test in `UserApiImplTest`:

**`Java expandable`**

```java Java expandable
    @Test
    public void getScaStatus() throws Exception {
        ScaStatus scaStatus = api.getUserApi().getScaStatus(ACTIVE_USER_NATURAL_SCA_ID);

        assertNotNull(scaStatus);
        assertEquals(true, scaStatus.getEnrolled());
        assertNotNull(scaStatus.getLastEnrollmentDate());
        assertNotNull(scaStatus.getConsentScope().getContactInformationUpdate());
        assertEquals("ACTIVE", scaStatus.getUserStatus());
    }
```

#### New event types

New `EventType`:

**`Java expandable`**

```java Java expandable
package com.mangopay.core.enumerations;
/**
 * Event types enumeration.
 */
public enum EventType {
    SCA_CONTACT_INFORMATION_UPDATE_CONSENT_GIVEN,
    SCA_CONTACT_INFORMATION_UPDATE_CONSENT_REVOKED,
    SCA_TRANSFER_CONSENT_GIVEN,
    SCA_TRANSFER_CONSENT_REVOKED,
    SCA_RECIPIENT_REGISTRATION_CONSENT_GIVEN,
    SCA_RECIPIENT_REGISTRATION_CONSENT_REVOKED,
    SCA_VIEW_ACCOUNT_INFORMATION_CONSENT_GIVEN,
    SCA_VIEW_ACCOUNT_INFORMATION_CONSENT_REVOKED,
    SCA_EMAIL_VERIFIED,
    SCA_PHONE_NUMBER_VERIFIED
}
```

#### RecipientId property on payouts

New `RecipientId` property added to PayOutPaymentDetailsBankWire.

### Fixed

#### Fixed PayOut serializer to include PaymentRef

The PayOut serializer now returns the `PaymentRef` object.

## 2.58.1 - Jan 16, 2026

### Fixed

* Checks for `null` when parsing error responses from the API, resolving `JsonNull` unsupported operation exception on some HTTP 401 responses

## 2.58.0 - Dec 2, 2025

### Changed

* Migrated to V4 naming convention

## 2.57.1 - Nov 25, 2025

### Added

* Support for `ScaContext` on [POST Create a Recipient](/api-reference/recipients/create-recipient) for platforms taking action by [proxy with consent](/guides/sca/proxy-management) from the user ([API release note](/release-notes/api/2025-11-17))

## 2.57.0 - Oct 27, 2025

### Added

* New [POST Manage proxy consent for a User](/api-reference/users/manage-proxy-consent) endpoint to obtain and manage user consent via the hosted SCA experience (if proxy is activated). A proxy and user consent are now required to use the `USER_NOT_PRESENT` value for `ScaContext` ([API release note](/release-notes/api/2025-10-23))
* `ScaContext` request parameter newly added on all user POST and PUT endpoints, enabling the platform to request these actions with `USER_NOT_PRESENT` provided the proxy is in place, activated, and the user has given consent ([API release note](/release-notes/api/2025-10-23#sca%3A-scacontext-request-parameter-on-user-endpoints))
* Support for the `Licensor` property on [GET View a Client](/api-reference/client/view-client)
* Support for [GET View card details for a Web Card PayIn](/api-reference/web-card-payins/view-card-details-web-card-payin) endpoint

### Changed

* `x-tenant-id` deprecated as no longer necessary for UK platforms; the parameter is ignored by Mangopay

## 2.56.0 - Oct 1, 2025

### Added

* [Verification of Payee (VOP)](/guides/vop/recipients-payouts) API response fields (`RecipientVerificationOfPayee` and sub-properties) on the endpoints [GET View a Recipient](/api-reference/recipients/view-recipient), [POST Create a Recipient](/api-reference/recipients/create-recipient), [POST Create a Payout](/api-reference/payouts/create-payout) ([API release note](/release-notes/api/2025-09-30))
* Support for the [POST Cancel an Intent](/api-reference/intents/cancel-intent) endpoint for [Echo](/guides/echo), Mangopay's solution for platforms working with another third-party PSP for funds acquisition
* Support for [POST Submit data for a PayPal PayIn](/api-reference/paypal/submit-data-paypal-payin) endpoint

## 2.55.3 - Sep 23, 2025

### Added

* Support for `ProfilingAttemptReference` on all payment methods for Mangopay's Fraud Prevention solution
* Webhook event types for [Echo](/guides/echo), Mangopay's solution for third-party PSP integrations: `INTENT_AUTHORIZED`,`INTENT_CAPTURED`,`INTENT_REFUNDED`,`INTENT_REFUND_REVERSED`,`INTENT_DISPUTE_CREATED`,`INTENT_DISPUTE_DEFENDED`,`INTENT_DISPUTE_WON`,`INTENT_DISPUTE_LOST`,`INTENT_SETTLED_NOT_PAID`,`INTENT_PAID`,`SPLIT_CREATED`,`SPLIT_PENDING_FUNDS_RECEPTION`,`SPLIT_AVAILABLE`,`SPLIT_REJECTED`,`SPLIT_REVERSED`
* Support for `VirtualAccountPurpose` on Banking Alias object

## 2.55.2 - Sep 2, 2025

### Added

* Support for missing webhook event types

### Changed

* OAuth token refresh buffer before expiry updated to 30s

### Fixed

* Tests

## 2.55.1 - Aug 14, 2025

### Added

* Support for [POST Create a Quoted Conversion between Client Wallets](/api-reference/conversions/create-quoted-conversion-client-wallets) and [POST Create an Instant Conversion between Client Wallets](/api-reference/conversions/create-instant-conversion-client-wallets)

## 2.55.0 - Aug 7, 2025

### Added

Support for new Splits endpoints for Echo ([API release note](/release-notes/api/2025-07-16)):

* [PUT Update an Intent Split](/api-reference/intents/update-intent-split)
* [POST Execute an Intent Split](/api-reference/intents/execute-intent-split)
* [POST Reverse an Intent Split](/api-reference/intents/reverse-intent-split)
* [GET View an Intent Split](/api-reference/intents/view-intent-split)

New `ReportTypes` for Echo ([API release note](/release-notes/api/2025-08-06)):

* `ECHO_INTENT`
* `ECHO_INTENT_ACTION`
* `ECHO_SETTLEMENT`
* `ECHO_SPLIT`

## 2.54.1 - Jul 28, 2025

### Added

* `Sku` parameter on LineItem, for [Klarna PayIns](/api-reference/klarna/create-klarna-payin)
* support for new endpoint [View supported banks for Pay by Bank](/api-reference/pay-by-bank/view-supported-banks-pay-by-bank), to enable presentation of banks to user before Pay by Bank payment request

## 2.54.0 - Jul 18, 2025

### Added

Endpoints for [Mangopay Echo](/guides/echo), a solution for platforms working with another third-party PSP for funds acquisition (including via the Mirakl Connector):

* [POST Create an Intent](/api-reference/intents/create-intent)
* [GET View an Intent](/api-reference/intents/view-intent)
* [POST Create a Capture for an Intent](/api-reference/intents/create-intent-capture)
* [POST Create a Settlement](/api-reference/settlements/create-settlement)
* [PUT Update a Settlement](/api-reference/settlements/update-settlement)
* [GET View a Settlement](/api-reference/settlements/view-settlement)
* [POST Create an Intent Split](/api-reference/intents/create-intent-split)

## 2.53.0 - Jun 24, 2025

### Changed

* Minimum language version changed to **Java 8.0 or higher**
* Java `sourceCompatibility` changed to **1.8**
* README updated

### Added

* New endpoint [POST Create a Bizum PayIn](/api-reference/bizum/create-bizum-payin)
* New webhook event types for SCA enrollment - API release planned for Monday, note that these are triggered on enrollment not authentication:
* `SCA_ENROLLMENT_SUCCEEDED`
* `SCA_ENROLLMENT_FAILED`
* `SCA_ENROLLMENT_EXPIRED`
* New webhook event types for `UserCategory` change - API release planned for Monday:
* `USER_CATEGORY_UPDATED_TO_OWNER`
* `USER_CATEGORY_UPDATED_TO_PAYER`
* `USER_CATEGORY_UPDATED_TO_PLATFORM`
* Support for `PLATFORM` value to `UserCategory` enum

## 2.52.2 - Jun 12, 2025

### Updated

* release configurations

## 2.52.1 - Jun 12, 2025

### Added

* [US and CA virtual accounts](/release-notes/api/2025-06-12) for local pay-in collection
* [GET List Transactions for a Card Fingerprint](/api-reference/transactions/list-transactions-card-fingerprint#list-transactions-for-a-card-fingerprint)

## 2.52.0 - Jun 10, 2025

### Added

Endpoints for [new Reporting Service](/release-notes/api/2025-06-05) feature:

* [POST Create a Report](/api-reference/reporting/create-report)
* [GET View a Report](/api-reference/reporting/view-report)
* [GET List all Reports](/api-reference/reporting/list-reports)

Webhook event types for new Reporting Service:

* `REPORT_GENERATED`
* `REPORT_FAILED`

## 2.51.1 - Jun 6, 2025

### Added

* Support for `RecipientScope` query parameter on [GET List Recipients for a User](/api-reference/recipients/list-recipients-user)
* [POST Validate the format of User data](/api-reference/user-data-format/validate-user-data-format)
* [GET List Disputes for a PayIn](/api-reference/disputes/list-disputes-payin)

### Fixed

* `Status` enum value on Identity Verification object changed from `OUTDATED` to `OUT_OF_DATE`