SDK > Java | Payment Gateway

Java

Java è un linguaggio di programmazione ad alto livello, orientato agli oggetti e a tipizzazione statica, che si appoggia sull'omonima piattaforma software di esecuzione, specificamente progettato per essere il più possibile indipendente dalla piattaforma hardware di esecuzione tramite compilazione in bytecode prima e interpretazione poi da parte di una JVM.

Tramite l'SDK messo a disposizione da Nexi è possibile scegliere tra il client OkHttp e HttpClient5.

Installazione

Per installare l'sdk Java tramite Maven aggiungere al file pom.xml la seguente dipendenza:

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

Successivamente è necessario includere la dipendenza per uno dei due client HTTP supportati:

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

Oppure:

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

Configurazione

Per poter comunicare con il gateway è necessario creare un oggetto di configurazione che implementa l'interfaccia io.github.nexipayments.sdknpg.configuration.IConfiguration.

                                    @Data
public class Configuration implements IConfiguration {

    public Configuration(
        final String apiKey = "<X-Api-Key>" // inserire 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");  // indirizzo ambiente di test
        } catch (MalformedURLException e) {
            throw new IllegalStateException(e);
        }
    }

}
                                

Per l'utilizzo in produzione è necessario utilizzare l'interfaccia io.github.nexipayments.sdknpg.configuration.ConfigurationProduction, in alternativa si può procedere con un'implementazione personalizzata che deve rispettare l'interfaccia stabilita.

È necessario fornire un ulteriore oggetto per lo storage persistente dei security token, usati per autenticare le notifiche che deve gestire l'interfaccia io.github.nexipayments.sdknpg.securitytokenstorage.ISecurityTokenStorage.

Questo storage associa ad ogni orderId uno o più token, questi devono essere persistiti in maniera durevole per validare gli eventi in ingresso da parte del gateway.

Una volta instanziati i due oggetti che aderiscono alle interfacce appena nominate si può procedere ad utilizzare uno dei due metodi statici della classe io.github.nexipayments.sdknpg.PaymentGatewayClient per ottenere l'istanza del client adeguata alla libreria HTTP scelta:

getInstanceOkHttp3: userà okhttp3
getInstanceApacheHttpClient5: userà httpclient5

Esempio di utilizzo

Ottenuto l'oggetto tramite uno dei due metodi statici presentati nella sezione precedente, è possibile procedere con le richieste verso il gateway. Di seguito un esempio di pagamento tramite la modalità Hosted Payment Page:

                                    final Order order = new Order(); // creazione oggetto ordine
order.setOrderId("MY-FIRST-ORDER"); // assegnazione identificativo all'ordine
order.setCurrency("EUR"); // assegnazione divisa all'ordine
order.setAmount(100); // assegnazione importo all'ordine

final PaymentSession paymentSession = new PaymentSession(); // creazione oggetto sessione di pagamento
paymentSession.setAmount(100); // impostazione dell'importo per la sessione di pagamento
paymentSession.setResultUrl("http://www.example.com/payments/result/" + order.getOrderId()); // impostazione indirizzo di esito
paymentSession.setCancelUrl("http://www.example.com/payments/cancel/" + order.getOrderId()); // impostazione indirizzo di annullo
paymentSession.setNotificationUrl("http://www.example.com/payments/s2s-notify/" + order.getOrderId()); // impostazione indirizzo di notifica

// impostazione oggetto di chiamata per pagamento Hosted Payment Page
final CreateHostedOrderRequest createHostedOrderRequest = new CreateHostedOrderRequest(order, paymentSession); 
// impostazione oggetto di esito per il pagamento Hosted Payment Page
final CreateHostedOrderResponse createHostedOrderResponse = paymentGatewayClient.createOrderForHostedPayment(createHostedOrderRequest); 

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

Gli oggetti, così come i metodi "set" per l'impostazione dei parametri, prendono riferimento dall'API POST /orders/hpp. L'SDK è stato sviluppato mantenendo i nomi dei parametri uguali a quelli delle API del gateway, per facilitare e migliorare l'esperienza di utilizzo.

Notifiche

Per validare le notifiche in ingresso dal gateway serve esporre l'endpoint indicato nel parametro "notificationUrl" della richiesta di avvio POST /orders/hpp, l'endpoint deve accettare un JSON con metodo POST. Tale JSON può essere validato dall'SDK con il metodo parseAndValidateWebhook che, sfruttando l'oggetto di storage persistente, provvede a verificare la congruenza del token di sicurezza oppure a sollevare un'eccezione:

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

In caso il sistema utilizzato supporti la deserializzazione del JSON con una classe specificata è possibile utilizzare l'interfaccia io.github.nexipayments.sdknpg.pojo.WebhookNotificationBody e procedere con la validazione dell'oggetto ricevuto:

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

Elenco API

Di seguito l'elenco delle API XPay disponibili nell'SDK, accessibili attraverso le funzioni presenti nel file PaymentGatewayClient.java:

Hosted Payment Page (POST /orders/hpp)
Pay-By-Link (POST /orders/paybylink)
M.O.T.O. (POST /orders/moto)
Pagamento ricorrente (POST /orders/mit)
Elenco ordini (GET /orders)
Ricerca ordine (GET /orders/{orderId})
Elenco operazioni (GET /operations)
Ricerca operazioni (GET /operations/{operationId})
Storno (POST /operations/{operationId}/refunds)
Contabilizzazione (POST /operations/{operationId}/captures)
Annullo contabilizzazione (POST /operations/{operationId}/cancels)
Elenco metodi di pagamento (GET /payment_methods)
Verifica carta (POST /orders/card_verification)
Annullo link Pay-By-Link (POST /paybylink/{linkId}/cancels)
Ricerca contratti (GET /contracts/customers/{customerId})
Disattiva contratto (POST /contracts/{contractId}/deactivation)
3 Step Init (POST /orders/3steps/init)
3 Step Validation (POST /orders/3steps/validation)
3 Step Pagamento (POST /orders/3steps/payment)