Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Terminal API

Learn about our Terminal API, including the endpoints and structure.

We don't recommend using Terminal API in combination with a classic POS library. In addition, you can't use Terminal API with older eVo terminal models. Refer to the overview of terminals that support Terminal API.

Our Terminal API is based on the nexo Retailer Protocol.

The Adyen Terminal API lets you make payments, issue refunds, collect shopper information, and perform other shopper-terminal interactions using a payment terminal supplied by Adyen.

Before you make any point-of-sale payments, it is important to understand how Terminal API works and how requests and responses are structured.

Enable Terminal API

Before you can use Terminal API in your test environment, you need to enable it:

  1. Log in to your test Customer Area.
  2. Go to Point of sale > Terminal settings and select Integrations.
  3. Select the option to Enable Terminal API.
  4. Select Save.

When you switch to your live environment, follow the same steps in your live Customer Area.

Use the correct endpoint

The endpoints you need to use, and how you authenticate requests depends on how your integration connects to the Adyen payments platform:

Local communications

If your integration uses local communications, API requests are made from a POS app directly to a terminal's IP address. The terminal listens for POST requests to /nexo on port 8443. For example, if your terminal has the IP address you would make API requests to:

If your integration uses Android devices and the POS app is installed on the terminal itself, you can send POST requests to either localhost or from that app.

Alternatively, if you assign a hostname to your terminal, you can make requests to the resolvable hostname of the terminal.

You should either use DHCP reservation for the terminal IP addresses, or manually configure static IP addresses. This helps to prevent connection issues when the terminal or your network reboots.

To protect local communications, you need to add Adyen's certificate to your POS app, and encrypt your messages.

Cloud communications

If your integration uses cloud communications, your POS app makes API requests to the Adyen payments platform. Our platform then forwards the request to the terminal.

The endpoint you need to use depends on two things:

  • Whether your integration will receive transaction results synchronously or asynchronously.
  • Whether you are making test transactions or live transactions.
Test endpoints - for all test transactions
Synchronous result:
Asynchronous result:

When you're ready to go live, you need to switch to a live transaction endpoint that is geographically closest to the location of your store.

Live endpoints - Europe
Synchronous result:
Asynchronous result:
Live endpoints - Australia
Synchronous result:
Asynchronous result:
Live endpoints - US
Synchronous result:
Asynchronous result:

Get your API key

You need to include an Adyen API key in the request header for:

To get an API key for your test environment:

  1. Log in to your Customer Area.
  2. Go to Developers > API credentials, and select the API credential username for your integration, for example ws@Company.[YourCompanyAccount].
  3. Under Server settings > Authentication select the API key tab.
  4. Select Generate API key.
  5. Select the copy icon and store your API key securely in your system.
  6. Select Save changes.

When you switch to your live environment, follow the same steps in your live Customer Area.

Add the value of the API key to the request header using the key: x-API-key

API structure

Our Terminal API communicates with the terminal using JSON messages. All requests and responses have the following message header-body structure:

  • Message header: identifies the type of transaction, the terminal being used, and unique transaction identifiers.
  • Body: a request or response object, depending on the type of transaction. For example, when you make a payment request this is a PaymentRequest object, and when you receive a payment response this is a PaymentResponse object.

The message header and body of Terminal API requests and responses are described in more detail below.


Each Terminal API request you make is contained in a SaletoPOIRequest object. In this, you need to provide a:

  • MessageHeader object.
  • Request body object corresponding to the type of transaction. For example, this is a PaymentRequest object when you are making a payment, or an InputRequest object when you are requesting shopper input.

Request MessageHeader

In each request MessageHeader, specify the following:

Name Required Type Description
ProtocolVersion -white_check_mark- String

Version of Adyen's Terminal API.

The current version is 3.0

MessageClass -white_check_mark- Enum This is almost always Service, but it can also be Device or Event. We will specify which MessageClass is required throughout our documentation.
MessageCategory -white_check_mark- Enum The type of transaction. For example, Payment for a payment request. We will specify which MessageCategory is required throughout our documentation.
MessageType -white_check_mark- Enum This is always Request.
ServiceID -white_check_mark- String Your unique ID for this request, consisting of 1-10 alphanumeric characters. Must be unique within the last 48 hours for the terminal (POIID) being used.
SaleID -white_check_mark- String Your unique ID for the system where you send this request from.
POIID -white_check_mark- String

The unique ID of the terminal that you send this request to. Format: [device model]-[serial number]. For example, P400-123456789.

You can find the device model and serial number in the Device info screen on the terminal, and in your Customer Area under Point of sale > Terminals. The serial number (or s/n) is also printed on the underside of the terminal.

The example below shows the header for making a payment.


Request body

The values you need to include in the request body depends on the type of transaction you are making. We provide examples and reference information for each transaction type throughout our point-of-sale documentation.


Each terminal API response you receive is contained in a SaleToPOIResponse object, and includes a:

If you're using a cloud integration that receives results asynchronously, you will only receive an ok response from the Terminal API. The MessageHeader and response body are sent in an event notification instead.

Response MessageHeader

The MessageHeader you receive in the response echoes the values you provided in the request. The only exception is the MessageType, which is Response.

The following example shows the header you would receive in response to the example payment request provided above.


Response body

The values you receive in the response body depends on the type of transaction request you made. We provide examples and reference information for each transaction type throughout our point-of-sale documentation.

The response body will often include a unique transaction identifier, and data you can use to generate your receipts.

Transaction identifier

Every API request that creates a transaction or interacts with your money flow (such as a payment or refund) returns a unique transaction identifier in the POITransactionID.TransactionID:

This identifier contains two values, separated by a dot:

  • Tender reference: a unique value generated by the terminal for the transaction.
  • PSP reference: a unique alphanumeric value generated by the Adyen payments platform for the transaction.

    If you're using Adyen for online payments or Unified Commerce, the PSP reference is the equivalent of the pspReference that you receive for transactions made online.

You should store each transaction identifier you receive, as you will need it to:

  • Make a refund.
  • Make a payment with acquired card details.
  • Identify the transaction in your Customer Area, or in reports generated by Adyen.

Transaction identifiers for offline payments

If your integration uses local communications, your terminals will be able to make Offline EMV and store-and-forward transactions. When you experience a network issue, an Approved payment will only generate a transaction identifier with the tender reference:

Once the terminal is able to connect to the internet again, the Adyen payments platform will process the payment and generate an alphanumeric PSP reference. The PSP reference and tender reference can be found in your Customer Area, and in reports generated by Adyen.

Receipt data

When you make a transaction such as a payment, the payment result contains a PaymentReceipt object. You can add the key-value pairs from this object to the receipt that you print, display, or email to your shopper.

For more information, see our receipts documentation.

Next steps