Provide guidance on upgrading from adyen-java-api-library v4.1.0 to v40.0.0 for Checkout API v71

[usmanarogundade]

Feature summary

This issue requests official upgrade guidance and documentation for migrating from adyen-java-api-library v4.1.0 to v40.0.0 to support Checkout API v71.

Problem statement

Hi team,

We’re working with a merchant who is currently using adyen-java-api-library v4.1.0 with Checkout API v69 and is looking to upgrade to Checkout API v71.

They’re evaluating the latest library version v40.0.0, but given the large version gap, they would like some guidance on:

Key breaking or structural changes between v4.1.0 and v40.0.0

Any recommended migration path or tools to identify differences (e.g., generated models, renamed classes, removed endpoints)

Known backward-incompatibility considerations or best practices when upgrading to v40.0.0 in order to support Checkout API v71

From the Checkout perspective, we plan to reference the API Diff Tool for v69 → v71, but additional insights or documentation on the Java library side would be very helpful.

Thanks in advance for any resources, notes, or upgrade guidelines you can share!

Proposed solution

Context:

Current library: v4.1.0

Target library: v40.0.0

Current Checkout API: v69

Target Checkout API: v71

Alternatives considered

No response

Additional context

No response

[gcatanese]

The upgrade from v4.1.0 to v40.0.0 is indeed a major migration, considering the number of new products, features and changes introduced over the years.

Checkout v69 vs v71

First of all, the migration requires upgrading from Checkout v69 to the current version v71. A good start pointing is to inspect the changes in our API Diff Tool.

Java Sample App

Another valuable resource is the Adyen Java sample application that shows how the Adyen Java API (together with the Web Drop-in) can be used to implement various use cases, like Session or Advanced flow, Authorization Adjustment, Subscriptions, Gift cards, etc...

The sample app is still using Adyen Java v29 (our team will be upgrading the app), however v29 is similar to the latest version v40.

Code snippets

Code snippets (in different languages) are available on the API Explorer.

We also recommend to check the unit tests that also show how the different features can be implemented.

Use cases

Since there is no a linear upgrade path, we suggest to 1) identify the relevant use cases and 2) look at the existing resources (Adyen Docs, sample applications on GitHub, code snippets on the API Explorer, source code of the library) to understand what needs to be done.

Make an API call

When you make a payment, or use any other feature, the workflow is similar:

• setup the client
• initialize the corresponding API handler (i.e. PaymentsApi to invoke Checkout Payments endpoints)
• perform the request

// setup the client
Config config = new Config()
    .environment(Environment.LIVE)
    .liveEndpointUrlPrefix("myCompany")
    .apiKey("myApiKey");
Client client = new Client(config);

// initialise API handler
PaymentsApi checkout = new PaymentsApi(client);

The next step is to define parameters and/or request object, then invoke the corresponding method.

Get payment methods

In the Advanced Flow, when you need to retrieve the list of available payment methods:

PaymentMethodsRequest paymentMethodsRequest =
    new PaymentMethodsRequest().merchantAccount("myMerchantAccount");

PaymentMethodsResponse paymentMethodsResponse = checkout.paymentMethods(paymentMethodsRequest);

Make a card payment

    CardDetails cardDetails =
        new CardDetails()
            .type(CardDetails.TypeEnum.SCHEME)
            .encryptedCardNumber("5136333333333335")
            .holderName("John Doe")
            .cvc("737")
            .encryptedExpiryMonth("08")
            .encryptedExpiryYear("2018");
    PaymentRequest paymentRequest =
        new PaymentRequest()
            .merchantAccount("YOUR_MERCHANT_ACCOUNT")
            .reference("YOUR_REFERENCE")
            .amount(new Amount().currency("EUR").value(1000L))
            .returnUrl("https://your-company.example.org/checkout?shopperOrder=12xy..")
            .paymentMethod(new CheckoutPaymentMethod(cardDetails));

    PaymentResponse paymentResponse = checkout.payments(paymentRequest);

Process incoming webhooks

The Java library supports the handling of webhooks delivered by Adyen as well as the validation of the HMAC signature.

Payment webhooks

In case of payment webhooks, parse the webhook payload and verify the HMAC signature

NotificationRequest notificationRequest = NotificationRequest.fromJson("webhook json payload");
// Fetch first (and only) NotificationRequestItem
Optional<NotificationRequestItem> notificationRequestItem = notificationRequest.getNotificationItems().stream().findFirst();

// validate hmac signature and process
NotificationRequestItem item = notificationRequestItem.get();
if (hmacValidator.validateHMAC(item, this.applicationProperty.getHmacKey())) {
   // Consume event asynchronously
} else {
  throw new RuntimeException("HMAC signature did not match");
}

Other webhooks

In case of AfP or Management webhooks, you can use the built-in webhook handlers.

    String json = "webhook json payload"; // a valid JSON document

    // find and validate HMAC signature
    String hmacsignature = headers.get("hmacsignature");

    if (!hmacValidator.validateHMAC(json, hmacsignature, "MY_HMAC_KEY")) {
            log.error("Invalid HMAC signature");
            throw new RuntimeException("Invalid HMAC signature");
    }

    Optional<AccountHolderNotificationRequest> notificationRequest =
        new ConfigurationWebhooksHandler(json).getAccountHolderNotificationRequest();
    AccountHolderNotificationRequest accountHolderNotificationRequest = notificationRequest.get();

Use an idempotency key

To submit a request for idempotent processing, send a request with the idempotency-key in the HTTP headers.

// set Idempotency Key
String idempotencyKey = "......" // unique identifier for the message with a maximum of 64 characters: use UUID
RequestOptions requestOptions =
    new RequestOptions().idempotencyKey(idempotencyKey);
PaymentResponse paymentResponse = checkout.payments(paymentRequest, requestOptions);

Error handling

Catch the ApiException to inspect the response and handle specific cases:

try {
    PaymentLinksApi paymentLinksApi = new PaymentLinksApi(client);
    PaymentLinkResponse paymentLinkResponse = paymentLinksApi.getPaymentLink("1234");
} catch (ApiException e) {
    // Obtain response 
    int statusCode = e.getStatusCode();
    String responseBody = e.getResponseBody();
    // Check ApiError object
    ApiError apiError = e.getError();
    String errorCode = apiError.getErrorCode();
    List<String> invalidFields = apiError.getInvalidFields();
    ....
}