Adyen Java API Library v38.0.0

Breaking Changes 🛠

• Checkout API

  • Remove DotpayDetails and GiropayDetails
  • Remove enum PAYSAFECARD from PaymentDetails

• Management API

  • Remove GiroPayInfo
  • Remove enum `PAYSHOP from PaymentMethodResponse

Features 💎

• Checkout API

  • Add Surcharge (#1445) and EnhancedSchemeData (supporting Airline enhanced scheme data) in PaymentRequest
  • Add EnhancedSchemeData (supporting Airline enhanced scheme data) in PaymentCaptureRequest
  • Add fraudRiskLevel in ResponseAdditionalDataCommon
  • Add enum PAYSAFECARD from StoredPaymentMethodDetails

• Payment Classic API

  • Add fraudRiskLevel in ResponseAdditionalDataCommon

• Payout API

  • Add fraudRiskLevel in ResponseAdditionalDataCommon

• Webhooks

  • Add TECHNICAL_CANCEL event code in NotificationRequestItem (#1481)

• Management API

  • Add supportEmail field to the AfterpayTouchInfo
  • Add enum PAYMENTDESIGNATORCONTRACT in JCBInfo
  • Add PayByBankPlaidInfo
  • Add enum PAYBYBANK_PLAID in PaymentMethodResponse
  • Add domainSuffix field to Profile
  • In SplitConfigurationRule add enums CHARGED, DEFERRED_DEBIT and PREPAID (#1457)
  • Add enableGratuities to the Standalone model

Fixes ⛑️

• Avoid null in User-Agent header by @gcatanese in #1483

Other Changes 🖇️

• Balance webhooks in README by @gcatanese in #1478

Full Changelog: v37.0.0...v38.0.0

Adyen Java API Library v37.0.0

This release brings significant improvements, new features, and few breaking changes to the Adyen Java API Library. It marks a major milestone in aligning the library more closely with Adyen’s OpenAPI specifications and improving the ✨ Developer Experience ✨

Find below what's new as well as a detailed summary of the Breaking Changes, and what you should do or consider.

Please review the Breaking Changes and update your integrations accordingly. For any questions, feel free to open an issue or consult our API Explorer.

---

🚀 Highlights

• Improved OpenAPI Code Generation: Source code is now more idiomatic, flexible, and better aligned with Adyen's OpenAPI specifications.
• Automated Webhook Handler Generation: Webhook handlers and models are now automatically generated and updated with each release.
• Refined Package Structure: Several APIs have been moved to more specific packages for better discoverability and maintainability.

---

🛠 Breaking Changes

🔁 Webhook Events Renamed

Several webhook TypeEnum names have been updated for clarity and consistency.
Note: the actual string value of the enum didn't change.

ConfigurationWebhooks

• AccountHolderNotificationRequest
  • CREATED → BALANCEPLATFORM_ACCOUNTHOLDER_CREATED
  • UPDATED → BALANCEPLATFORM_ACCOUNTHOLDER_UPDATED
• BalanceAccountNotificationRequest
  • CREATED → BALANCEPLATFORM_BALANCEACCOUNT_CREATED
  • UPDATED → BALANCEPLATFORM_BALANCEACCOUNT_UPDATED
• CardOrderNotificationRequest
  • CREATED → BALANCEPLATFORM_CARDORDER_CREATED
  • UPDATED → BALANCEPLATFORM_CARDORDER_UPDATED
• PaymentNotificationRequest
  • CREATED → BALANCEPLATFORM_PAYMENTINSTRUMENT_CREATED
  • UPDATED → BALANCEPLATFORM_PAYMENTINSTRUMENT_UPDATED
• SweepConfigurationNotificationRequest
  • CREATED → BALANCEPLATFORM_BALANCEACCOUNTSWEEP_CREATED
  • UPDATED → BALANCEPLATFORM_BALANCEACCOUNTSWEEP_UPDATED
  • DELETED → BALANCEPLATFORM_BALANCEACCOUNTSWEEP_DELETED

TransferWebhooks

• TransferNotificationRequest
  • CREATED → BALANCEPLATFORM_TRANSFER_CREATED
  • UPDATED → BALANCEPLATFORM_TRANSFER_UPDATED

🔒 Read-Only Attributes

Properties marked as readOnly in the OpenAPI specs no longer expose setters or builder methods. These values must be set using constructors instead.

Note: this change might affect your test code, where the methods might have been used to setup test and mock data.

---

🔍 Important Changes

📦 Service Class Refactoring

The following services have been moved to their own dedicated packages
Services in the old location are deprecated and will be removed in a future release.

Note: There are no changes in functionality (the same code is now available in the new location), please update your code accordingly.

Old Location	New Location
com.adyen.service.StoredValueApi	com.adyen.service.storedvalue.StoredValueApi
com.adyen.service.BinLookupApi	com.adyen.service.binlookup.BinLookupApi
com.adyen.service.BalanceControlApi	com.adyen.service.balancecontrol.BalanceControlApi
com.adyen.service.DataProtectionApi	com.adyen.service.dataprotection.DataProtectionApi
com.adyen.service.DisputesApi	com.adyen.service.disputes.DisputesApi
com.adyen.service.PaymentsAppApi	com.adyen.service.paymentsapp.PaymentsAppApi
com.adyen.service.PosMobileApi	com.adyen.service.posmobile.PosMobileApi

🪝 Webhook Handling

Webhook handling is now modernized and streamlined:

• Automation: Auto-generated handlers ensure that webhook events and models stay aligned with the changes in the OpenAPI specs
• Deprecated: Former BankingWebhookHandler class is now deprecated
• Recommended: Use instead the dedicated handler in the Webhook package (AcsWebhooks, ReportWebhooksHandler, ConfigurationWebhooks, TransferWebhooks, TransactionWebhooks, etc..)

// parse AccountHolderNotificationRequest
Optional<AccountHolderNotificationRequest> notificationRequest =
   new ConfigurationWebhooksHandler("webhook_payload").getAccountHolderNotificationRequest();

🌐 HTTP Client Configuration

• Now supports custom connectionRequestTimeout and defaultKeepAliveTimeout.
• The default timeout is configured to 60 seconds, however we recommend the application to explicitly configure it according to the requirements and expectations.

🏷️ Default Values for Attributes

Fields are initialized using a default value when the OpenAPI specs define the attribute default value. For example:

private TypeEnum type = TypeEnum.BRLOCAL;

---

💎 New Features & Enhancements

💰 BalancePlatform

• New: BalancesApi service now supports BalanceWebhookSetting for managing Balance Webhook criteria.
• Other changes:
  • New BIC enum in BankIdentification
  • New PENDING enum in CreateSweepConfigurationV2 and UpdateSweepConfigurationV2
  • New replacedById and replacementOfId attributes in PaymentInstrument and UpdatePaymentInstrument
  • New walletProviderAccountScore and walletProviderDeviceScore attributes in TransactionRuleRestrictions
  • New class USInstantPayoutAddressRequirement

🛒 Checkout

• New Donation type field supporting the following values: roundup, fixedAmounts
  (Documentation)
• Added sub-merchant info:
  • subMerchantPhoneNumber, subMerchantEmail
  • Nested: subMerchant.subSeller[n].email, subMerchant.subSeller[n].phoneNumber
• Added bonus enum to CheckoutSessionInstallmentOption

🔄 BalancePlatformTransfer API

• Added IssuingTransactionData with captureCycleId that provides the captureCycleId associated with transfer event

🔄 BalancePlatformTransfer Webhooks

• Added IssuingTransactionData with captureCycleId that provides the captureCycleId associated with transfer event

• Other changes:

  • New enum: ChargebackRemainder in PlatformPayment.platformPaymentType
  • New attribute: externalReason in TransferData
  • New pending enum in TransferData.reason

📬 New Balance Webhook

• A new Balance webhook is now available to process events related to balance changes.
• Use: BalancePlatformBalanceWebhooksHandler to consume the Webhook event balancePlatform.balanceAccount.balance.updated
  Documentation

---

🧩 Other Changes

• Enhanced Javadoc coverage across the codebase.
• Introduced a new HMAC troubleshooting utility for signature validation debugging (#1452). The tool calculates the HMAC signature given the HMAC key and the payload:

cd tools/hmac
mvn clean compile exec:java -Dexec.mainClass=CalculateHmacPayments -Dexec.args="11223344D785FBAE710E7F943F307971BB61B21281C98C9129B3D4018A57B2EB payload.json"

Check the README

---

Changes in this release:

• POS Mobile API by @gcatanese in #1463
• StoredValueAPI generation by @gcatanese in #1462
• Generate BinLookupApi service with OpenAPI Generator v7.11.0 by @gcatanese in #1465
• RecurringApi generation with OpenAPI Generator v7.11.0 by @gcatanese in #1466
• Add PaymentsAppApi, DisputesApi, DataProtectionApi by @gcatanese in #1467
• OpenAPI Generator v7.11.0: Add BalanceControl API by @gcatanese in #1468
• OpenAPI Generator v7.11.0: add Webhooks by @gcatanese in #1469
• OpenAPI Generator v7.11.0: regenerate Checkout models by @gcatanese in #1472
• Add BalancePlatform WebhookSettings by @gcatanese in #1471
• Configure HTTP Client connectionRequestTimeout by @gcatanese in #1470
• Deprecate legacy code [PosTerminalManagementApi, PaymentApi] by @gcatanese in #1474
• Rename Balance webhooks package by @gcatanese in #1476
• Release v37.0.0 by @AdyenAutomationBot in #1464

Full Changelog: v36.0.1...v37.0.0

Adyen Java API Library v36.0.1

What's Changed

Important

This patch addresses the issue introduced in Java API Library v36.0.0 that impacted the usage of the Adyen iOS SDK.

Response attributes without a value will be omitted (instead that being returned as empty lists).

The timeout settings of the underlying (Apache) HTTP client have been updated to define a default timeout of 60 seconds, developers should however always define/override those defaults accordingly.

Fixes ⛑️

• Initialise List/Set/Map as null by @gcatanese in #1461

Other Changes 🖇️

• Update example site placeholder by @ayodejidev in #1453
• HMAC Troubleshooting tool by @gcatanese in #1452
• HTTP Client timeouts by @gcatanese in #1458
• fix(deps): update dependency org.apache.httpcomponents.client5:httpclient5 to v5.4.3 [security] by @renovate in #1456
• Release v36.0.1 by @AdyenAutomationBot in #1454

Full Changelog: v36.0.0...v36.0.1

Adyen Java API Library v36.0.0

What's Changed

Warning

In this release the response attributes without a value are returned as empty lists ([]), rather than being omitted.
This might affect your integration.

Upgrade to v36.0.1: the patch has restored the initial behaviour (attributes without values are omitted from the API requests and responses).

Note for iOS SDK users: this particular version is not compatible with iOS SDK.
Root cause: response attributes without a value are now returned as empty lists, rather than being omitted.
Workaround: Upgrade to v36.0.1.

{
      "apps": [],
      "fundingSource": null,
      "group": null,
      "inputDetails": [],
      "issuers": [],
      "name": "Cards",
      "type": "scheme"
    }

Breaking Changes 🛠

• ACS webhooks
  ChallengeInfo FlowEnum values have changed:
  • Fixed correct FlowEnum-values in ChallengeInfo - "OTP_SMS" and "OOB" were not used previously and now have been updated to correct values.
  • Fix: OTP_SMS -> PWD_OTP_PHONE_FL - One-Time Password via SMS
  • Fix: OOB -> OOB_TRIGGER_FL - Out-Of-Band flow

Features 💎

• Checkout

  • add support for RakutenPay
  • add RequestedTestAcquirerResponseCode in AdditionalDataCommon

• AcsWebhooks:

  • Add Out-of-band authentication requested webhook event
  • Add new enum PWD_OTP_EMAIL_FL (One-Time Password via Email)

• Configuration webhooks

  • Add enum PENDINGin SweepConfigurationV2.

• LEM API

  • Add attribute allowDebugUi in OnboardingLinkSettingsto debug user interface (UI) when applicable.

• Transactions webhooks

  • Add enum DCCPLATFORMCOMMISSION in PlatformPayment

• Transfers API

  • Add enum DCCPLATFORMCOMMISSION in PlatformPayment
  • Add enum PENDINGin TransferData
  • Add attribute externalReason in TransferData
  • Add scaOnApproval attribute in TransferReview

Other Changes 🖇️

Note: enums instantiation has changed, this shouldn't impact the usage of the enums
Example, from PERMATA_LITE_ATM("doku_permata_lite_atm") to DOKU_PERMATA_LITE_ATM(String.valueOf("doku_permata_lite_atm"))

• Improve Github workflows by @ayodejidev in #1440
• Add close-issue-label flag to correctly label closed issues by @DjoykeAbyah in #1442
• iDEAL2 unit test update by @gcatanese in #1443
• Ovverride default ApiError message with the error message from the API response by @gcatanese in #1447
• Add OpenAPI Generator v7 mustache templates by @gcatanese in #1444
• ACS webhooks update: RelayedAuthenticationRequest event code by @gcatanese in #1449
• Checkout API code generation: RakutenPay by @gcatanese in #1450
• Release v36.0.0 by @AdyenAutomationBot in #1441

Full Changelog: v35.0.0...v36.0.0

Adyen Java API Library v35.0.0

What's Changed

Breaking Changes 🛠

• Management API:
  • In AndroidApp the field status has changed from String to StatusEnum (ARCHIVED, ERROR, INVALID, PROCESSING, READY)
• Management webhooks:
  • In PaymentMethodRequestRemovedNotificationRequest the event type has been renamed to paymentMethodRequest.removed
  • In PaymentMethodScheduledForRemovalNotificationRequest the event type has been renamed to paymentMethodRequest.scheduledForRemoval

New Features 💎

Add support for Session Authentication API to create the sessions required for integrating Adyen Platform components (#1435)

• Checkout:
  • New payment methods PixDetails and PixRecurring
  • In PaymentRefundResponse add attribute capturePspReference (only available for PayPal refunds)
  • In ResponseAdditionalDataCommon:
    • ⚠️ the recurringRecurringDetailReference and recurringShopperReference are deprecated, use instead the new attribute tokenizationShopperReference
    • add tokenizationStoreOperationType and tokenizationStoredPaymentMethodId attributes, add TokenizationStoreOperationTypeEnum enum
• Management API:
  • Support AffirmInfo and PayToInfo payment methods
  • in Surcharge class add attribuge excludeGratuityFromSurcharge
• Payout:
  • In ResponseAdditionalDataCommon:
    • ⚠️ the recurringRecurringDetailReference and recurringShopperReference are deprecated, use instead the new attribute tokenizationShopperReference
    • add tokenizationStoreOperationType and tokenizationStoredPaymentMethodId attributes, add TokenizationStoreOperationTypeEnum enum
• Classic Payments:
  • In ResponseAdditionalDataCommon:
    • ⚠️ the recurringRecurringDetailReference and recurringShopperReference are deprecated, use instead the new attribute tokenizationShopperReference
    • add tokenizationStoreOperationType and tokenizationStoredPaymentMethodId attributes, add TokenizationStoreOperationTypeEnum enum
• Terminal API:
  • Add SaleReferenceID field in CustomerOrder class (#1436)

Important

The Recurring API is deprecated. Use the Checkout API recurring endpoints instead.

Other Changes 🖇️

• feat(tls): allow disabling protocol upgrade by @sp00m in #1425
• Improve issue template by @ayodejidev in #1434
• chore(deps): update dependency org.apache.maven.plugins:maven-checkstyle-plugin to v3.6.0 by @renovate in #1381
• fix(exception): better handle non-JSON response bodies by @sp00m in #1404
• Code generation: update services and models by @AdyenAutomationBot #1433
• Release v35.0.0 by @AdyenAutomationBot in #1437
• Session Authentication API #1435 by @gcatanese

Full Changelog: v34.0.0...v35.0.0

Adyen Java API Library v34.0.0

What's Changed

Breaking Changes 🛠

• BalancePlatform:
  • Removed PriorityRestriction class.
  • In TransactionRuleRestriction removed priority.
• BinLookup:
  • In CostEstimateResponse removed surchargeType.
• Transfers:
  • In TransferReview removed numberOfApprovalsCompleted and scaOnApproval.
• TransferWebhook:
  • In TransferReview removed numberOfApprovalsCompleted and scaOnApproval.

Features 💎

• AcsWebhooks:

  • In ChallengeInfo broadening the range of ChallengeCancelEnum.

• BalancePlatform:

  • Added AssociationDelegatedAuthenticationData, AssociationFinaliseRequest, AssociationFinaliseResponse, AssociationInitiateRequest, AssociationInitiateResponse and TokenRequestorsRestriction class.
  • In TransactionRuleRestriction added tokenRequestors.

• Checkout:

  • In CardDetails, CardDonations and CheckoutPaymentMethod added fastlaneData.
  • Added FastlaneDetails class.

• LegalEntityManagement:

  • Added FinancialReport class.
  • In LegalEntityAssociation added nominee.
  • In Organization and SoleProprietorship added financialReports.

• Service:

  • BalancePlatform:
    • Deprecated GrantAccountsApi and GrantOffersApi.
    • In ManageSCADevicesApi added completeAssociationBetweenScaDeviceAndResource and initiateAssociationBetweenScaDeviceAndResource.
  • Transfers:
    • Deprecated CapitalApi.

• Code generation: update services and models by @AdyenAutomationBot in #1426

Other Changes 🖇️

• chore(deps): update dependency org.mockito:mockito-core to v5.15.2 by @renovate in #1348
• Fix failing failing step for external forks by @ayodejidev in #1429
• Update Java version in POM file by @gcatanese in #1432
• Release v34.0.0 by @AdyenAutomationBot in #1427

Full Changelog: v33.1.0...v34.0.0

Adyen Java API Library v33.1.0

What's Changed

New Features 💎

Add Negative Balance Warning

• Webhooks:
  • Classic Payments
  • Add TopUp enum in Split class

Other Changes 🖇️

• Improve exception logging in BankingWebhookHandler
• OpenAPI spec files or templates have been modified on 29-01-2025 by commit. Download OpenAPI diffs to view the changes.
• Code generation: update services and models by @AdyenAutomationBot in #1423
• Add deprecation of POS Terminal Management API by @gcatanese in #1420
• Improve deserialization unit testing by @gcatanese in #1421
• Code generation: update services and models by @AdyenAutomationBot in #1424
• Release v33.1.0 by @AdyenAutomationBot in #1422

Full Changelog: v33.0.0...v33.1.0

Adyen Java API Library v33.0.0

What's Changed

Breaking Changes 🛠

• Checkout API:
  *airlinePassengerTelephoneNumber attribute renamed to airlinePassengerPhoneNumber in AdditionalDataAirline

New Features 💎

• Checkout API:
  • Add AffirmDetails payment method
  • Add PayPayDetails payment method
  • Add TopUp enum in Split class
  • Add autoRescue attribute in AdditionalDataCommon - Set to true to enable Auto Rescue
  • Add maxDaysToRescue in AdditionalDataCommon - Specify the rescue window for a transaction, in days, when autoRescue is set to true. You can specify a value between 1 and 48.
• Report webhooks:
  • Add id attribute in ReportNotificationData class

Other changes 🖇️

Important

From January 1, 2025 POS Terminal Management API is deprecated and support stops on April 1, 2025. To automate the management of your terminal fleet, use our Management API.

Before: (deprecated) https://postfmapi-test.adyen.com/postfmapi/terminal/v1/getTerminalDetails We've moved the fields TerminalStatus to lastActivityAt and data.AssignmentStatus.
Note that your API-credentials requires the following permission: Management API — Terminal actions read.

// TerminalStatus:

ONLINELAST1DAY ("OnlineLast1Day")
ONLINELAST2DAYS ("OnlineLast2Days")
ONLINELAST3DAYS ("OnlineLast3Days")
ONLINELAST4DAYS ("OnlineLast4Days")
ONLINELAST5DAYS ("OnlineLast5Days")
ONLINELAST6DAYS ("OnlineLast6Days")
ONLINELAST7DAYS ("OnlineLast7Days")
ONLINETODAY ("OnlineToday")
REASSIGNTOINVENTORYPENDING ("ReAssignToInventoryPending")
REASSIGNTOMERCHANTINVENTORYPENDING ("ReAssignToMerchantInventoryPending")
REASSIGNTOSTOREPENDING ("ReAssignToStorePending")
SWITCHEDOFF ("SwitchedOff")

• Code generation: update services and models by @AdyenAutomationBot in #1417
• Release v33.0.0 by @AdyenAutomationBot in #1419

Full Changelog: v32.2.0...v33.0.0

Adyen Java API Library v32.2.0

What's Changed

New Features 💎

Adjusted Region class to define region constants and their associated Terminal API endpoint mappings.

• Terminal API:

  • Add Regions support for live transactions: use an endpoint that is geographically closest to the location of your store

• BalancePlatform:

  • Added PriorityRestriction class.
  • In TransactionRuleRestrictions added priority.
  • In VerificationDeadline, VerificationError and VerificationErrorRecursive added issueChargeCard, issueChargeCardCommercial , useChargeCard and useChargeCardCommercial enum.

• ConfigurationWebhooks:

  • In VerificationDeadline, VerificationError and VerificationErrorRecursive added issueChargeCard, issueChargeCardCommercial , useChargeCard and useChargeCardCommercial enum.

• LegalEntityManagement:

  • In VerificationDeadline, VerificationError and VerificationErrorRecursive added issueChargeCard, issueChargeCardCommercial , useChargeCard and useChargeCardCommercial enum.

• Update all services by @AdyenAutomationBot in #1416

Other Changes 🖇️

• feat(tls): allow disabling protocol upgrade by @sp00m in #1409
• Revert "feat(tls): allow disabling protocol upgrade" by @DjoykeAbyah in #1414
• Adjust Region class with valid regions plus endpoint mappings for terminal api live by @DjoykeAbyah in #1407
• Release v32.2.0 by @AdyenAutomationBot in #1415

Full Changelog: v32.1.0...v32.2.0

Adyen Java API Library v32.1.0

What's Changed

New Features 💎

• BalancePlatform:
  • Added CounterpartyTypesRestriction and SourceAccountTypesRestriction class
  • In TransactionRuleRestrictions added counterpartyTypes and sourceAccountTypes
• ConfigurationWebhooks:
  • In AccountHolderNotificationRequest, BalanceAccountNotificationRequest, CardOrderNotificationRequest, PaymentNotificationRequest and SweepConfigurationNotificationRequest added timestamp
• Management:
  • In TerminalConnectivityCellular added iccid2
  • In UpdatePaymentMethodInfo added storeId
• ManagementWebhooks:
  • Added TerminalAssignmentNotificationRequest and TerminalAssignmentNotificationResponse class
• ReportWebhooks:
  • In ReportNotificationRequest added timestamp

• Update all services by @AdyenAutomationBot in #1405

Other Changes 🖇️

• Use a dynamically-generated, random IV by @ayodejidev in #1410
• Deprecate TerminalLocalAPIUnencrypted.java by @ayodejidev in #1412
• Release v32.1.0 by @AdyenAutomationBot in #1411

Full Changelog: v32.0.0...v32.1.0