Adyen

Adyen Terminal API

The Adyen [Terminal API](https://docs.adyen.com/point-of-sale/design-your-integration/terminal-api/) lets you make payments, issue refunds, collect shopper…

Payments#openapi

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

Overview

The Adyen Terminal API lets you make payments, issue refunds, collect shopper information, and perform other shopper-device interactions using a payment terminal supplied by Adyen. The Terminal API is also used for transactions in Adyen Mobile solutions.

API structure

The architecture of Terminal API is determined by the nexo Sale to POI Protocol Specifications.

A Terminal API request is a JSON message consisting of a SaleToPOIRequest object with:

  • MessageHeader: identifies the type of transaction, the terminal or Mobile SDK instance being used, and unique transaction identifiers.
  • Request body: content depending on the type of transaction or operation, for example, a PaymentRequest.

A Terminal API response is a JSON message consisting of a SaletoPOIResponsewith:

  • MessageHeader: echoes the values provided in the request, except for MessageType, which is always Response.
  • Response body: content depending on the type of transaction or operation, for example, a PaymentResponse.

Sending and receiving

In an integration with Ayden payment terminals, you can send and receive Terminal API messages in the following ways:

  • Local communications: using your local network, your POS system sends the request directly to the IP address of the terminal, and receives the result synchronously.
  • Cloud communications: using the internet to access the cloud, your POS system sends the request to an Adyen endpoint, and Adyen forwards the request to the terminal. Your POS system either keeps the connection open and receives the response synchronously, or closes the connection and receives the response asynchronously in an event notification.

Using local communications

To learn how to set up and protect local communications, refer to Building a local integration.

Endpoints for cloud communications

If your POS system is cloud-based, you POST your Terminal API requests to a Cloud device API endpoint, using path and query parameters to identify the device that you want to send the request to.

  • If your POS system is designed to keep the connection open to wait for the response, use the endpoints ending in /sync.
  • If your POS system is designed to close the connection so that it can initiate a new request, use the endpoints ending in /async.

Test endpoints

  • https://device-api-test.adyen.com/v1/merchants/{merchantAccount}/devices/{deviceId}/sync
  • https://device-api-test.adyen.com/v1/merchants/{merchantAccount}/devices/{deviceId}/async

Live endpoints

The live endpoints differ per region. In addition to using a regional endpoint, you must select the geographically closest data center in your live Customer Area.

Australia

  • https://device-api-live-au.adyen.com/v1/merchants/{merchantId}/devices/{deviceId}/sync
  • https://device-api-live-au.adyen.com/v1/merchants/{merchantId}/devices/{deviceId}/async

East Asia

  • https://device-api-live-apse.adyen.com/v1/merchants/{merchantId}/devices/{deviceId}/sync
  • https://device-api-live-apse.adyen.com/v1/merchants/{merchantId}/devices/{deviceId}/async

Europe

  • https://device-api-live.adyen.com/v1/merchants/{merchantId}/devices/{deviceId}/sync
  • https://device-api-live.adyen.com/v1/merchants/{merchantId}/devices/{deviceId}/async

United States

  • https://device-api-live-us.adyen.com/v1/merchants/{merchantId}/devices/{deviceId}/sync
  • https://device-api-live-us.adyen.com/v1/merchants/{merchantId}/devices/{deviceId}/async

Old endpoints

If you currently use endpoints with a base URL that includes terminal-api, we strongly recommend migrating to Cloud device API endpoints, for the following reasons:

  • When using Cloud device API, the API logs in the Customer Area include the Terminal API requests and responses.
  • Cloud device API endpoints offer technical advantages such as versioning and better routing.
  • Future enhancements and features will be based on Cloud device API.

There will be no future development on the old endpoints, but we continue to support them.

Old test endpoints:

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

Old live endpoints Australia:

  • https://terminal-api-live-au.adyen.com/sync and https://terminal-api-live-au.adyen.com/async

**Old live…

Endpoints 17

  • POSTLogin Request/loginIt conveys information related to the session (period between a Login and the following Logout) to process. Content of the LoginRequest message.
  • POSTLogout Request/logoutEmpty. Content of the Logout Request message.
  • POSTEnableService Request/enableserviceIt conveys the services that will be enabled for the POI Terminal without the request of the Sale System, and a possible invitation for the Customer to start…
  • POSTAdmin Request/adminEmpty. Content of the Custom Admin Request message.
  • POSTPayment Request/paymentRequest sent to terminal to initiate payment. It conveys Information related to the Payment transaction to process. Content of the PaymentRequest message.
  • POSTCardAcquisition Request/cardacquisitionIt conveys Information related to the payment and loyalty cards to read and analyse. This message pair is usually followed by a message pair (e.g. payment or…
  • POSTStoredValue Request/storedvalueIt conveys Information related to the Stored Value transaction to process. Content of the Stored Value Request message.
  • POSTReversal Request/reversalIt conveys Information related to the reversal of a previous payment or a loyalty transaction. Content of the Reversal Request message.
  • POSTReconciliation Request/reconciliationContent of the Reconciliation Request message. It conveys Information related to the Reconciliation requested by the Sale System.
  • POSTGetTotals Request/gettotalsIt conveys information from the Sale System related to the scope and the format of the totals to be computed by the POI System. Content of the Get Totals…
  • POSTBalanceInquiry Request/balanceinquiryIt conveys Information related to the account for which a Balance Inquiry is requested. Content of the Balance Inquiry Request message.
  • POSTTransactionStatus Request/transactionstatusContent of the TransactionStatus Request message. It conveys Information requested for status of the last or current Payment, Loyalty or Reversal transaction.
  • POSTAbort Request/abortBody of the Abort Request message. It conveys Information requested for identification of the message request carrying the transaction to abort. A message to…
  • POSTDiagnosis Request/diagnosisIt conveys Information related to the target POI for which the diagnosis is requested. Content of the Diagnosis Request message.
  • POSTDisplay Request/displayIt conveys the data to display and the way to process the display. It contains the complete content to display. It might contain an operation (the…
  • POSTInput Request/inputContent of the InputRequest message. It conveys the data to display and how to process it. In addition to the display on the Input Device, it might contain an…
  • POSTPrint Request/printContent of the Print Request message. It conveys the complete data to print and how to process the print.

API details

Base URL
https://device-api-test.adyen.com/v1/merchants/{merchantAccount}/devices/{deviceId}/sync
https://device-api-test.adyen.com/v1/merchants/{merchantAccount}/devices/{deviceId}/async
Authentication
An API key in the X-API-Key header
HTTP Basic authentication (username and password)
Operations
17 operations on 17 pathsPOST 17
Response formats
application/json
Description format
OpenAPI 3.1.0, API version 1

How to test the Adyen Terminal API in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the Adyen Terminal API collection, without the publisher's secrets.
  3. Add your credentialsThis API uses an API key in the X-API-Key header. Add yours in the collection's variables or an environment; the requests already reference it.
  4. Send a requestPick an endpoint, for example “Login Request” (POST /login), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the Adyen Terminal API?

The Adyen [Terminal API](https://docs.adyen.com/point-of-sale/design-your-integration/terminal-api/) lets you make payments, issue refunds, collect shopper… It is listed under Payments and has 17 endpoints.

Who publishes the Adyen Terminal API?

It is listed from Adyen's public API description (an OpenAPI document), not published by Adyen on Swastik Codes. Anyone who controls adyen.com can claim the profile by adding a DNS TXT record.

What is the base URL of the Adyen Terminal API?

Its description lists 2 base URLs: https://device-api-test.adyen.com/v1/merchants/{merchantAccount}/devices/{deviceId}/sync, https://device-api-test.adyen.com/v1/merchants/{merchantAccount}/devices/{deviceId}/async. The first is the usual one; the others are typically sandbox or regional servers.

How do I authenticate with the Adyen Terminal API?

It accepts 2 methods: an API key in the X-API-Key header; HTTP Basic authentication (username and password).

How many endpoints does the Adyen Terminal API have?

17 operations on 17 paths (17 POST).

Is forking the Adyen Terminal API free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.