Adyen Terminal API

Click to copy

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.

Authentication and endpoints

Authentication and endpoints depend on whether you are using a cloud or a local Terminal API integration.

Cloud

Each request to the cloud Terminal API must be signed with an API key. Generate your API Key in the Customer Area and set this key to the X-API-Key header value.

The cloud Terminal API endpoint you need to use depends on whether your integration will receive transaction results synchronously or asynchronously:

  • Synchronous: https://terminal-api-test.adyen.com/sync
  • Asynchronous: https://terminal-api-test.adyen.com/async

When you are ready to go live, you need to generate a new web service user credential and switch to one of the live endpoints.

Local

If your integration uses local communications, API requests are made from a POS app directly to a terminal's IP address. To learn how to set up and protect local communications, refer to Building a local integration.

API structure

Terminal API communicates with the terminal using JSON messages. All requests and responses have the following structure:

  • MessageHeader: identifies the type of transaction, the terminal being used, and unique transaction identifiers.
  • Request 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.

Requests

Each Terminal API request you make is contained in a SaletoPOIRequest object and needs to have the following objects:

  • MessageHeader: for each request you need to include this object and specify the required parameters.
  • Request body: the name and structure of this object depends on the type of request. You can use this specification to create the structure of the request body. For example, to make a payment you need to include a PaymentRequest object and the MessageHeader inside the SaletoPOIRequest object.

Responses

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

  • MessageHeader: this object echoes the values you provided in the request. The only exception is the MessageType, which is always Response.
  • Response body: the values you receive in the response body depend on the type of transaction request you made. For example, when making a PaymentRequest you would receive a PaymentResponse as the response body.

Below, you can find the list of available Terminal API requests with the structure of the request/response body parameters: