SDK > Java | Payment Gateway

Java

Java is a high-level programming language, object-oriented and with static typing, which relies on the execution software platform of the same name, specifically designed to be as independent as possible from the execution hardware platform by compiling in bytecode first and then interpreting by part of a JVM.

Through the SDK made available by Nexi it is possible to choose between the OkHttp client and HttpClient5.

Installation

To install the Java SDK via Maven add the following dependency to the pom.xml file:

                                    <dependency>
    <groupId>io.github.nexipayments</groupId>
    <artifactId>sdk-java-npg</artifactId>
    <version>0.0.6-RELEASE</version>
</dependency>
                                

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.

                                    @Data
public class Configuration implements IConfiguration {

    public Configuration(
        final String apiKey = "<X-Api-Key>" // enter api-key
    ) {
        this.apiKey = apiKey;
    }

    @ToString.Exclude
    private final String apiKey;

    public URL getGatewayBaseUrl() {
        try {
            return new URL("https://stg-ta.nexigroup.com/api/phoenix-0.0/psp/api/v1");  // test environment address
        } catch (MalformedURLException e) {
            throw new IllegalStateException(e);
        }
    }

}
                                

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(); // Creating an order object
order.setOrderId("MY-FIRST-ORDER"); // Assigning an identifier to the order
order.setCurrency("EUR"); // Assigning currency to the order
order.setAmount(100); // Assigning an amount to the order

final PaymentSession paymentSession = new PaymentSession(); // Creating a payment session object
paymentSession.setAmount(100); // Setting the amount for the payment session
paymentSession.setResultUrl("http://www.example.com/payments/result/" + order.getOrderId()); // Setting the result URL
paymentSession.setCancelUrl("http://www.example.com/payments/cancel/" + order.getOrderId()); // Setting the cancel URL
paymentSession.setNotificationUrl("http://www.example.com/payments/s2s-notify/" + order.getOrderId()); // Setting the notification URL

// Setting up the request object for Hosted Payment Page payment
final CreateHostedOrderRequest createHostedOrderRequest = new CreateHostedOrderRequest(order, paymentSession); 
// Setting up the response object for Hosted Payment Page payment
final CreateHostedOrderResponse createHostedOrderResponse = paymentGatewayClient.createOrderForHostedPayment(createHostedOrderRequest); 

log.info(
    "Redirecting user to: {}",
    createHostedOrderResponse.getHostedPage()
);
                                

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.

Notification

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
);
                                

API Overview

Below is the list of XPay APIs available in the SDK, accessible through the functions in the PaymentGatewayClient.java file:

Hosted Payment Page (POST /orders/hpp)
Pay-By-Link (POST /orders/paybylink)
M.O.T.O. (POST /orders/moto)
Recurring Payment (POST /orders/mit)
Order List (GET /orders)
Order Search (GET /orders/{orderId})
Operations List (GET /operations)
Operation Search (GET /operations/{operationId})
Refund (POST /operations/{operationId}/refunds)
Capture (POST /operations/{operationId}/captures)
Capture Cancellation(POST /operations/{operationId}/cancels)
Payment Methods List (GET /payment_methods)
Card Verification (POST /orders/card_verification)
Pay-By-Link Cancelation (POST /paybylink/{linkId}/cancels)
Contract Search (GET /contracts/customers/{customerId})
Deactivate Contract (POST /contracts/{contractId}/deactivation)
3 Step Initiation (POST /orders/3steps/init)
3 Step Validation (POST /orders/3steps/validation)
3 Step Payment (POST /orders/3steps/payment)