--- title: "Upgrade your Java API library" description: "Upgrade your Java API library to support Checkout API v72." url: "https://docs.adyen.com/online-payments/upgrade-your-integration/migrate-to-checkout-api/upgrade-api-library" source_url: "https://docs.adyen.com/online-payments/upgrade-your-integration/migrate-to-checkout-api/upgrade-api-library.md" canonical: "https://docs.adyen.com/online-payments/upgrade-your-integration/migrate-to-checkout-api/upgrade-api-library" last_modified: "2026-07-03T16:21:07+02:00" language: "en" --- # Upgrade your Java API library Upgrade your Java API library to support Checkout API v72. [View source](/online-payments/upgrade-your-integration/migrate-to-checkout-api/upgrade-api-library.md) Upgrade your `adyen-java-api-library` from an earlier version (such as v4.1.0) to the latest version (v40.0.0 or later) to support Checkout API v72. This is a major upgrade because of significant changes to products, features, and architecture. ## Requirements | | | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | Online payments integration with a payments server using the [Adyen Java API library](https://github.com/Adyen/adyen-java-api-library). | ## Review API changes Use the [API Diff Tool](https://docs.adyen.com/api-explorer/api-diff-tool?api=Checkout\&from=71\&to=72%3Fclasses%3DcodeLabel) to understand the changes between your current Checkout API version and v72. This tool shows: * New parameters and endpoints * Deprecated or removed fields * Changes to existing functionality ## Identify your use cases There is no linear upgrade path. Identify the specific use cases in your integration. Common use cases include: * Make payments ([Sessions flow or Advanced flow](/online-payments/build-your-integration#choose-your-server-side-implementation)) * Process [webhooks](/development-resources/webhooks) * Handle [authorization adjustments](/online-payments/adjust-authorisation) * Manage [subscriptions and subscription payments](/online-payments/tokenization/make-token-payments#make-a-subscription-or-unscheduled-card-on-file-payment) * Accept [gift card payments](/payment-methods/gift-cards) For each use case, make sure that you understand the models the latest library version that supports it. ## Update your integration Update your server-side code to use the latest version of the Java API library. ### Set up the client The workflow for API requests follows this pattern: 1. Set up the client. 2. Initialize the corresponding API handler. 3. Send the request. **Set up the client** ```java // Set up the client Config config = new Config() .environment(Environment.LIVE) .liveEndpointUrlPrefix("YOUR_LIVE_URL_PREFIX") .apiKey("YOUR_API_KEY"); Client client = new Client(config); // Initialize API handler PaymentsApi checkout = new PaymentsApi(client); ``` ### Get payment methods For the Advanced flow, to get the list of available payment methods: **Get payment methods** ```java PaymentMethodsRequest paymentMethodsRequest = new PaymentMethodsRequest().merchantAccount("YOUR_MERCHANT_ACCOUNT"); PaymentMethodsResponse paymentMethodsResponse = checkout.paymentMethods(paymentMethodsRequest); ``` ### Make a card payment For the Advanced flow, to make a card payment: **Make a card payment** ```java CardDetails cardDetails = new CardDetails() .type(CardDetails.TypeEnum.SCHEME) .encryptedCardNumber("test_5136333333333335") .holderName("S. Hopper") .encryptedSecurityCode("test_737") .encryptedExpiryMonth("test_08") .encryptedExpiryYear("test_2030"); PaymentRequest paymentRequest = new PaymentRequest() .merchantAccount("YOUR_MERCHANT_ACCOUNT") .reference("YOUR_REFERENCE") .amount(new Amount().currency("EUR").value(1000L)) .returnUrl("https://your-company.example.com/checkout?shopperOrder=12xy..") .paymentMethod(new CheckoutPaymentMethod(cardDetails)); PaymentResponse paymentResponse = checkout.payments(paymentRequest); ``` ### Process payment webhooks To process payment webhooks and verify the HMAC signature: **Process payment webhooks** ```java NotificationRequest notificationRequest = NotificationRequest.fromJson("webhook json payload"); // Fetch first (and only) NotificationRequestItem Optional notificationRequestItem = notificationRequest.getNotificationItems().stream().findFirst(); // Validate HMAC signature and process NotificationRequestItem item = notificationRequestItem.get(); if (hmacValidator.validateHMAC(item, hmacKey)) { // Consume event asynchronously } else { throw new RuntimeException("HMAC signature did not match"); } ``` ### Process other webhooks For Balance Platform or Management webhooks, use the built-in webhook handlers: **Process Balance Platform webhooks** ```java String json = "webhook json payload"; // a valid JSON document // Find and validate HMAC signature String hmacSignature = headers.get("hmacsignature"); if (!hmacValidator.validateHMAC(json, hmacSignature, "YOUR_HMAC_KEY")) { log.error("Invalid HMAC signature"); throw new RuntimeException("Invalid HMAC signature"); } Optional notificationRequest = new ConfigurationWebhooksHandler(json).getAccountHolderNotificationRequest(); AccountHolderNotificationRequest accountHolderNotificationRequest = notificationRequest.get(); ``` ### Use idempotency keys To send a request that uses [API idempotency](/development-resources/api-idempotency), include the `idempotency-key` in the HTTP header for each request: **Use idempotency keys** ```java // Set idempotency key String idempotencyKey = UUID.randomUUID().toString(); // unique identifier with max 64 characters RequestOptions requestOptions = new RequestOptions().idempotencyKey(idempotencyKey); PaymentResponse paymentResponse = checkout.payments(paymentRequest, requestOptions); ``` ### Handle errors Catch the `ApiException` to inspect the response and handle specific errors: **Handle errors** ```java try { PaymentLinksApi paymentLinksApi = new PaymentLinksApi(client); PaymentLinkResponse paymentLinkResponse = paymentLinksApi.getPaymentLink("QFQTPCQ8HXSKGK82"); } catch (ApiException e) { // Obtain response details int statusCode = e.getStatusCode(); String responseBody = e.getResponseBody(); // Check ApiError object ApiError apiError = e.getError(); String errorCode = apiError.getErrorCode(); List invalidFields = apiError.getInvalidFields(); } ``` ## Test your integration After you upgrade your library: 1. Test all your use cases in your test environment. 2. Verify that webhook processing works correctly. 3. Check that your integration can handle errors for all possible scenarios. 4. Validate that your integration can handle all the payment flows that you support. If you have questions or need help with your upgrade, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). * [Adyen Java sample application](https://github.com/adyen-examples/adyen-java-spring-online-payments) * [API Explorer](https://docs.adyen.com/api-explorer/) * [Library unit tests](https://github.com/Adyen/adyen-java-api-library/blob/main/src/test/java/com/adyen/CheckoutTest.java) * [Checkout API v72 reference](https://docs.adyen.com/api-explorer/Checkout/72/overview) * [adyen-java-api-library GitHub repository](https://github.com/Adyen/adyen-java-api-library)