{"title":"Upgrade your Java API library","category":"default","creationDate":1783088467,"content":"<p>Upgrade your <code>adyen-java-api-library<\/code> from an earlier version (such as v4.1.0) to the latest version (v40.0.0 or later) to support Checkout API v72.<\/p>\n<p>This is a major upgrade because of significant changes to products, features, and architecture.<\/p>\n<h2>Requirements<\/h2>\n<table>\n<thead>\n<tr>\n<th><\/th>\n<th><\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td><strong>Integration type<\/strong><\/td>\n<td>Online payments integration with a payments server using the <a href=\"https:\/\/github.com\/Adyen\/adyen-java-api-library\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Adyen Java API library<\/a>.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h2>Review API changes<\/h2>\n<p>Use the <a href=\"https:\/\/docs.adyen.com\/api-explorer\/api-diff-tool?api=Checkout&amp;from=71&amp;to=72%3Fclasses%3DcodeLabel\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">API Diff Tool<\/a> to understand the changes between your current Checkout API version and v72. This tool shows:<\/p>\n<ul>\n<li>New parameters and endpoints<\/li>\n<li>Deprecated or removed fields<\/li>\n<li>Changes to existing functionality<\/li>\n<\/ul>\n<h2>Identify your use cases<\/h2>\n<p>There is no linear upgrade path. Identify the specific use cases in your integration. Common use cases include:<\/p>\n<ul>\n<li>Make payments (<a href=\"\/online-payments\/build-your-integration#choose-your-server-side-implementation\">Sessions flow or Advanced flow<\/a>)<\/li>\n<li>Process <a href=\"\/development-resources\/webhooks\">webhooks<\/a><\/li>\n<li>Handle <a href=\"\/online-payments\/adjust-authorisation\">authorization adjustments<\/a><\/li>\n<li>Manage <a href=\"\/online-payments\/tokenization\/make-token-payments#make-a-subscription-or-unscheduled-card-on-file-payment\">subscriptions and subscription payments<\/a><\/li>\n<li>Accept <a href=\"\/payment-methods\/gift-cards\">gift card payments<\/a><\/li>\n<\/ul>\n<p>For each use case, make sure that you understand the models the latest library version that supports it.<\/p>\n<h2>Update your integration<\/h2>\n<p>Update your server-side code to use the latest version of the Java API library.<\/p>\n<h3>Set up the client<\/h3>\n<p>The workflow for API requests follows this pattern:<\/p>\n<ol>\n<li>Set up the client.<\/li>\n<li>Initialize the corresponding API handler.<\/li>\n<li>Send the request.<\/li>\n<\/ol>\n<div data-component-wrapper=\"code-sample\">\n    <code-sample :title=\"'Set up the client'\" :id=\"''\" :code-data='[{\"language\":\"java\",\"tabTitle\":\"\",\"content\":\"\\\/\\\/ Set up the client\\nConfig config = new Config()\\n    .environment(Environment.LIVE)\\n    .liveEndpointUrlPrefix(\\\"YOUR_LIVE_URL_PREFIX\\\")\\n    .apiKey(\\\"YOUR_API_KEY\\\");\\nClient client = new Client(config);\\n\\n\\\/\\\/ Initialize API handler\\nPaymentsApi checkout = new PaymentsApi(client);\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<h3>Get payment methods<\/h3>\n<p>For the Advanced flow, to get the list of available payment methods:<\/p>\n<div data-component-wrapper=\"code-sample\">\n    <code-sample :title=\"'Get payment methods'\" :id=\"''\" :code-data='[{\"language\":\"java\",\"tabTitle\":\"\",\"content\":\"PaymentMethodsRequest paymentMethodsRequest =\\n    new PaymentMethodsRequest().merchantAccount(\\\"YOUR_MERCHANT_ACCOUNT\\\");\\n\\nPaymentMethodsResponse paymentMethodsResponse = checkout.paymentMethods(paymentMethodsRequest);\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<h3>Make a card payment<\/h3>\n<p>For the Advanced flow, to make a card payment:<\/p>\n<div data-component-wrapper=\"code-sample\">\n    <code-sample :title=\"'Make a card payment'\" :id=\"''\" :code-data='[{\"language\":\"java\",\"tabTitle\":\"\",\"content\":\"CardDetails cardDetails =\\n    new CardDetails()\\n        .type(CardDetails.TypeEnum.SCHEME)\\n        .encryptedCardNumber(\\\"test_5136333333333335\\\")\\n        .holderName(\\\"S. Hopper\\\")\\n        .encryptedSecurityCode(\\\"test_737\\\")\\n        .encryptedExpiryMonth(\\\"test_08\\\")\\n        .encryptedExpiryYear(\\\"test_2030\\\");\\n\\nPaymentRequest paymentRequest =\\n    new PaymentRequest()\\n        .merchantAccount(\\\"YOUR_MERCHANT_ACCOUNT\\\")\\n        .reference(\\\"YOUR_REFERENCE\\\")\\n        .amount(new Amount().currency(\\\"EUR\\\").value(1000L))\\n        .returnUrl(\\\"https:\\\/\\\/your-company.example.com\\\/checkout?shopperOrder=12xy..\\\")\\n        .paymentMethod(new CheckoutPaymentMethod(cardDetails));\\n\\nPaymentResponse paymentResponse = checkout.payments(paymentRequest);\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<h3>Process payment webhooks<\/h3>\n<p>To process payment webhooks and verify the HMAC signature:<\/p>\n<div data-component-wrapper=\"code-sample\">\n    <code-sample :title=\"'Process payment webhooks'\" :id=\"''\" :code-data='[{\"language\":\"java\",\"tabTitle\":\"\",\"content\":\"NotificationRequest notificationRequest = NotificationRequest.fromJson(\\\"webhook json payload\\\");\\n\\n\\\/\\\/ Fetch first (and only) NotificationRequestItem\\nOptional&lt;NotificationRequestItem&gt; notificationRequestItem = \\n    notificationRequest.getNotificationItems().stream().findFirst();\\n\\n\\\/\\\/ Validate HMAC signature and process\\nNotificationRequestItem item = notificationRequestItem.get();\\nif (hmacValidator.validateHMAC(item, hmacKey)) {\\n    \\\/\\\/ Consume event asynchronously\\n} else {\\n    throw new RuntimeException(\\\"HMAC signature did not match\\\");\\n}\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<h3>Process other webhooks<\/h3>\n<p>For Balance Platform or Management webhooks, use the built-in webhook handlers:<\/p>\n<div data-component-wrapper=\"code-sample\">\n    <code-sample :title=\"'Process Balance Platform webhooks'\" :id=\"''\" :code-data='[{\"language\":\"java\",\"tabTitle\":\"\",\"content\":\"String json = \\\"webhook json payload\\\"; \\\/\\\/ a valid JSON document\\n\\n\\\/\\\/ Find and validate HMAC signature\\nString hmacSignature = headers.get(\\\"hmacsignature\\\");\\n\\nif (!hmacValidator.validateHMAC(json, hmacSignature, \\\"YOUR_HMAC_KEY\\\")) {\\n    log.error(\\\"Invalid HMAC signature\\\");\\n    throw new RuntimeException(\\\"Invalid HMAC signature\\\");\\n}\\n\\nOptional&lt;AccountHolderNotificationRequest&gt; notificationRequest =\\n    new ConfigurationWebhooksHandler(json).getAccountHolderNotificationRequest();\\nAccountHolderNotificationRequest accountHolderNotificationRequest = notificationRequest.get();\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<h3>Use idempotency keys<\/h3>\n<p>To send a request that uses <a href=\"\/development-resources\/api-idempotency\">API idempotency<\/a>, include the <code>idempotency-key<\/code> in the HTTP header for each request:<\/p>\n<div data-component-wrapper=\"code-sample\">\n    <code-sample :title=\"'Use idempotency keys'\" :id=\"''\" :code-data='[{\"language\":\"java\",\"tabTitle\":\"\",\"content\":\"\\\/\\\/ Set idempotency key\\nString idempotencyKey = UUID.randomUUID().toString(); \\\/\\\/ unique identifier with max 64 characters\\nRequestOptions requestOptions = new RequestOptions().idempotencyKey(idempotencyKey);\\n\\nPaymentResponse paymentResponse = checkout.payments(paymentRequest, requestOptions);\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<h3>Handle errors<\/h3>\n<p>Catch the <code>ApiException<\/code> to inspect the response and handle specific errors:<\/p>\n<div data-component-wrapper=\"code-sample\">\n    <code-sample :title=\"'Handle errors'\" :id=\"''\" :code-data='[{\"language\":\"java\",\"tabTitle\":\"\",\"content\":\"try {\\n    PaymentLinksApi paymentLinksApi = new PaymentLinksApi(client);\\n    PaymentLinkResponse paymentLinkResponse = paymentLinksApi.getPaymentLink(\\\"QFQTPCQ8HXSKGK82\\\");\\n} catch (ApiException e) {\\n    \\\/\\\/ Obtain response details\\n    int statusCode = e.getStatusCode();\\n    String responseBody = e.getResponseBody();\\n    \\n    \\\/\\\/ Check ApiError object\\n    ApiError apiError = e.getError();\\n    String errorCode = apiError.getErrorCode();\\n    List&lt;String&gt; invalidFields = apiError.getInvalidFields();\\n}\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<h2>Test your integration<\/h2>\n<p>After you upgrade your library:<\/p>\n<ol>\n<li>Test all your use cases in your test environment.<\/li>\n<li>Verify that webhook processing works correctly.<\/li>\n<li>Check that your integration can handle errors for all possible scenarios.<\/li>\n<li>Validate that your integration can handle all the payment flows that you support.<\/li>\n<\/ol>\n<p>If you have questions or need help with your upgrade, contact our <a href=\"https:\/\/ca-test.adyen.com\/ca\/ca\/contactUs\/support.shtml?form=other\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Support Team<\/a>.<\/p>\n<div class=\"see-also-links output-inline\" id=\"see-also\">\n<ul><li><a href=\"https:\/\/github.com\/adyen-examples\/adyen-java-spring-online-payments\"\n                        target=\"_blank\"\n                         class=\"external\">\n                    Adyen Java sample application\n                <\/a><\/li><li><a href=\"https:\/\/docs.adyen.com\/api-explorer\/\"\n                        target=\"_blank\"\n                         class=\"external\">\n                    API Explorer\n                <\/a><\/li><li><a href=\"https:\/\/github.com\/Adyen\/adyen-java-api-library\/blob\/main\/src\/test\/java\/com\/adyen\/CheckoutTest.java\"\n                        target=\"_blank\"\n                         class=\"external\">\n                    Library unit tests\n                <\/a><\/li><li><a href=\"https:\/\/docs.adyen.com\/api-explorer\/Checkout\/72\/overview\"\n                        target=\"_blank\"\n                         class=\"external\">\n                    Checkout API v72 reference\n                <\/a><\/li><li><a href=\"https:\/\/github.com\/Adyen\/adyen-java-api-library\"\n                        target=\"_blank\"\n                         class=\"external\">\n                    adyen-java-api-library GitHub repository\n                <\/a><\/li><\/ul><\/div>\n","url":"https:\/\/docs.adyen.com\/online-payments\/upgrade-your-integration\/migrate-to-checkout-api\/upgrade-api-library","articleFields":{"description":"Upgrade your Java API library to support Checkout API v72.","feedback_component":true},"algolia":{"url":"https:\/\/docs.adyen.com\/online-payments\/upgrade-your-integration\/migrate-to-checkout-api\/upgrade-api-library","title":"Upgrade your Java API library","content":"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.\nThis is a major upgrade because of significant changes to products, features, and architecture.\nRequirements\n\n\n\n\n\n\n\n\n\nIntegration type\nOnline payments integration with a payments server using the Adyen Java API library.\n\n\n\nReview API changes\nUse the API Diff Tool to understand the changes between your current Checkout API version and v72. This tool shows:\n\nNew parameters and endpoints\nDeprecated or removed fields\nChanges to existing functionality\n\nIdentify your use cases\nThere is no linear upgrade path. Identify the specific use cases in your integration. Common use cases include:\n\nMake payments (Sessions flow or Advanced flow)\nProcess webhooks\nHandle authorization adjustments\nManage subscriptions and subscription payments\nAccept gift card payments\n\nFor each use case, make sure that you understand the models the latest library version that supports it.\nUpdate your integration\nUpdate your server-side code to use the latest version of the Java API library.\nSet up the client\nThe workflow for API requests follows this pattern:\n\nSet up the client.\nInitialize the corresponding API handler.\nSend the request.\n\n\n    \n\nGet payment methods\nFor the Advanced flow, to get the list of available payment methods:\n\n    \n\nMake a card payment\nFor the Advanced flow, to make a card payment:\n\n    \n\nProcess payment webhooks\nTo process payment webhooks and verify the HMAC signature:\n\n    \n\nProcess other webhooks\nFor Balance Platform or Management webhooks, use the built-in webhook handlers:\n\n    \n\nUse idempotency keys\nTo send a request that uses API idempotency, include the idempotency-key in the HTTP header for each request:\n\n    \n\nHandle errors\nCatch the ApiException to inspect the response and handle specific errors:\n\n    \n\nTest your integration\nAfter you upgrade your library:\n\nTest all your use cases in your test environment.\nVerify that webhook processing works correctly.\nCheck that your integration can handle errors for all possible scenarios.\nValidate that your integration can handle all the payment flows that you support.\n\nIf you have questions or need help with your upgrade, contact our Support Team.\n\n\n                    Adyen Java sample application\n                \n                    API Explorer\n                \n                    Library unit tests\n                \n                    Checkout API v72 reference\n                \n                    adyen-java-api-library GitHub repository\n                \n","type":"page","locale":"en","boost":16,"hierarchy":{"lvl0":"Home","lvl1":"Online payments","lvl2":"Upgrade your integration","lvl3":"Migrate to Checkout API","lvl4":"Upgrade your Java API library"},"hierarchy_url":{"lvl0":"https:\/\/docs.adyen.com\/","lvl1":"https:\/\/docs.adyen.com\/online-payments","lvl2":"https:\/\/docs.adyen.com\/online-payments\/upgrade-your-integration","lvl3":"https:\/\/docs.adyen.com\/online-payments\/upgrade-your-integration\/migrate-to-checkout-api","lvl4":"\/online-payments\/upgrade-your-integration\/migrate-to-checkout-api\/upgrade-api-library"},"levels":5,"category":"Online Payments","category_color":"green","tags":["Upgrade","library"]}}