Getting startedRelease notesSDK

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<String, Object>, 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.