API > Service usage specifications

Service usage specifications

The APIs exposed by XPay support the HTTP protocol with channel encryption and use the JSON format for the request and response.

Here are the technical details for invoking the services.

Request specifications

Protocol	HTTPS
Method	GET/POST
Content-Type	application/json
Production url	https://xpay.nexigroup.com/api/phoenix-0.0/psp/api/v1/
Test url	https://xpaysandbox.nexigroup.com/api/phoenix-0.0/psp/api/v1/

We recommend avoiding direct requests and/or adding the IP addresses of endpoint DNS resolution to firewall authorization lists. However, if whitelists have been configured, please update them with the following production addresses:

185.198.117.102
185.198.118.102

The TLSv1.2 and TLSv1.3 protocols are supported. Below are the ciphers:

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

Below are the details of the certificate installed in the test and production environment:

ROOT CERTIFICATE	GlobalSign Root CA - R3
Serial Number	04:00:00:00:00:01:21:58:53:08:A2
CA Intermediate	GlobalSign RSA Organization Validation CA - 2018
Serial Number	01:EE:5F:22:1D:FC:62:3B:D4:33:3A:85:57

If it is necessary to download the certificates, please refer to the web pages of the Certification Authority (CA):

Here are some examples of requests to XPay services in different programming languages:

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

    

ATTENTION: API execution must strictly occur on the server side; implementing them on the client side poses significant security risks.

Specifications for outcome notification

Payment notifications for asynchronous services are sent by the XPay gateway in server-to-server mode with the POST method, in JSON format. They have the following user agent:

Apache-HttpClient/4.5.13 (Java/1.8.0_161)

The notification is optional, it is sent if the "notificationUrl" parameter is set in the APIs:

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

Below are the IP addresses of the Gateway from which notifications are sent:

Domain	IP Addresses
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

NOTES:

It is specified that the XPay payment gateway flow requires that web redirects and 3D Secure authentication steps be executed directly in the end user’s browser, in accordance with the flow defined in the official documentation. The use of solutions that intercept, simulate, or automate the redirects and HTTP requests of the authentication process is neither supported nor permitted, nor is the use of application-level proxies to manage the flow. Such implementations are incompatible with the system’s security model and result in transaction blocking. The only approved integration method is based on the official APIs and SDKs provided by the gateway.
For solutions that use the "resultUrl" parameter during the payment initiation phase, which involve redirecting the end customer from the Nexi page back to the merchant's page, there is no static IP address from which Nexi performs the call. The redirect occurs directly through the end user's browser; consequently, requests to the merchant's servers will originate directly from the end customer's IP address.