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…
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 forMessageType, 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}/synchttps://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}/synchttps://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}/synchttps://device-api-live-apse.adyen.com/v1/merchants/{merchantId}/devices/{deviceId}/async
Europe
https://device-api-live.adyen.com/v1/merchants/{merchantId}/devices/{deviceId}/synchttps://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}/synchttps://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/syncandhttps://terminal-api-test.adyen.com/async
Old live endpoints Australia:
https://terminal-api-live-au.adyen.com/syncandhttps://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}/synchttps://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 - Links
- OpenAPI document
- Listed from
- Adyen's published OpenAPI description (Adyen/adyen-openapi) (MIT)
How to test the Adyen Terminal API in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the Adyen Terminal API collection, without the publisher's secrets.
- 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.
- 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.