API > Specifiche di utilizzo del servizio

Specifiche di utilizzo del servizio

Le API esposte da XPay supportano il protocollo HTTP con cifratura del canale e utilizzano il formato JSON per la richiesta e risposta.

Di seguito i dettagli tecnici per l'invocazione ai servizi.

Specifiche di chiamata

Protocollo	HTTPS
Metodo	GET/POST
Content-Type	application/json
Url di produzione	https://xpay.nexigroup.com/api/phoenix-0.0/psp/api/v1/
Url di test	https://xpaysandbox.nexigroup.com/api/phoenix-0.0/psp/api/v1/

Raccomandiamo di evitare chiamate dirette e/o l'inserimento degli indirizzi IP di risoluzione DNS degli endpoint nelle liste di autorizzazione del firewall. Tuttavia, nel caso in cui siano state configurate whitelist, aggiornarle con i seguenti indirizzi di produzione:

185.198.117.102
185.198.118.102

Vengono supportati i protocolli TLSv1.2 e TLSv1.3. Di seguito i cipher:

TLS 1.2:
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
- TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
- TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
TLS 1.3:
- AES_128_GCM_SHA256
- AES_256_GCM_SHA384
- CHACHA20_POLY1305_SHA256

Di seguito il dettaglio del certificato installato in ambiente di test e produzione:

CERTIFICATO DI ROOT	GlobalSign Root CA - R3
Numero di serie	04:00:00:00:00:01:21:58:53:08:A2
La CA intermedia è	GlobalSign RSA Organization Validation CA - 2018
Numero di serie	01:EE:5F:22:1D:FC:62:3B:D4:33:3A:85:57

Qualora fosse necessario scaricare i certificati, consultare le pagine web della Certification Authority (CA):

Di seguito vengono presentati alcuni esempi di chiamata verso i servizi di XPay in diversi linguaggi di programmazione:

PHP

JAVA

PYTHON

        <?php

$apiUrl = "https://xpaysandbox.nexigroup.com/api/phoenix-0.0/psp/api/v1";
$apiKey = "API_KEY";
$orderId = "MY_ORDER_ID";

$requestBodyData = array(
    "order" => array(
        "orderId" => $orderId,
        "amount" => 10,
        "currency" => "EUR",
    ),
    "paymentSession" => array(
        "actionType" => "PAY",
        "amount" => 10,
        "recurrence" => array(
          "action" => "NO_RECURRING",
        ),
        "language" => "ENG",
        "resultUrl" => "https://www.example.com/payment/result",
        "cancelUrl" => "https://www.example.com/payment/cancel",
        "notificationUrl" => "https://www.example.com/payment/notification",
    ),
);

$rawCorrelationId = bin2hex(openssl_random_pseudo_bytes(16));

$correlationId =  substr($rawCorrelationId, 0, 8);
$correlationId .= "-";
$correlationId .=  substr($rawCorrelationId, 8, 4);
$correlationId .= "-";
$correlationId .=  substr($rawCorrelationId, 12, 4);
$correlationId .= "-";
$correlationId .=  substr($rawCorrelationId, 16, 4);
$correlationId .= "-";
$correlationId .=  substr($rawCorrelationId, 20);

$headers = array(
    "X-Api-Key: " . $apiKey,
    "Content-Type: application/json",
    "Correlation-Id: " . $correlationId,
);

$ch = curl_init($apiUrl ."/orders/hpp");
$payload = json_encode($requestBodyData);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$resultJson = curl_exec($ch);

if (curl_errno($ch)) {
    die("curl error: " . curl_error($ch));
}

$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if ($http_code != 200) {
    die("invalid http status code: ".print_r($http_code, true));
}

curl_close($ch);

$resultData = json_decode($resultJson);

echo "Hosted Page: " . $resultData->hostedPage . "\n";
echo "Security Token: " . $resultData->securityToken . "\n";
?>
    

        package example;

import java.io.IOException;
import java.util.UUID;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.databind.ObjectMapper;
import lombok.Data;
import lombok.extern.slf4j.Slf4j;
import okhttp3.Call;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;
import okhttp3.ResponseBody;

@Slf4j
public class CreateHpp {

  public static void main(String[] args) throws IOException {
    final String apiUrl = "https://xpaysandbox.nexigroup.com/api/phoenix-0.0/psp/api/v1";
    final String apiKey = "API_KEY";
    final String orderId = "MY_ORDER_ID";

    final CreateHostedOrderRequest createHostedOrderRequest = new CreateHostedOrderRequest();
    createHostedOrderRequest.getOrder().setOrderId(orderId);
    createHostedOrderRequest.getOrder().setAmount(10L);
    createHostedOrderRequest.getOrder().setCurrency("EUR");
    createHostedOrderRequest.getOrder().setAmount(100L);

    final RecurringSettings recurringSettings = new RecurringSettings();
    recurringSettings.setAction(RecurringAction.NO_RECURRING);

    createHostedOrderRequest.getPaymentSession().setActionType(ActionType.PAY);
    createHostedOrderRequest.getPaymentSession().setRecurrence(recurringSettings);
    createHostedOrderRequest.getPaymentSession().setAmount(10L);
    createHostedOrderRequest.getPaymentSession().setLanguage("ENG");
    createHostedOrderRequest.getPaymentSession().setResultUrl("https://www.example.com/payment/result");
    createHostedOrderRequest.getPaymentSession().setCancelUrl("https://www.example.com/payment/cancel");
    createHostedOrderRequest.getPaymentSession().setNotificationUrl("https://www.example.com/payment/notification");

    final ObjectMapper mapper = new ObjectMapper();

    final String requestBodyJson = mapper.writeValueAsString(createHostedOrderRequest);

    final RequestBody body = RequestBody.create(
        requestBodyJson,
        MediaType.parse("application/json; charset=utf-8"));

    Request.Builder requestBuilder = new Request.Builder();
    requestBuilder = requestBuilder.url(apiUrl + "/orders/hpp");
    requestBuilder = requestBuilder.header(
        "X-Api-Key",
        apiKey);
    requestBuilder = requestBuilder.header(
        "Correlation-Id",
        UUID.randomUUID().toString());
    requestBuilder = requestBuilder.post(body);

    final OkHttpClient client = new OkHttpClient();

    final Request request = requestBuilder.build();
    final Call call = client.newCall(request);
    final Response response = call.execute();
    final ResponseBody responseBody = response.body();
    final String responseString = responseBody.string();
    log.debug(
        "response body: {}",
        responseString);
    if (response.code() >= 300) {
      log.error(
          "invalid status code {} in response: {}",
          response.code(),
          responseString);
    } else {
      final CreateHostedOrderResponse responseInfo = mapper.readValue(
          responseString,
          CreateHostedOrderResponse.class);

      log.info("Hosted Page: " + responseInfo.getHostedPage());
      log.info("Security Token: " + responseInfo.getSecurityToken());
    }

  }

  @Data
  public static class CreateHostedOrderResponse {

    /**
     * URL of the hosted payment page. Redirect the payment flow to this URL.
     */
    @JsonProperty("hostedPage")
    private String hostedPage;

    /**
     * Token which may be used for validating the notifications related to this
     * payment
     *
     * For example 2f0ea5059b41414ca3744fe672327d85
     */
    @JsonProperty("securityToken")
    private String securityToken;

  }

  @Data
  public static class CreateHostedOrderRequest {

    @JsonProperty("order")
    private final Order order = new Order();

    @JsonProperty("paymentSession")
    private final PaymentSession paymentSession = new PaymentSession();

  }

  @Data
  public static class Order {

    @JsonProperty("orderId")
    private String orderId;

    @JsonProperty("amount")
    private Long amount;

    @JsonProperty("currency")
    private String currency;

  }

  public enum ActionType {

    PAY;

  }

  @Data
  public static class PaymentSession {

    @JsonProperty("amount")
    private Long amount;

    @JsonProperty("actionType")
    private ActionType actionType;

    @JsonProperty("recurrence")
    private RecurringSettings recurrence;

    @JsonProperty("language")
    private String language;

    @JsonProperty("resultUrl")
    private String resultUrl;

    @JsonProperty("cancelUrl")
    private String cancelUrl;

    @JsonProperty("notificationUrl")
    private String notificationUrl;

  }

  @Data
  public static class RecurringSettings {

    @JsonProperty("action")
    private RecurringAction action;

  }

  public enum RecurringAction {

    NO_RECURRING;

  }

}
    

        const https = require("https");
const url = require("url");

const apiUrl = "https://xpaysandbox.nexigroup.com/api/phoenix-0.0/psp/api/v1";
const apiKey = "API_KEY";
const orderId = "MY_ORDER_ID";

const data = JSON.stringify({
  order: {
    orderId: orderId,
    amount: 10,
    currency: "EUR",
  },
  paymentSession: {
    actionType: "PAY",
    amount: 10,
    recurrence: {
      action: "NO_RECURRING",
    },
    language: "ENG",
    resultUrl: "https://www.example.com/payment/result",
    cancelUrl: "https://www.example.com/payment/cancel",
    notificationUrl: "https://www.example.com/payment/notification",
  },
});

const targetUrl = url.parse(apiUrl + "/orders/hpp", true);

const options = {
  hostname: targetUrl.hostname,
  port: targetUrl.port,
  path: targetUrl.path,
  method: "POST",
  headers: {
    "X-Api-Key": apiKey,
    "Correlation-Id": apiKey,
    "Content-Type": "application/json",
    "Content-Length": data.length,
  },
};

const req = https.request(options, (res) => {
  if (res.statusCode != 200) {
    throw new Error(`invalid status code: ${res.statusCode}`);
  }
  res.on("data", (d) => {
    responseObject = JSON.parse(d);
    process.stdout.write("Hosted Page: " + responseObject.hostedPage + "\n");
    process.stdout.write(
      "Security Token: " + responseObject.securityToken + "\n"
    );
  });
});

req.on("error", (error) => {
  console.error(error);
});

req.write(data);
req.end();

    

        import requests
import uuid

apiUrl = "https://xpaysandbox.nexigroup.com/api/phoenix-0.0/psp/api/v1"
apiKey = "API_KEY"
orderId = "MY_ORDER_ID"

requestBodyData = {
    "order": {
        "orderId": orderId,
        "amount": 10,
        "currency": "EUR",
    },
    "paymentSession": {
        "amount": 10,
        "actionType": "PAY",
        "recurrence": {
            "action": "NO_RECURRING",
        },
        "language": "ENG",
        "resultUrl": "https://www.example.com/payment/result",
        "cancelUrl": "https://www.example.com/payment/cancel",
        "notificationUrl": "https://www.example.com/payment/notification",
    },
}

headers = {
    "X-Api-Key": apiKey,
    "Content-Type": "application/json",
    "Correlation-Id": str(uuid.uuid4()),
}
response = requests.post(apiUrl+"/orders/hpp",
                         json=requestBodyData, headers=headers)

response.raise_for_status()

responseData = response.json()

print("Hosted Page: " + responseData.get("hostedPage"))
print("Security Token: " + responseData.get("securityToken"))

    

        package main

import (
	"bytes"
	"context"
	"encoding/json"
	"fmt"
	"io/ioutil"
	"log"
	"net/http"

	"github.com/google/uuid"
)

type Recurrence struct {
	Action string `json:"action"`
}

type CreateHppRequestBodyType struct {
	Order          Order          `json:"order"`
	PaymentSession PaymentSession `json:"paymentSession"`
}

type Order struct {
	OrderID  string `json:"orderId"`
	Amount   uint64 `json:"amount"`
	Currency string `json:"currency"`
}
type PaymentSession struct {
	Amount          uint64     `json:"amount"`
	Recurrence      Recurrence `json:"recurrence"`
	ActionType      string     `json:"actionType"`
	Language        string     `json:"language"`
	ResultURL       string     `json:"resultUrl"`
	CancelURL       string     `json:"cancelUrl"`
	NotificationURL string     `json:"notificationUrl"`
}

type CreateHppResponseBodyType struct {
	HostedPage    string `json:"hostedPage"`
	SecurityToken string `json:"securityToken"`
}

func main() {
	ctx := context.TODO()
	apiUrl := "https://xpaysandbox.nexigroup.com/api/phoenix-0.0/psp/api/v1"
	apiKey := "API_KEY"
	orderId := "MY_ORDER_ID"

	requestBodyData := CreateHppRequestBodyType{
		Order: Order{
			OrderID:  orderId,
			Amount:   10,
			Currency: "EUR",
		},
		PaymentSession: PaymentSession{
			Amount:     10,
			ActionType: "PAY",
			Recurrence: Recurrence{
				Action: "NO_RECURRING",
			},
			Language:        "ENG",
			ResultURL:       "https://www.example.com/payment/result",
			CancelURL:       "https://www.example.com/payment/cancel",
			NotificationURL: "https://www.example.com/payment/notification",
		},
	}

	requestBodyJson, err := json.Marshal(requestBodyData)
	if err != nil {
		panic(err)
	}

	requestBodyBuffer := bytes.NewBuffer(requestBodyJson)

	req, err := http.NewRequestWithContext(ctx, http.MethodPost, apiUrl+"/orders/hpp", requestBodyBuffer)
	if err != nil {
		panic(err)
	}
	req.Header.Add("X-Api-Key", apiKey)
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Correlation-Id", uuid.New().String())

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	responseBody, err := ioutil.ReadAll(resp.Body)
	if err != nil {
		panic(err)
	}
	if resp.StatusCode != http.StatusOK {
		panic(fmt.Errorf("invalid status code from payment gateway: %s (%s)", resp.Status, string(responseBody)))
	}

	var responseBodyData CreateHppResponseBodyType
	if err := json.Unmarshal(responseBody, &responseBodyData); err != nil {
		panic(fmt.Errorf("error json unmarshal for %s: %w", string(responseBody), err))
	}

	log.Println("Hosted Page: ", responseBodyData.HostedPage)
	log.Println("Security Token: ", responseBodyData.SecurityToken)
}

    

        ﻿using System.Text;
using System.Text.Json;

internal class Program
{
    private static async Task Main(string[] args)
    {
        var apiUrl = "https://xpaysandbox.nexigroup.com/api/phoenix-0.0/psp/api/v1";
        var apiKey = "API_KEY";
        var orderId = "MY_ORDER_ID";

        var order = new RequestBodyOrder(orderId, 10, "EUR");
        var paymentSession = new RequestBodyPaymentSession(
            10,
            "PAY",
            new RequestBodyPaymentSessionRecurrence("NO_RECURRING"),
            "https://www.example.com/payment/result",
            "https://www.example.com/payment/cancel",
            "https://www.example.com/payment/notification",
            "ITA"
         );

        var newOrderRequest = new RequestBody(order, paymentSession);



        var json = JsonSerializer.Serialize(newOrderRequest);
        var data = new StringContent(json, Encoding.UTF8, "application/json");
        data.Headers.Add("X-Api-Key",
                apiKey);
        data.Headers.Add("Correlation-Id",
            Guid.NewGuid().ToString());

        using var client = new HttpClient();

        var response = await client.PostAsync(apiUrl + "/orders/hpp", data);

        if (!response.IsSuccessStatusCode)
        {
            Console.WriteLine("Error data: " + response);
        }
        else
        {
            var result = await response.Content.ReadAsStringAsync();

            var responseData = JsonSerializer.Deserialize<ResponseBody>(result);

            if (responseData == null)
            {
                throw new Exception("invalid response data");
            }

            Console.WriteLine("Hosted Page: " + responseData.hostedPage);
            Console.WriteLine("Security Token: " + responseData.securityToken);
        }

    }
}

record RequestBody(RequestBodyOrder order, RequestBodyPaymentSession paymentSession);
record RequestBodyOrder(string orderId, long amount, string currency);
record RequestBodyPaymentSession(long amount, string actionType, RequestBodyPaymentSessionRecurrence recurrence, string resultUrl, string cancelUrl, string notificationUrl, string language);
record RequestBodyPaymentSessionRecurrence(string action);
record ResponseBody(string hostedPage, string securityToken);

    

ATTENZIONE: l'esecuzione delle API deve avvenire rigorosamente lato server; implementarle lato client comporta notevoli rischi per la sicurezza.

Specifiche di notifica

Le notifiche di pagamento per servizi asincroni vengono inviate dal gateway XPay in modalità server to server con metodo POST, in formato JSON. Hanno il seguente user agent:

Apache-HttpClient/4.5.13 (Java/1.8.0_161)

La notifica è opzionale, viene inviata se si valorizza il parametro "notificationUrl" nelle API:

POST /orders/hpp (Hosted Payment Page)
POST/orders/paybylink (Pay-By-Link)
POST /orders/build (XPay Build)

Di seguito gli indirizzi IP del Gateway da cui vengono inviate le notifiche:

Dominio	Indirizzi IP
xpaysandbox.nexigroup.com	185.198.117.13 185.198.117.14 185.198.117.17 185.198.118.13 185.198.118.14 185.198.118.17
xpay.nexigroup.com	185.198.117.13 185.198.117.14 185.198.117.17 185.198.118.13 185.198.118.14 185.198.118.17

NOTE:

Si specifica che il flusso di pagamento del gateway XPay richiede obbligatoriamente che i redirect web e le fasi di autenticazione 3D Secure vengano eseguiti direttamente sul browser dell’utente finale, secondo il flusso previsto dalla documentazione ufficiale. Non è consentito né supportato l’utilizzo di soluzioni che intercettino, simulino o automatizzino i redirect e le chiamate HTTP del processo di autenticazione, né l’impiego di proxy applicativi per la gestione del flusso. Tali implementazioni risultano incompatibili con il modello di sicurezza del sistema e comportano il blocco delle transazioni. L’unica modalità di integrazione ammessa è quella basata su API e SDK ufficiali forniti dal gateway.
Per le soluzioni che utilizzano il parametro "resultUrl" in fase di avvio pagamento, e che prevedono quindi il reindirizzamento del cliente dalla pagina Nexi a quella dell'esercente, non esiste un indirizzo IP statico da cui Nexi esegue la chiamata. Il redirect avviene direttamente tramite il browser dell'utente finale, di conseguenza, le richieste verso i server dell'esercente proverranno direttamente dall'indirizzo IP del cliente finale.