Java

Overview

Java is a high-level, object-oriented and statically typed programming language, which relies on the homonymous execution software platform, specifically designed to be as independent as possible from the hardware platform of execution by compilation in bytecode first and then interpretation by a JVM.

Through the SDK, it is possible to choose between the OkHttp and HttpClient5 client.

Installation

To install the Java SDK using Maven, add the following dependency to the POM FILE.XML:

<dependency>
    <groupId>it.iplusservice</groupId>
    <artifactId>nexi-npg-sdk-java</artifactId>
    <version>1.0.0-RELEASE</version>

Next you need to include the dependency for one of the two supported HTTP clients:

<dependency>
   <groupId>com.squareup.okhttp3</groupId>
   <artifactId>okhttp</artifactId>
</dependency>

Or:

<dependency>
   <groupId>org.apache.httpcomponents.client5</groupId>
   <artifactId>httpclient5</artifactId>
</dependency>

Configuration

In order to communicate with the gateway it is necessary to create a configuration object that implements the interface io.github.nexipayments.sdknpg.configuration.IConfiguration.

For use in production it is necessary to use the interface io.github.nexipayments.sdknpg.configuration.

ConfigurationProduction, alternatively you can proceed with a customized implementation that must respect the established interface.

It is necessary to provide an additional object for the persistent storage of security tokens, used to authenticate the notifications that the interface must manage io.github.nexipayments.sdknpg.securitytokenstorage.ISecurityTokenStorage.

This storage associates one or more tokens with each orderId, these must be persistently persisted to validate incoming events from the gateway.

Once the two objects that adhere to the interfaces just mentioned have been instantiated, you can proceed to use one of the two static methods of the class io.github.nexipayments.sdknpg.PaymentGatewayClient to get the client instance suitable for the chosen HTTP library:

• getInstanceOkHttp3: will use okhttp3
• getInstanceApacheHttpClient5: will use httpclient5

Example of Use

Once the object has been obtained through one of the two static methods presented in the previous section, it is possible to proceed with requests to the gateway. Below is an example of payment using the method Hosted Payment Page:

final Order order = new Order();
order.setOrderId("MY-FIRST-ORDER");
order.setCurrency("EUR");
order.setAmount(100L);

Objects, as well as "set" methods for setting parameters, are referenced by the API POST /orders/hpp. The SDK was developed keeping the parameter names the same as those of the gateway API, to facilitate and improve the user experience.

Notifications

To validate the notifications coming in from the gateway, it is necessary to expose the endpoint indicated in the "notificationUrl" parameter of the start request POST /orders/hpp, the endpoint must accept a JSON with POST method.

This JSON can be validated by the SDK with the parseAndValidateWebhook method which, using the persistent storage object, verifies the consistency of the security token or raises an exception:

final WebhookNotificationBody webhookNotificationBody = paymentGatewayClient.parseAndValidateWebhook(json);
log.info(
    "webhookNotificationBody: {}",
    webhookNotificationBody

If the system used supports the deserialization of JSON with a specified class, the interface can be used io.github.nexipayments.sdknpg.pojo.WebhookNotificationBody and proceed with the validation of the object received:

paymentGatewayClient.validateWebhook(webhookNotificationBody);
log.info(
    "webhookNotificationBody: {}",
    webhookNotificationBody