Java SDK | Mangopay docs

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

Note: The SDK requires TLS 1.2+ for TLS compliance, even for non-mTLS connections, in line with Mangopay’s security guidelines.

2.60.1 - Feb 19, 2026

Added

ChargeBearer body parameter on payouts

On POST Create a Payout, platforms can now request to pay all SWIFT fees using the OUR value of the new ChargeBearer property (API release note):

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):

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 (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

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):

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):

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 endpoint to obtain an UploadUrl:

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

Caution - Breaking change

Replaced upload method in SettlementApi with generateUploadUrl:

Java

1 // null idempotencyKey in this example
2 Settlement settlement = api.getSettlementApi().generateUploadUrl(settlementFileName, null);

Caution - Breaking change

Replaced update method in SettlementApi with generateNewUploadUrl:

Java

1 Settlement dto = new Settlement().setFileName("new_file_name_settlement.csv");
2 dto.setId(existingSettlement.getSettlementId()); 
3 Settlement newUploadUrl = api.getSettlementApi().generateNewUploadUrl(dto);

Added

GET validations for a Settlement endpoint

To support the GET View validations for a Settlement endpoint:

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

Java

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

PUT Cancel a Settlement endpoint

To support the PUT Cancel a Settlement endpoint:

Added cancel method to SettlementApi

Java

1 // in this case, the IdempotencyKey is null
2 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:

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

Java

1 // idempotencyKey is null in this example
2 api.getPayInApi().createPayInIntentRefund(intentId, refundToBeCreated, null);

POST Reverse an Intent Refund

To support POST Reverse an Intent Refund:

Added reversePayInIntentRefund method to PayInApi:

Java

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

POST Create an Intent Dispute

To support POST Create an Intent Dispute:

Added Dispute to PayInIntent
Added createPayInIntentDispute method to PayInApi:

Java

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

PUT Update an Intent Dispute

To support PUT Update an Intent Dispute:

Added Decision to PayInIntent
Added updatePayInIntentDisputeOutcome method to PayInApi:

Java

1 PayInIntent dto = new PayInIntent().setDecision("DEFENDED");
2 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 endpoint.

New method in UserApi:

Java

1 import com.mangopay.entities.subentities.ScaStatus;
2 
3 /**
4     * Get SCA status
5     * @param userId User identifier
6     * @return ScaStatus instance
7     * @throws Exception
8     */
9    ScaStatus getScaStatus(String userId) throws Exception;

New ScaStatus class:

Java expandable

1 package com.mangopay.entities.subentities;
2 
3 import com.google.gson.annotations.SerializedName;
4 import com.mangopay.core.Dto;
5 
6 public class ScaStatus extends Dto {
7     @SerializedName("UserStatus")
8     private String userStatus;
9 
10     @SerializedName("IsEnrolled")
11     private Boolean isEnrolled;
12 
13     @SerializedName("LastEnrollmentDate")
14     private Long lastEnrollmentDate;
15 
16     @SerializedName("LastConsentCollectionDate")
17     private Long lastConsentCollectionDate;
18 
19     @SerializedName("ConsentScope")
20     private ConsentScope consentScope;
21 
22     public String getUserStatus() {
23         return userStatus;
24     }
25 
26     public ScaStatus setUserStatus(String userStatus) {
27         this.userStatus = userStatus;
28         return this;
29     }
30 
31     public Boolean getEnrolled() {
32         return isEnrolled;
33     }
34 
35     public ScaStatus setEnrolled(Boolean enrolled) {
36         isEnrolled = enrolled;
37         return this;
38     }
39 
40     public Long getLastEnrollmentDate() {
41         return lastEnrollmentDate;
42     }
43 
44     public ScaStatus setLastEnrollmentDate(Long lastEnrollmentDate) {
45         this.lastEnrollmentDate = lastEnrollmentDate;
46         return this;
47     }
48 
49     public Long getLastConsentCollectionDate() {
50         return lastConsentCollectionDate;
51     }
52 
53     public ScaStatus setLastConsentCollectionDate(Long lastConsentCollectionDate) {
54         this.lastConsentCollectionDate = lastConsentCollectionDate;
55         return this;
56     }
57 
58     public ConsentScope getConsentScope() {
59         return consentScope;
60     }
61 
62     public ScaStatus setConsentScope(ConsentScope consentScope) {
63         this.consentScope = consentScope;
64         return this;
65     }
66 }

New ConsentScope class:

Java expandable

1 package com.mangopay.entities.subentities;
2 
3 import com.google.gson.annotations.SerializedName;
4 import com.mangopay.core.Dto;
5 
6 public class ConsentScope extends Dto {
7     @SerializedName("ContactInformationUpdate")
8     private String contactInformationUpdate;
9 
10     @SerializedName("RecipientRegistration")
11     private String recipientRegistration;
12 
13     @SerializedName("Transfer")
14     private String transfer;
15 
16     @SerializedName("ViewAccountInformation")
17     private String viewAccountInformation;
18 
19     public String getContactInformationUpdate() {
20         return contactInformationUpdate;
21     }
22 
23     public ConsentScope setContactInformationUpdate(String contactInformationUpdate) {
24         this.contactInformationUpdate = contactInformationUpdate;
25         return this;
26     }
27 
28     public String getRecipientRegistration() {
29         return recipientRegistration;
30     }
31 
32     public ConsentScope setRecipientRegistration(String recipientRegistration) {
33         this.recipientRegistration = recipientRegistration;
34         return this;
35     }
36 
37     public String getTransfer() {
38         return transfer;
39     }
40 
41     public ConsentScope setTransfer(String transfer) {
42         this.transfer = transfer;
43         return this;
44     }
45 
46     public String getViewAccountInformation() {
47         return viewAccountInformation;
48     }
49 
50     public ConsentScope setViewAccountInformation(String viewAccountInformation) {
51         this.viewAccountInformation = viewAccountInformation;
52         return this;
53     }
54 }

New test in UserApiImplTest:

Java expandable

1     @Test
2     public void getScaStatus() throws Exception {
3         ScaStatus scaStatus = api.getUserApi().getScaStatus(ACTIVE_USER_NATURAL_SCA_ID);
4 
5         assertNotNull(scaStatus);
6         assertEquals(true, scaStatus.getEnrolled());
7         assertNotNull(scaStatus.getLastEnrollmentDate());
8         assertNotNull(scaStatus.getConsentScope().getContactInformationUpdate());
9         assertEquals("ACTIVE", scaStatus.getUserStatus());
10     }

New event types

New EventType:

Java expandable

1 package com.mangopay.core.enumerations;
2 /**
3  * Event types enumeration.
4  */
5 public enum EventType {
6     SCA_CONTACT_INFORMATION_UPDATE_CONSENT_GIVEN,
7     SCA_CONTACT_INFORMATION_UPDATE_CONSENT_REVOKED,
8     SCA_TRANSFER_CONSENT_GIVEN,
9     SCA_TRANSFER_CONSENT_REVOKED,
10     SCA_RECIPIENT_REGISTRATION_CONSENT_GIVEN,
11     SCA_RECIPIENT_REGISTRATION_CONSENT_REVOKED,
12     SCA_VIEW_ACCOUNT_INFORMATION_CONSENT_GIVEN,
13     SCA_VIEW_ACCOUNT_INFORMATION_CONSENT_REVOKED,
14     SCA_EMAIL_VERIFIED,
15     SCA_PHONE_NUMBER_VERIFIED
16 }

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 for platforms taking action by proxy with consent from the user (API release note)

2.57.0 - Oct 27, 2025

Added

New POST Manage proxy consent for a User 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)
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)
Support for the Licensor property on GET View a Client
Support for GET View card details for a 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) API response fields (RecipientVerificationOfPayee and sub-properties) on the endpoints GET View a Recipient, POST Create a Recipient, POST Create a Payout (API release note)
Support for the POST Cancel an Intent endpoint for Echo, Mangopay’s solution for platforms working with another third-party PSP for funds acquisition
Support for POST Submit data for a 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, 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 and POST Create an Instant Conversion between Client Wallets

2.55.0 - Aug 7, 2025

Added

Support for new Splits endpoints for Echo (API release note):

New ReportTypes for Echo (API release note):

ECHO_INTENT
ECHO_INTENT_ACTION
ECHO_SETTLEMENT
ECHO_SPLIT

2.54.1 - Jul 28, 2025

Added

Sku parameter on LineItem, for Klarna PayIns
support for new endpoint View supported banks for 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, a solution for platforms working with another third-party PSP for funds acquisition (including via the Mirakl Connector):

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
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 for local pay-in collection
GET List Transactions for a Card Fingerprint

2.52.0 - Jun 10, 2025

Added

Endpoints for new Reporting Service feature:

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
POST Validate the format of User data
GET List Disputes for a PayIn

Fixed

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