Adyen Java API Library

Supported API versions

Supported Webhook versions

Prerequisites

Installation

<dependency>  <groupId>com.adyen</groupId>  <artifactId>adyen-java-api-library</artifactId>  <version>40.1.0</version></dependency>

Using the library

General use with API key

// Import the required classesimportcom.adyen.Client;importcom.adyen.enums.Environment;importcom.adyen.service.checkout.PaymentsApi;importcom.adyen.model.checkout.*;// Setup Client using Config objectConfigconfig =newConfig()    .environment(Environment.LIVE)    .liveEndpointUrlPrefix("myCompany")    .apiKey(apiKey);Clientclient =newClient(config);PaymentsApipaymentsApi =newPaymentsApi(client);// Create PaymentRequestCardDetailscardDetails =newCardDetails()      .type(CardDetails.TypeEnum.SCHEME)      .encryptedCardNumber("5136333333333335")      .holderName("John Doe")      .cvc("737")      .encryptedExpiryMonth("08")      .encryptedExpiryYear("2018");PaymentRequestpaymentRequest =newPaymentRequest()      .merchantAccount("YOUR_MERCHANT_ACCOUNT")      .reference("YOUR_REFERENCE")      .amount(newAmount()          .currency("EUR")          .value(1000L))      .returnUrl("https://your-company.example.org/checkout?shopperOrder=12xy..")      .paymentMethod(newCheckoutPaymentMethod(cardDetails));// Make a call to the /payments endpointPaymentResponsepaymentResponse =paymentsApi.payments(paymentRequest);

General use with basic auth

// Import the required classesimportcom.adyen.Client;importcom.adyen.enums.Environment;importcom.adyen.service.checkout.PaymentLinksApi// Setup Client and Service passing prefixClientclient =newClient("Your username","Your password",Environment.LIVE,"mycompany123");// Or setup Client and Service passing prefix and application name//Client client = new Client("Your username", "Your password", Environment.LIVE, "mycompany123", "Your application name");PaymentLinksApipaymentLinksApi =newPaymentLinksApi(client); ...

Making requests with additional headers

importcom.adyen.Client;importcom.adyen.Config;importcom.adyen.enums.Environment;importcom.adyen.model.RequestOptions;importcom.adyen.service.checkout.PaymentsApi;importcom.adyen.model.checkout.PaymentRequest;importcom.adyen.model.checkout.PaymentResponse;importcom.adyen.model.checkout.Amount;importcom.adyen.model.checkout.CardDetails;importcom.adyen.model.checkout.CheckoutPaymentMethod;importjava.util.HashMap;importjava.util.Map;// Setup Client using Config objectConfigconfig =newConfig()    .environment(Environment.TEST)// Or Environment.LIVE    .apiKey("YOUR_API_KEY");Clientclient =newClient(config);// Create RequestOptionsHashMap<String,String>additionalHeaders =newHashMap<>();additionalHeaders.put("X-Custom-Header","custom-value");RequestOptionsrequestOptions =newRequestOptions()    .idempotencyKey("YOUR_IDEMPOTENCY_KEY")// use UUID    .additionalServiceHeaders(additionalHeaders);PaymentsApipaymentsApi =newPaymentsApi(client);// Create PaymentRequest (example from existing README)CardDetailscardDetails =newCardDetails()      .type(CardDetails.TypeEnum.SCHEME)      .encryptedCardNumber("5136333333333335")      .holderName("John Doe")      .cvc("737")      .encryptedExpiryMonth("08")      .encryptedExpiryYear("2018");PaymentRequestpaymentRequest =newPaymentRequest()      .merchantAccount("YOUR_MERCHANT_ACCOUNT")      .reference("YOUR_REFERENCE")      .amount(newAmount()          .currency("EUR")          .value(1000L))      .returnUrl("https://your-company.example.org/checkout?shopperOrder=12xy..")      .paymentMethod(newCheckoutPaymentMethod(cardDetails));// Make a call to the /payments endpoint with RequestOptionsPaymentResponsepaymentResponse =paymentsApi.payments(paymentRequest,requestOptions);// Process paymentResponseSystem.out.println("Payment response: " +paymentResponse.toJson());

Deserializing JSON Strings

// Import the required model classimportcom.adyen.model.checkout.PaymentRequest;// Deserialize using built-in functionPaymentRequestpaymentRequest =PaymentRequest.fromJson("YOUR_JSON_STRING");

Error handling

try {    service.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();    ....}

Using notification webhooks parser

// Import the required classesimportjava.util.List;importcom.adyen.util.HMACValidator;importcom.adyen.notification.WebhookHandler;importcom.adyen.model.notification.NotificationRequest;importcom.adyen.model.notification.NotificationRequestItem;// YOUR_HMAC_KEY from the Customer AreaStringhmacKey ="YOUR_HMAC_KEY";// The webhook payloadStringnotificationRequestJson ="NOTIFICATION_REQUEST_JSON";HMACValidatorhmacValidator =newHMACValidator();WebhookHandlerwebhookHandler =newWebhookHandler();NotificationRequestnotificationRequest =webhookHandler.handleNotificationJson(notificationRequestJson);// fetch first (and only) NotificationRequestItemvarnotificationRequestItem =notificationRequest.getNotificationItems().stream().findFirst();if (notificationRequestItem.isPresent()) {// validate the HMAC signatureif (hmacValidator.validateHMAC(notificationRequestItem,hmacKey) ) {// Process the notification based on the eventCodelog.info("Received webhook with event {} :\n" +"Merchant Reference: {}\n" +"Alias : {}\n" +"PSP reference : {}",notificationRequestItem.getEventCode(),notificationRequestItem.getMerchantReference(),notificationRequestItem.getAdditionalData().get("alias"),notificationRequestItem.getPspReference());    }else {// Non valid NotificationRequestthrownewRuntimeException("Invalid HMAC signature");    }}

// The webhook payloadStringpayload ="WEBHOOK_JSON_PAYLOAD";// HMAC key from Customer AreaStringhmacKey ="HMAC_KEY_RETRIEVED_FROM_CA";// HMAC signature from hmacsignature headerStringhmacsignature =headers.get("hmacsignature");if (hmacsignature ==null ||hmacsignature.isBlank()) {thrownewRuntimeException("HMAC Signature not found");}// validate the HMAC signatureHMACValidatorhmacValidator =newHMACValidator();if (!hmacValidator.validateHMAC(hmacsignature,hmacKey,payload)) {thrownewRuntimeException("Invalid HMAC signature");}

ConfigurationWebhooksHandlerwebhookHandler =newConfigurationWebhooksHandler(payload);// onAccountHolderNotificationRequestwebhookHandler.getAccountHolderNotificationRequest().ifPresent((AccountHolderNotificationRequestevent) -> {System.out.println(event.getData().getBalancePlatform());});// onBalanceAccountNotificationRequestwebhookHandler.getBalanceAccountNotificationRequest().ifPresent((BalanceAccountNotificationRequestevent) -> {System.out.println(event.getData().getBalanceAccount());});

ManagementWebhooksHandlerwebhookHandler =newManagementWebhooksHandler(payload);// onMerchantCreatedNotificationRequestwebhookHandler.getMerchantCreatedNotificationRequest().isPresent((MerchantCreatedNotificationRequestevent) -> {System.out.println(event.getData().getMerchantId());});

Using Attachments in LEM (Legal Entity Management)

Proxy configuration

...// Import the required classesimportcom.adyen.httpclient.AdyenHttpClient;importjava.net.InetSocketAddress;importjava.net.Proxy;// Set http proxyAdyenHttpClientadyenHttpClientWithProxy =newAdyenHttpClient();Proxyproxy =newProxy(Proxy.Type.HTTP,newInetSocketAddress("PROXY_HOST",PROXY_PORT));adyenHttpClientWithProxy.setProxy(proxy);client.setHttpClient(adyenHttpClientWithProxy);

System.setProperty("https.proxyHost","129.0.0.1");System.setProperty("https.proxyPort","3128");System.setProperty("https.proxyUser","squid");System.setProperty("https.proxyPassword","ward");

Client certificate authentication

// Import the required classesimportcom.adyen.Client;importjavax.net.ssl.KeyManagerFactory;importjavax.net.ssl.SSLContext;importjavax.net.ssl.TrustManagerFactory;importjava.security.KeyStore;// Initialize a KeyManagerFactory with the client KeyStore and passwordKeyManagerFactorykeyManagerFactory =KeyManagerFactory.getInstance(KeyManagerFactory.getDefaultAlgorithm());keyManagerFactory.init(clientKeyStore,clientKeyStorePassword);// Create a TrustManagerFactory that trusts the CAs in our Trust KeyStoreTrustManagerFactorytrustManagerFactory =TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());trustManagerFactory.init(trustStore);// Create an SSLContext with the desired protocol that uses our KeyManagers and TrustManagersSSLContextsslContext =SSLContext.getInstance("TLSv1.2");sslContext.init(keyManagerFactory.getKeyManagers(),trustManagerFactory.getTrustManagers(),null);Clientclient =newClient(sslContext,apiKey);// Use the client

Using the Cloud Terminal API

// Step 1: Import the required classesimportcom.adyen.Client;importcom.adyen.enums.Environment;importcom.adyen.service.TerminalCloudAPI;importcom.adyen.model.nexo.*;importcom.adyen.model.terminal.*;// Step 2: Initialize the client objectConfigconfig =newConfig()    .environment(Environment.LIVE)    .terminalApiRegion(Region.EU)    .apiKey(apiKey);Clientclient =newClient(config);// Step 3: Initialize the API objectTerminalCloudAPIterminalCloudApi =newTerminalCloudAPI(client);// Step 4: Create the request objectStringserviceID ="123456789";StringsaleID ="POS-SystemID12345";StringPOIID ="Your Device Name(eg V400m-123456789)";// Use a unique transaction for every other transaction you performStringtransactionID ="TransactionID";TerminalAPIRequestterminalAPIRequest =newTerminalAPIRequest();SaleToPOIRequestsaleToPOIRequest =newSaleToPOIRequest();MessageHeadermessageHeader =newMessageHeader();messageHeader.setMessageClass(MessageClassType.SERVICE);messageHeader.setMessageCategory(MessageCategoryType.PAYMENT);messageHeader.setMessageType(MessageType.REQUEST);messageHeader.setProtocolVersion("3.0");messageHeader.setServiceID(serviceID);messageHeader.setSaleID(saleID);messageHeader.setPOIID(POIID);saleToPOIRequest.setMessageHeader(messageHeader);com.adyen.model.nexo.PaymentRequestpaymentRequest =newcom.adyen.model.nexo.PaymentRequest();SaleDatasaleData =newSaleData();TransactionIdentificationtransactionIdentification =newTransactionIdentification();transactionIdentification.setTransactionID("001");XMLGregorianCalendartimestamp =DatatypeFactory.newInstance().newXMLGregorianCalendar(newGregorianCalendar());transactionIdentification.setTimeStamp(timestamp);saleData.setSaleTransactionID(transactionIdentification);SaleToAcquirerDatasaleToAcquirerData =newSaleToAcquirerData();ApplicationInfoapplicationInfo =newApplicationInfo();CommonFieldmerchantApplication =newCommonField();merchantApplication.setVersion("1");merchantApplication.setName("Test");applicationInfo.setMerchantApplication(merchantApplication);saleToAcquirerData.setApplicationInfo(applicationInfo);saleData.setSaleToAcquirerData(saleToAcquirerData);PaymentTransactionpaymentTransaction =newPaymentTransaction();AmountsReqamountsReq =newAmountsReq();amountsReq.setCurrency("EUR");amountsReq.setRequestedAmount(BigDecimal.valueOf(1000));paymentTransaction.setAmountsReq(amountsReq);paymentRequest.setPaymentTransaction(paymentTransaction);paymentRequest.setSaleData(saleData);saleToPOIRequest.setPaymentRequest(paymentRequest);terminalAPIRequest.setSaleToPOIRequest(saleToPOIRequest);// Step 5: Make the requestTerminalAPIResponseterminalAPIResponse =terminalCloudApi.sync(terminalAPIRequest);

Optional: perform an abort request

TerminalAPIRequestterminalAPIRequest =newTerminalAPIRequest();SaleToPOIRequestsaleToPOIRequest =newSaleToPOIRequest();MessageHeadermessageHeader =newMessageHeader();messageHeader.setMessageClass(MessageClassType.SERVICE);messageHeader.setMessageCategory(MessageCategoryType.ABORT);messageHeader.setMessageType(MessageType.REQUEST);messageHeader.setProtocolVersion("3.0");messageHeader.setServiceID("Different service ID");messageHeader.setSaleID(saleID);messageHeader.setPOIID(POIID);AbortRequestabortRequest =newAbortRequest();abortRequest.setAbortReason("MerchantAbort");MessageReferencemessageReference =newMessageReference();messageReference.setMessageCategory(MessageCategoryType.PAYMENT);messageReference.setSaleID(saleID);messageReference.setPOIID(POIID);// Service ID of the payment you're abortingmessageReference.setServiceID(serviceID);abortRequest.setMessageReference(messageReference);saleToPOIRequest.setAbortRequest(abortRequest);saleToPOIRequest.setMessageHeader(messageHeader);terminalAPIRequest.setSaleToPOIRequest(saleToPOIRequest);TerminalAPIResponseterminalAPIResponse =terminalCloudApi.sync(terminalAPIRequest);

Optional: perform a status request

TerminalAPIRequestterminalAPIRequest =newTerminalAPIRequest();SaleToPOIRequestsaleToPOIRequest =newSaleToPOIRequest();MessageHeadermessageHeader =newMessageHeader();messageHeader.setMessageClass(MessageClassType.SERVICE);messageHeader.setMessageCategory(MessageCategoryType.TRANSACTION_STATUS);messageHeader.setMessageType(MessageType.REQUEST);messageHeader.setProtocolVersion("3.0");messageHeader.setServiceID("Different service ID");messageHeader.setSaleID(saleID);messageHeader.setPOIID(POIID);TransactionStatusRequesttransactionStatusRequest =newTransactionStatusRequest();transactionStatusRequest.setReceiptReprintFlag(true);transactionStatusRequest.getDocumentQualifier().add(DocumentQualifierType.CASHIER_RECEIPT);transactionStatusRequest.getDocumentQualifier().add(DocumentQualifierType.CUSTOMER_RECEIPT);MessageReferencemessageReference =newMessageReference();messageReference.setMessageCategory(MessageCategoryType.PAYMENT);messageReference.setSaleID(saleID);// serviceID of the transaction you want the status update frommessageReference.setServiceID(serviceID);transactionStatusRequest.setMessageReference(messageReference);saleToPOIRequest.setTransactionStatusRequest(transactionStatusRequest);saleToPOIRequest.setMessageHeader(messageHeader);terminalAPIRequest.setSaleToPOIRequest(saleToPOIRequest);TerminalAPIResponseterminalAPIResponse =terminalCloudApi.sync(terminalAPIRequest);

Helper classes

PredefinedContentHelperhelper =newPredefinedContentHelper(predefinedContent.getReferenceID());// Safely extract and use the event type with Optionalhelper.getEvent().ifPresent(event -> {System.out.println("Received event: " +event);if (event ==PredefinedContentHelper.DisplayNotificationEvent.PIN_ENTERED) {// Handle PIN entry eventSystem.out.println("The user has entered their PIN.");    }});

Using the Local Terminal API Integration

Local terminal API Using Keystore

// Import the required classesimportcom.adyen.Client;importcom.adyen.Config;importcom.adyen.enums.Environment;importcom.adyen.httpclient.TerminalLocalAPIHostnameVerifier;importcom.adyen.service.TerminalLocalAPI;importcom.adyen.model.terminal.security.*;importcom.adyen.model.terminal.*;importjavax.net.ssl.SSLContext;importjavax.net.ssl.TrustManagerFactory;importjava.security.KeyStore;importjava.security.SecureRandom;// Create a KeyStore for the terminal certificateKeyStorekeyStore =KeyStore.getInstance(KeyStore.getDefaultType());keyStore.load(null,null);keyStore.setCertificateEntry("adyenRootCertificate",adyenRootCertificate);// Create a TrustManagerFactory that trusts the CAs in our KeyStoreTrustManagerFactorytrustManagerFactory =TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());trustManagerFactory.init(keyStore);// Create an SSLContext with the desired protocol that uses our TrustManagersSSLContextsslContext =SSLContext.getInstance("SSL");sslContext.init(null,trustManagerFactory.getTrustManagers(),newSecureRandom());// Configure a client for TerminalLocalAPIConfigconfig =newConfig();config.setEnvironment(environment);config.setTerminalApiLocalEndpoint("https://" +terminalIpAddress);config.setSSLContext(sslContext);config.setHostnameVerifier(newTerminalLocalAPIHostnameVerifier(environment));Clientclient =newClient(config);// Create your SecurityKey object used for encrypting the payload (keyIdentifier/passphrase you set up beforehand in CA)SecurityKeysecurityKey =newSecurityKey();securityKey.setKeyVersion(1);securityKey.setAdyenCryptoVersion(1);securityKey.setKeyIdentifier("keyIdentifier");securityKey.setPassphrase("passphrase");// Use TerminalLocalAPITerminalLocalAPIterminalLocalAPI =newTerminalLocalAPI(client,securityKey);TerminalAPIResponseterminalAPIResponse =terminalLocalAPI.request(terminalAPIRequest);

Using Attachments in Document API

Using the Local Terminal API Integration without Encryption (Only on TEST)

// Step 1: Import the required classesimportcom.adyen.service.TerminalLocalAPI;importcom.adyen.model.nexo.*;importcom.adyen.model.terminal.*;importjavax.net.ssl.SSLContext;// Step 2: Add your Certificate Path and Local Endpoint to the config path.Clientclient =newClient();client.getConfig().setTerminalApiLocalEndpoint("The IP of your terminal (eg https://192.168.47.169)");client.getConfig().setEnvironment(Environment.TEST);config.setSSLContext(createTrustSSLContext());// Trust all certificates for testing onlyclient.setConfig(config);// Step 3: Create an SSL context that accepts all certificates (Use in TEST only).SSLContextcreateTrustSSLContext()throwsException {TrustManager[]trustAllCerts =newTrustManager[]{newX509TrustManager() {java.security.cert.X509Certificate[]getAcceptedIssuers() {returnnull; }checkClientTrusted(java.security.cert.X509Certificate[]certs,StringauthType) {}checkServerTrusted(java.security.cert.X509Certificate[]certs,StringauthType) {}            }    };SSLContextsc =SSLContext.getInstance("SSL");sc.init(null,trustAllCerts,newjava.security.SecureRandom());returnsc;}// Step 4: Construct a TerminalAPIRequest objectGsongson =newGsonBuilder().create();TerminalAPIRequestterminalAPIPaymentRequest =newTerminalAPIRequest();// Step 5: Make the requestTerminalAPIResponseterminalAPIResponse =terminalLocalAPI.request(terminalAPIRequest);

Example integrations

Feedback

Contributing

Support

Licence

See also