Getting started

We find that the best way to get started with the Nexi POS API is to jump in and try it out with a simulated payment terminal.

This page will give you three options where to start your integration journey:

Command line interface (CLI) – for those who want to instantly try it out in their terminal.
Postman – for those who prefer a browser based interface and want to explore the API interactively.
Code examples – for those who want to write real code and try out the API in their own environment.

Command line interface (CLI)

Creating a simulator

The first step is creating your own personal simulator for playing around with the API without any setup or physical hardware.

Create a simulator

Creating a simulator will give you a unique terminal ID, username, and password. These will be displayed only once, so make sure to copy them somewhere safe. You will need them to keep using your simulator. Although you can always create a new simulator if you want to start fresh.

Making a purchase

You can make a purchase by doing a single REST API request to the /transaction/purchase endpoint. The request will look like this:

cURL
NodeJS
Python
Java
curl -H 'Content-Type: application/json' \
  --data '{
    "terminal_id": "t-9999999999",
    "external_id": "1",
    "currency": "EUR",
    "requested_amount": 100
  }' \
  -u npi_XXXXXXXXXXXXXXXXXXXXXXXXXX:nps_XXXXXXXXXXXXXXXXXXXXXXXXXX \
  https://api.npay.eu/pos/v0/transaction/purchase | jq .
const response = await fetch("https://api.npay.eu/pos/v0/transaction/purchase", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Basic ${btoa("npi_XXXXXXXXXXXXXXXXXXXXXXXXXX:nps_XXXXXXXXXXXXXXXXXXXXXXXXXX")}`,
  },
  body: JSON.stringify({
    terminal_id: "t-9999999999",
    external_id: "1",
    currency: "EUR",
    requested_amount: 100,
  }),
});

const data = await response.json();
console.log(data);
import requests
from requests.auth import HTTPBasicAuth

url = "https://api.npay.eu/pos/v0/transaction/purchase"
payload = {
    "terminal_id": "t-9999999999",
    "external_id": "1",
    "currency": "EUR",
    "requested_amount": 100,
}

response = requests.post(
    url,
    json=payload,
    auth=HTTPBasicAuth(
        "npi_XXXXXXXXXXXXXXXXXXXXXXXXXX",
        "nps_XXXXXXXXXXXXXXXXXXXXXXXXXX"
    )
)

print(response.json())
import java.net.http.*;
import java.net.URI;
import java.util.Base64;

public class PurchaseExample {
    public static void main(String[] args) throws Exception {
        String credentials = "npi_XXXXXXXXXXXXXXXXXXXXXXXXXX:nps_XXXXXXXXXXXXXXXXXXXXXXXXXX";
        String auth = Base64.getEncoder().encodeToString(credentials.getBytes());
        
        String payload = """
            {
                "terminal_id": "t-9999999999",
                "external_id": "1",
                "currency": "EUR",
                "requested_amount": 100
            }
            """;
        
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.npay.eu/pos/v0/transaction/purchase"))
            .header("Content-Type", "application/json")
            .header("Authorization", "Basic " + auth)
            .POST(HttpRequest.BodyPublishers.ofString(payload))
            .build();
        
        HttpClient client = HttpClient.newHttpClient();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        
        System.out.println(response.body());
    }
}

Go ahead and run the command in your terminal! It should take a few seconds to process the request, as it is simulating the processing time of a real payment terminal. You should receive a response with all the transaction details you need about the purchase that was just performed. The transaction will be in the AWAITING_CONFIRM state, meaning that the terminal has processed the payment and reserved the money in the customer’s account, but you still need to confirm the transaction to finalize it.

If for some reason the REST request would fail, like for example if there are network issues, you can simply resend the same request until you get a successful response. The API is idempotent and will not create duplicate transactions if you resend the same request with the same external_id and terminal_id.

Also, if the purchase takes more than 25 seconds, the API will return the transaction in PROCESSING state, meaning that the terminal is still processing the transaction and you should wait for it to complete. In this case as well, you can simply resend the same request until the transaction is no longer in PROCESSING state.

Confirming a purchase

After the transaction has completed successfully, and ýou have marked in your ECR database that the transaction was successful, as well as printed a receipt for the customer, you need to confirm the transaction to finalize it. This is done by sending a request to the /transaction/confirm endpoint with the same terminal_id and external_id that you used in the purchase request. The request will look like this:

cURL
NodeJS
Python
Java
curl -H 'Content-Type: application/json' \
  --data '{
    "terminal_id": "t-9999999999",
    "external_id": "1",
    "result_code": "SUCCESS"
  }' \
  -u npi_XXXXXXXXXXXXXXXXXXXXXXXXXX:nps_XXXXXXXXXXXXXXXXXXXXXXXXXX \
  https://api.npay.eu/pos/v0/transaction/confirm | jq .
const response = await fetch("https://api.npay.eu/pos/v0/transaction/confirm", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Basic ${btoa("npi_XXXXXXXXXXXXXXXXXXXXXXXXXX:nps_XXXXXXXXXXXXXXXXXXXXXXXXXX")}`,
  },
  body: JSON.stringify({
    terminal_id: "t-9999999999",
    external_id: "1",
    result_code: "SUCCESS",
  }),
});

const data = await response.json();
console.log(data);
import requests
from requests.auth import HTTPBasicAuth

url = "https://api.npay.eu/pos/v0/transaction/confirm"
payload = {
    "terminal_id": "t-9999999999",
    "external_id": "1",
    "result_code": "SUCCESS",
}

response = requests.post(
    url,
    json=payload,
    auth=HTTPBasicAuth(
        "npi_XXXXXXXXXXXXXXXXXXXXXXXXXX",
        "nps_XXXXXXXXXXXXXXXXXXXXXXXXXX"
    )
)

print(response.json())
import java.net.http.*;
import java.net.URI;
import java.util.Base64;

public class ConfirmExample {
    public static void main(String[] args) throws Exception {
        String credentials = "npi_XXXXXXXXXXXXXXXXXXXXXXXXXX:nps_XXXXXXXXXXXXXXXXXXXXXXXXXX";
        String auth = Base64.getEncoder().encodeToString(credentials.getBytes());
        
        String payload = """
            {
                "terminal_id": "t-9999999999",
                "external_id": "1",
                "result_code": "SUCCESS"
            }
            """;
        
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.npay.eu/pos/v0/transaction/confirm"))
            .header("Content-Type", "application/json")
            .header("Authorization", "Basic " + auth)
            .POST(HttpRequest.BodyPublishers.ofString(payload))
            .build();
        
        HttpClient client = HttpClient.newHttpClient();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        
        System.out.println(response.body());
    }
}

This request will confirm the transaction and mark it as successful. The response will contain the updated transaction details, including the final status of the transaction. The same request can also be used to mark the transaction as failed, by changing the result_code to something else than SUCCESS. This is useful if the customer decides to cancel the transaction or if there was an error during the transaction processing.

Proper integration

Now you are ready to build the proper integration with the Nexi POS API. You should read transaction flow to understand exactly how the transaction life cycle works.

Postman

You can jump right into the Nexi POS API Postman collections and start exploring the API interactively. The collections include all endpoints and example requests/responses, so you can quickly get a feel for how the API works.

Code examples

Code examples will be added soon. Please check back later.