> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.mangopay.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mangopay.com/_mcp/server. # Java SDK - 2.62.0 Mar 30, 2026 ## Idempotency mapping ### Breaking change #### Resource mapping overhaul in `IdempotencyApiImpl` **Warning:** This release contains several breaking changes to the idempotency resource mapping. If your code uses the idempotency API (`IdempotencyApi.get(...)`) and casts the returned resource to a specific type, please review the changes below carefully. #### Internal map changed from `HashMap` to `LinkedHashMap` The internal resource map was changed from `HashMap` to `LinkedHashMap` to guarantee insertion-order iteration. The idempotency resolution logic matches resource URLs using regex patterns, and the order in which entries are evaluated is now deterministic and intentional. Previously, the undefined iteration order of `HashMap` could cause incorrect type resolution for certain URLs. This is a breaking change for any code that relied on the old (undefined) iteration order. ### Potentially breaking change #### Ordering of existing entries changed Several existing entries were reordered so that more-specific URL patterns are evaluated before more-general ones. Notable reorderings include: * `settlement_cancel` and `settlement_generate_upload_url` now appear before `pay_in_intent_*` entries, because `/payins/intents/settlements/...` would otherwise be incorrectly matched by the broader pay-in intent patterns. * SCA user variants (`users_createnaturals_sca`, `users_createlegals_sca`) now appear before their non-SCA counterparts, because `/sca/users/...` URLs would otherwise match the shorter `/users/...` pattern first. * `transfers_createrefunds` now appears before `transfers_create` to avoid refund URLs being matched by the more general transfers pattern. * `banking_alias_create_iban` and `virtual_account_create` now appear before `wallets_create`, because `/wallets/%s/bankingaliases/...` and `/wallets/%s/virtualaccounts/...` would otherwise be matched by the wallet pattern first. If any custom tooling or tests relied on the previous position/index of a specific mapping, it will need to be updated. #### Previously unmapped endpoints now return typed models Before this release, any endpoint that was not present in the mapping returned its resource as a raw, untyped `Object` (a generic JSON structure, typically a `LinkedTreeMap`). Now that mappings have been added for the endpoints listed above, those same calls will return a properly deserialized model instance (e.g., `PayIn`, `Deposit`, `Conversion`, etc.). This is a **potential breaking change** if your code was already handling the untyped `Object` result — for example, by inspecting raw map keys, casting to `Map`, or using any logic that assumed the resource was not a strongly typed model. Such code will need to be updated to work with the actual model class instead. #### Regex URL pattern widened The URL-matching regex was updated from `[0-9a-zA-Z_]+` to `[0-9a-zA-Z_-]+` (hyphen added). This allows resource IDs that contain hyphens to be matched correctly. This is unlikely to be breaking but changes the set of URLs that are matched. ### Added #### New mappings The following resource mappings were added. These are additive, but they do affect the total size and iteration behavior of the map, which may have indirect effects on custom URL-matching logic: * **Card:** `card_validate` * **Pay-ins:** `payins_card_preauthorized_deposit`, `payins_deposit_preauthorized_prior_to_complement`, `payins_deposit_preauthorized_complement`, `payins_applepay-direct_create`, `payins_googlepay-direct_create`, `payins_googlepayv2-direct_create`, `payins_paypal-web_create`, `payins_paypal-web_create_v2`, `payins_payconiq-web_create`, `payins_payconiqv2-web_create`, `payins_mbway-web_create`, `payins_satispay-web_create`, `payins_blik-web_create`, `payins_bizum-web_create`, `payins_multibanco-web_create`, `payins_klarna-web_create`, `payins_ideal-web_create`, `payins_giropay-web_create`, `payins_bancontact-web_create`, `payins_twint-web_create`, `payins_swish-web_create`, `payins_paybybank-web_create`, `payins_recurring_registration`, `payins_recurring_card_direct`, `payment_method-metadata` * **Settlements:** `settlement_cancel`, `settlement_generate_upload_url` * **Pay-in intents:** `pay_in_intent_create_refund`, `pay_in_intent_reverse_refund`, `pay_in_intent_create_dispute` * **Payouts:** `payouts_instant_payout_eligibility` * **Users:** `users_validate_data_format`, `users_enroll_sca`, `users_manage_consent` * **KYC:** `kyc_page_create` * **Virtual accounts:** `virtual_account_create` * **Client:** `client_create_bankaccount_iban`, `client_create_payout` * **Reports:** `reports_request`, `reports_wallets_create` * **Conversions:** `create_instant_conversion`, `create_quoted_conversion`, `create_conversion_quote`, `create_client_wallets_quoted_conversion`, `create_client_wallets_instant_conversion` * **Deposits:** `deposits_create` * **Identity verification:** `identify_verification_create` * **Recipients:** `recipient_create`, `recipient_validate` * **UBO declarations:** `ubo_declaration_create`, `ubo_create` * **Acquiring:** `acquiring_payins_paypal_data_collection_create`, `acquiring_payins_card-direct_create`, `acquiring_payins_ideal-web_create`, `acquiring_payins_applepay-direct_create`, `acquiring_payins_googlepayv2-direct_create`, `acquiring_payins_paypal-web_create`, `acquiring_payins_createrefunds`, `acquiring_create_card_validation` ### Changed #### Tests Tests were added and refactored in `IdempotencyApiImplTest` and related test classes to cover all resource mappings, including all newly added entries and the reordered ones. --- ## Removal of deprecated items ### Breaking change #### `ukHeaderFlag` removed from `Configuration` The `ukHeaderFlag` property and its accessors (`isUkHeaderFlag()`, `setUkHeaderFlag(boolean)`) have been removed from the `Configuration` class. The flag was previously used to automatically inject the `x-tenant-id: uk` HTTP header for UK traffic on both regular API calls and OAuth token requests. Any code that calls `config.setUkHeaderFlag(true)` or `config.isUkHeaderFlag()` will fail to compile after upgrading. #### `createCardPreAuthorizedDepositPayIn` removed from `PayInApi` The `createCardPreAuthorizedDepositPayIn(CreateCardPreAuthorizedDepositPayIn, String)` method and its associated DTO `CreateCardPreAuthorizedDepositPayIn` have been removed from `PayInApi` and `PayInApiImpl`. These were previously marked `@Deprecated`. **Migration:** Use `createDepositPreauthorizedWithoutComplement` instead, which follows the same pattern as all other pay-in creation methods. #### Payconiq PayIn removed following discontinuation Payconiq was discontinued on 4th December 2025. All related SDK support has been removed: * Deleted `PayInPaymentDetailsPayconiq` class * Removed `createPayconiq(PayIn, String)` method from `PayInApi` and `PayInApiImpl` * Removed `PAYCONIQ` value from the `PayInPaymentType` enum * Removed URL mappings `payins_payconiq-web_create` and `payins_payconiqv2-web_create` from `ApiBase` and `IdempotencyApiImpl` Any code referencing `PayInPaymentDetailsPayconiq`, `PayInPaymentType.PAYCONIQ`, or `createPayconiq(...)` will fail to compile after upgrading. There is no migration path as the payment method is no longer available. --- ## Klarna discount parameter ### Added #### Klarna `Discount` parameter on `LineItem` A `Discount` field has been added to the `LineItem` class to support item-level discounts on Klarna pay-ins. * Added `discount` (`Integer`) field to `LineItem`, serialized as `"Discount"` in the JSON payload * Added `getDiscount()` getter and fluent `setDiscount(Integer)` setter This is a purely additive change with no breaking impact. ---