Skip to content

README.md

Latest commit

 

History

History
368 lines (291 loc) · 34.4 KB

README.md

File metadata and controls

368 lines (291 loc) · 34.4 KB

Java

Adyen Java API Library

Maven Central

This is the officially supported Java library for using Adyen's APIs.

Supported API versions

The Library supports all APIs under the following services:

API Description Service Name Supported version
BIN lookup API The BIN Lookup API provides endpoints for retrieving information based on a given BIN. BinLookup v54
Checkout API Our latest integration for accepting online payments. Checkout v71
Configuration API The Configuration API enables you to create a platform where you can onboard your users as account holders and create balance accounts, cards, and business accounts. balanceplatform package subclasses v2
Cloud device API Cloud Device point-of-sale integration. clouddevice package subclasses v1
DataProtection API Adyen Data Protection API provides a way for you to process Subject Erasure Requests as mandated in GDPR. Use our API to submit a request to delete shopper's data, including payment details and other related information (for example, delivery address or shopper email) DataProtection v1
Disputes API You can use the Disputes API to automate the dispute handling process so that you can respond to disputes and chargebacks as soon as they are initiated. The Disputes API lets you retrieve defense reasons, supply and delete defense documents, and accept or defend disputes. DisputesApi v30
Legal Entity Management API Manage legal entities that contain information required for verification. legalentitymanagement package subclasses v3
Local/Cloud-based Terminal API Our point-of-sale integration. TerminalLocalAPI or TerminalCloudAPI v1
Management API Configure and manage your Adyen company and merchant accounts, stores, and payment terminals. management package subclasses v3
Open Banking API The Open Banking API provides secure endpoints to share financial data and services with third parties. openbanking package subclasses v1
Payments API Our classic integration for online payments. Payment v68
Payments App API The Payments App API is used to Board and manage the Adyen Payments App on your Android mobile devices. PaymentsAppApi v1
Payouts API Endpoints for sending funds to your customers. Payout v68
POS Mobile API The POS Mobile API is used in the mutual authentication flow between an Adyen Android or iOS POS Mobile SDK and the Adyen payments platform. The POS Mobile SDK for Android or iOS devices enables businesses to accept in-person payments using a commercial off-the-shelf (COTS) device like a phone. For example, Tap to Pay transactions, or transactions on a mobile device in combination with a card reader POS Mobile v68
POS Terminal Management API Endpoints for managing your point-of-sale payment terminals. ‼️ Deprecated: use instead the Management API for the management of your terminal fleet. TerminalManagement v1
Recurring API Endpoints for managing saved payment details. Recurring v68
Session Authentication API Create and manage the JSON Web Tokens (JWT) required for integrating Onboarding and Platform Experience components. SessionAuthentication v1
Stored Value API Manage both online and point-of-sale gift cards and other stored-value cards. StoredValue v46
Transfers API The Transfers API provides endpoints that can be used to get information about all your transactions, move funds within your balance platform or send funds from your balance platform to a transfer instrument. Transfers v4
Classic Platforms Account API This API is used for the classic integration. If you are just starting your implementation, refer to our new integration guide instead. ClassicPlatformAccountApi v6
Classic Platforms Fund API This API is used for the classic integration. If you are just starting your implementation, refer to our new integration guide instead. ClassicPlatformFundApi v6
Classic Platforms Hosted Onboarding Page API This API is used for the classic integration. If you are just starting your implementation, refer to our new integration guide instead. ClassicPlatformHopApi v6
Classic Platforms Notification Configuration API This API is used for the classic integration. If you are just starting your implementation, refer to our new integration guide instead. ClassicPlatformConfigurationApi v6

Supported Webhook versions

The library supports all webhooks under the following model directories:

Webhooks Description Model Name Supported Version
Authentication Webhooks Adyen sends this webhook when the process of cardholder authentication is finalized, whether it is completed successfully, fails, or expires. acswebhooks v1
Balance Webhooks Adyen sends webhooks to inform you of balance changes in your balance platform. balancewebhooks v1
Configuration Webhooks You can use these webhooks to build your implementation. For example, you can use this information to update internal statuses when the status of a capability is changed. configurationwebhooks v2
Transfer Webhooks You can use these webhooks to build your implementation. For example, you can use this information to update balances in your own dashboards or to keep track of incoming funds. transferwebhooks v4
Report Webhooks You can download reports programmatically by making an HTTP GET request, or manually from your Balance Platform Customer Area reportwebhooks v1
Negative Balance Warning Webhooks Adyen sends this webhook to inform you about a balance account whose balance has been negative for a given number of days. negativebalancewarningwebhooks v1
Notification Webhooks We use webhooks to send you updates about payment status updates, newly available reports, and other events that you can subscribe to. For more information, refer to our documentation notification v1
Management Webhooks Adyen uses webhooks to inform your system about events that happen with your Adyen company and merchant accounts, stores, payment terminals, and payment methods when using Management API managementwebhooks v3
Transaction Webhooks Adyen sends webhooks to inform your system about incoming and outgoing transfers in your platform. You can use these webhooks to build your implementation. For example, you can use this information to update balances in your own dashboards or to keep track of incoming funds. transactionwebhooks v4
Tokenization Webhooks Adyen sends webhooks to inform you about the creation and changes to the recurring tokens. tokenizationwebhooks v1
Classic Platform Webhooks The Notification API sends notifications to the endpoints specified in a given subscription. Subscriptions are managed through the Notification Configuration API. The API specifications listed here detail the format of each notification. marketpaywebhooks v6

For more information, refer to our documentation or the API Explorer.

Prerequisites

Installation

You can use Maven and add this dependency to your project's POM:

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

Alternatively, you can download the release on GitHub.

Using the library

General use with API key

Every API the library supports is represented by a service object. The name of the service matching the corresponding API is listed in the Supported API versions section of this document.

// Import the required classes
import com.adyen.Client;
import com.adyen.enums.Environment;
import com.adyen.service.checkout.PaymentsApi;
import com.adyen.model.checkout.*;

// Setup Client and Service
Client client = new Client("Your X-API-KEY", Environment.TEST);
PaymentsApi paymentsApi = new PaymentsApi(client);

// Create PaymentRequest 
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));

// Make a call to the /payments endpoint
PaymentResponse paymentResponse = paymentsApi.payments(paymentRequest);

General use with API key for live environment

For requests on live environment, you need to pass the Live URL Prefix to the Client object:

// Import the required classes
import com.adyen.Client;
import com.adyen.enums.Environment;
import com.adyen.service.checkout.ModificationsApi

// Setup Client and Service
Client client = new Client("Your X-API-KEY", Environment.LIVE, "Your live URL prefix");
ModificationsApi modificationsApi = new ModificationsApi(client);

...

General use with basic auth

// Import the required classes
import com.adyen.Client;
import com.adyen.enums.Environment;
import com.adyen.service.checkout.PaymentLinksApi

// Setup Client and Service
Client client = new Client("Your username", "Your password", Environment.LIVE, "Your live URL prefix", "Your application name");
PaymentLinksApi paymentLinksApi = new PaymentLinksApi(client);
 
...

Deserializing JSON Strings

In some setups you might need to deserialize JSON strings to request objects. For example, when using the libraries in combination with Dropin/Components. Please use the built-in deserialization functions:

// Import the required model class
import com.adyen.model.checkout.PaymentRequest;

// Deserialize using built-in function
PaymentRequest paymentRequest = PaymentRequest.fromJson("YOUR_JSON_STRING");

Using notification webhooks parser

// Import the required classes
import java.util.List;
import com.adyen.util.HMACValidator;
import com.adyen.notification.WebhookHandler;
import com.adyen.model.notification.NotificationRequest;
import com.adyen.model.notification.NotificationRequestItem;

// YOUR_HMAC_KEY from the Customer Area
String hmacKey = "YOUR_HMAC_KEY";
// The webhook payload
String notificationRequestJson = "NOTIFICATION_REQUEST_JSON";

HMACValidator hmacValidator = new HMACValidator();

WebhookHandler webhookHandler = new WebhookHandler();
NotificationRequest notificationRequest = webhookHandler.handleNotificationJson(notificationRequestJson);

// fetch first (and only) NotificationRequestItem
var notificationRequestItem = notificationRequest.getNotificationItems().stream().findFirst();

if (notificationRequestItem.isPresent()) {
    // validate the HMAC signature
    if ( hmacValidator.validateHMAC(notificationRequestItem, hmacKey) ) {
      // Process the notification based on the eventCode
      log.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 NotificationRequest
	  throw new RuntimeException("Invalid HMAC signature");
    }
}

When deserializing Banking or Management Webhooks, first check if the payload is authentic:

// The webhook payload
String payload = "WEBHOOK_JSON_PAYLOAD";
// HMAC key from Customer Area
String hmacKey = "HMAC_KEY_RETRIEVED_FROM_CA";

// HMAC signature from hmacsignature header
String hmacsignature = headers.get("hmacsignature");
if (hmacsignature == null || hmacsignature.isBlank()) {
   throw new RuntimeException("HMAC Signature not found");
}

// validate the HMAC signature
HMACValidator hmacValidator = new HMACValidator();
if (!hmacValidator.validateHMAC(hmacsignature, hmacKey, payload)) {
   throw new RuntimeException("Invalid HMAC signature");
}

Use then the relevant webhook handler (i.e. ConfigurationWebhooksHandler) to obtain the object representing the event:

ConfigurationWebhooksHandler webhookHandler = new ConfigurationWebhooksHandler(payload);
// onAccountHolderNotificationRequest
webhookHandler.getAccountHolderNotificationRequest().ifPresent((AccountHolderNotificationRequest event) -> {
    System.out.println(event.getData().getBalancePlatform());
});
// onBalanceAccountNotificationRequest
webhookHandler.getBalanceAccountNotificationRequest().ifPresent((BalanceAccountNotificationRequest event) -> {
    System.out.println(event.getData().getBalanceAccount());
});

To deserialize Management Webhooks use instead the specific webhook handler ManagementWebhooksHandler:

ManagementWebhooksHandler webhookHandler = new ManagementWebhooksHandler(payload);
// onMerchantCreatedNotificationRequest
webhookHandler.getMerchantCreatedNotificationRequest().isPresent((MerchantCreatedNotificationRequest event) -> {
System.out.println(event.getData().getMerchantId());
});

Using Attachments in LEM (Legal Entity Management)

When using Attachments, ensure content is provided as a byte array. It's important to convert it to a Base64-encoded string before initiating the request.

Proxy configuration

You can configure a proxy connection by injecting your own AdyenHttpClient on your client instance.

Example:

...
// Import the required classes
import com.adyen.httpclient.AdyenHttpClient;
import java.net.InetSocketAddress;
import java.net.Proxy;

// Set http proxy
AdyenHttpClient adyenHttpClientWithProxy = new AdyenHttpClient();

Proxy proxy = new Proxy(Proxy.Type.HTTP, new InetSocketAddress("PROXY_HOST", PROXY_PORT));
adyenHttpClientWithProxy.setProxy(proxy);

client.setHttpClient(adyenHttpClientWithProxy);

If your proxy requires authentication, set all the settings as system properties instead (don't mix with previous approach), for example:

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 classes
import com.adyen.Client;
import javax.net.ssl.KeyManagerFactory;
import javax.net.ssl.SSLContext;
import javax.net.ssl.TrustManagerFactory;
import java.security.KeyStore;

// Initialize a KeyManagerFactory with the client KeyStore and password
KeyManagerFactory keyManagerFactory = KeyManagerFactory.getInstance(KeyManagerFactory.getDefaultAlgorithm());
keyManagerFactory.init(clientKeyStore, clientKeyStorePassword);

// Create a TrustManagerFactory that trusts the CAs in our Trust KeyStore
TrustManagerFactory trustManagerFactory = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());
trustManagerFactory.init(trustStore);

// Create an SSLContext with the desired protocol that uses our KeyManagers and TrustManagers
SSLContext sslContext = SSLContext.getInstance("TLSv1.2");
sslContext.init(keyManagerFactory.getKeyManagers(), trustManagerFactory.getTrustManagers(), null);

Client client = new Client(sslContext, apiKey);
// Use the client

Classic Platforms Error Handling

When requests fail, the library throws exceptions. For Classic AFP endpoints like Create Account Holder, you can decode further details from the exception:

Client client = new Client("Your YOUR_API_KEY", Environment.TEST);
ClassicPlatformAccountApi api = new ClassicPlatformAccountApi(client);
CreateAccountHolderRequest request = new CreateAccountHolderRequest();

try {
    api.createAccountHolder(request);
} catch (ApiException e) {
    CreateAccountHolderResponse error = CreateAccountHolderResponse.fromJson(e.getResponseBody());
    // inspect the error
    System.out.println(e.getStatusCode());
    System.out.println(error.getInvalidFields());
}

In-person payments integration

Build a feature-rich in-person payments integrations that accept payments around the world, with global and local payment methods and create a unique shopping experience for your customers.

Using the Cloud Device API

For In-Person Payments integrations, the recommended solution is the Cloud Device API.

Check the Cloud Device API README.

Using the Terminal API

With the Terminal API you can send and receive Terminal API messages in the following ways:

  • Local communications: using your local network, your POS system sends the request directly to the IP address of the terminal, and receives the result synchronously.
  • Cloud communications: using the internet to access the cloud /sync and /async endpoints. You should consider adopting the Cloud Device API instead.

Check the Terminal API README.

Example integrations

For a closer look at how our Java library works, you can clone one of our example integrations:

These include commented code, highlighting key features and concepts, and examples of API calls that can be made using the library.

Feedback

We value your input! Help us enhance our API Libraries and improve the integration experience by providing your feedback. Please take a moment to fill out our feedback form to share your thoughts, suggestions or ideas.

Contributing

We encourage you to contribute to this repository, so everyone can benefit from new features, bug fixes, and any other improvements.

Have a look at our contributing guidelines to find out how to raise a pull request.

Support

If you have a feature request, or spotted a bug or a technical problem, create an issue here.

For other questions, contact our Support Team.

Licence

This repository is available under the MIT license.

See also