This page explains the components of an in-person integration and the two connection modes Adyen's Terminal API supports: cloud communications and local communications.
The components
Your POS app: the cash register software that starts a transaction and shows the result.
The Adyen payment terminal: the device the shopper pays on. It reads the card and gets the payment authorized.
The Adyen platform: processes the transaction, applies risk and acquiring, and records it.
Your server and webhooks: Adyen sends webhooks to your endpoint with the authoritative final outcome of a transaction. Treat the webhook, not the synchronous response alone, as the source of truth. See Webhooks.
Your POS app communicates using Terminal API, which exchanges JSON messages and does not require client libraries.
Cloud vs local communications
Before you build, you choose how your POS app connects to the terminal and the Adyen platform. This is the integration architecture.
Cloud communications (recommended)
Your POS app sends the Terminal API request to the Adyen platform over the internet, and Adyen relays it to the terminal. This is the simplest and most flexible option, and Valpay recommends it for most integrations.
Easiest to implement: your POS app calls a single Adyen endpoint, and Adyen manages the connection to the terminal for you.
No in-store network security work: you do not install certificates or encrypt messages on the local network yourself, because the traffic runs over Adyen's secured platform.
Location-independent: terminals only need an internet connection, so they do not have to be on the same local network as your POS app. This makes it easy to add stores and devices.
Less network administration: use dynamic IP addresses, with no DHCP reservation or static IPs to maintain.
Flexible results: you can receive the outcome synchronously or asynchronously, depending on how you build the integration.
The main trade-off is that cloud does not support every advanced use case. For those specific cases, consider local communications.
Local communications
Your POS app sends the Terminal API request directly to the terminal's IP address on your local network. The shopper completes the transaction on the terminal, and you receive the result synchronously.
Can be more robust.
Requires extra effort to secure communication on the local network: you add Adyen's certificate to your POS app and encrypt your messages.
Should use DHCP reservation or manually configured static IP addresses.
Choosing between them
Start with cloud communications unless you have a specific requirement that only local meets. Local adds network administration and security work on your side, and Adyen does not provide support for in-store network problems, so choose it only when you need it. If you do consider local, confirm that whoever manages the in-store network has the expertise to configure it for payment terminals and to resolve network issues. Adyen also provides an interactive questionnaire on its "Choose an integration architecture" page to recommend an approach for your situation.
What stays the same
Whichever mode you choose, you use the same Terminal API message structure, terminals are assigned to a store, and the final outcome is confirmed by webhook. See Terminal API Payment Flow for the request and response details.