Cloud-based communication to the terminal

Learn about communication between the POS and terminal over the internet.

The cloud Terminal API architecture allows the terminal and POS to communicate over the internet, no library required.  It provides endpoints to initiate payments on your payment terminals through our platform. Adyen manages the connection between the platform and the terminal. The request is forwarded to the correct terminal based on the POIID (unique terminal ID) in the request message.


  • Basic HTTP authentication.
  • A web server for event and display notifications.


The test endpoints are available through the following service:

Endpoint Communication type Synchronous Asynchronous

The live endpoints are available through the following service:

Endpoint Communication type Synchronous Asynchronous

Create and send an API request

  1. Retrieve your API key from the Customer Area. For more information, see How to get the checkout API key
  2. Create a POST request in JSON Format.
  3. Set the content-type to JSON in the header.
  4. Set the X-api-key to the API key you retrieved in step 1.
  5. Send the POST request to the endpoints outlined below.

 curl -H "content-type: application/json" -H "x-api-key:<INSERT YOUR CHECKOUT API KEY>" -X POST --data-binary '{
	"SaleToPOIRequest": {
		"MessageHeader": {
			"ProtocolVersion": "3.0",
			"MessageClass": "Service",
			"MessageCategory": "Payment",
			"MessageType": "Request",
			"ServiceID": "0207111104",
			"SaleID": "POSSystemID12345",
			"POIID": "V400m-324688179"
		"PaymentRequest": {
			"SaleData": {
				"SaleTransactionID": {
					"TransactionID": "27908",
					"TimeStamp": "2018-02-07T10:11:04+00:00"
			"PaymentTransaction": {
				"AmountsReq": {
					"Currency": "EUR",
					"RequestedAmount": 10.99
}' --url

Architecture diagram

Communication Types


Synchronous communication requires a HTTPS client with an extended time-out of more than 2 minutes. During this time the connection is kept alive and a synchronous response will follow.

Set up a Sale System HTTPS server to receive display and event notifications.

If during the transaction the communication has been broken for any reason, the transaction status can be retrieved by checking the status of the transaction.  


Asynchronous communication with the Terminal Cloud API requires a HTTPS Server to receive event notifications. The request is automatically accepted and forwarded to the POI. The result of the Terminal request is then relayed to the notification server that is configured with the Sale System. Display notifications are also sent to this server.


Payment notifications from the Asynchronous Terminal Cloud API are not guaranteed to be sent. Set up regular notifications to guarantee delivery of payment information notifications. For more information, see Notifications

Alternatively, query the transaction status when you receive no response. The terminal must be connected to the Adyen payments platform to successfully query the transaction status. For more information, see Recover a payment.