Event notifications

Receive event notifications on your cash register.

From time to time, one of your Adyen terminals will encounter an issue, or need to perform maintenance. When this happens, the terminal generates an event notification. You can optionally present this on your cash register to inform your store staff of the terminal's availability and state.

Here we describe how you expose an endpoint on your server, and set up event notifications. Your server will then receive webhooks that include an EventToNotify value. This indicates the state of the terminal, and can be used to present a message on your cash register.

We also provide a list of possible EventToNotify values, and examples of each.

Set up event notifications

Step 1: Expose an endpoint on your server

Event notifications are sent as HTTP callbacks (webhooks) to an endpoint on your server. To receive notifications, make sure you have a server with:

An endpoint that can receive a JSON call.
An open TCP port for HTTP traffic (443, 8443, or 8843).

For testing, you can also use an HTTP port (80, 8080, or 8888).
A username and password for basic authentication.

Step 2: Set up notifications in your Customer Area

The next step is to enter your server's details in your Customer Area, and select additional information that you want to receive in notifications. You can configure notifications either at company or merchant account level.

Log in to your Customer Area. To configure notifications at merchant level, switch to your merchant account.
Go to Account > Server communication.
Next to Terminal API Notification, select Add.
In the Transport section:
- Enter your server's URL. Make sure that this is a public URL.
- Enter your server's SSL (TLS) Version.
- Select the Active checkbox.
In the Authentication section, enter your server's username and password for basic authentication.
We include these details in the header of the notification request to authenticate with your server.
In the Additional settings section, turn on Event notification.
Select Test Configuration and verify that the notification was received at your endpoint.
If your endpoint received the notification, select Save Configuration.

Event notifications will now be sent to the endpoint you specified.

Event notification types

Each notification contains an EventToNotify value. You can use this to present a message on your cash register informing your store staff of the terminal's state.

Event	Description
`Shutdown`	The terminal is shutting down.
`BeginMaintenance`	Terminal maintenance is starting.
`EndMaintenance`	Terminal maintenance is finishing.
`OutOfOrder`	The terminal is out of order.
`Initialised`	The terminal has been initialised and is ready for transactions.
`Reject`	A request was rejected. An explanation of the error should be provided in the `EventDetails` element.
`SaleWakeUp`	The terminal is initiating a payment request. The `EventDetails` element contains the reference number that was entered on the terminal.

Examples of event notifications are provided below.

Examples

Shutdown

{
   "SaleToPOIRequest":{
      "EventNotification":{
         "EventDetails":"newstate=IDLE&oldstate=START",
         "EventToNotify":"Shutdown",
         "TimeStamp":"2019-08-07T10:16:10.000Z"
      },
      "MessageHeader":{
         "SaleID":"POSSystemID12345",
         "ProtocolVersion":"3.0",
         "MessageType":"Notification",
         "POIID":"V400m-324688179",
         "MessageClass":"Event",
         "MessageCategory":"Event",
         "DeviceID":"1517998561"
      }
   }
}

BeginMaintenance

{
   "SaleToPOIRequest":{
      "EventNotification":{
         "EventDetails":"newstate=IDLE&oldstate=START",
         "EventToNotify":"BeginMaintenance",
         "TimeStamp":"2019-08-07T10:16:10.000Z"
      },
      "MessageHeader":{
         "SaleID":"POSSystemID12345",
         "ProtocolVersion":"3.0",
         "MessageType":"Notification",
         "POIID":"V400m-324688179",
         "MessageClass":"Event",
         "MessageCategory":"Event",
         "DeviceID":"1517998562"
      }
   }
}

EndMaintenance

{
   "SaleToPOIRequest":{
      "EventNotification":{
         "EventDetails":"newstate=IDLE&oldstate=START",
         "EventToNotify":"EndMaintenance",
         "TimeStamp":"2019-08-07T10:16:10.000Z"
      },
      "MessageHeader":{
         "SaleID":"POSSystemID12345",
         "ProtocolVersion":"3.0",
         "MessageType":"Notification",
         "POIID":"V400m-324688179",
         "MessageClass":"Event",
         "MessageCategory":"Event",
         "DeviceID":"1517998561"
      }
   }
}

OutOfOrder

{
   "SaleToPOIRequest":{
      "EventNotification":{
         "EventDetails":"newstate=IDLE&oldstate=START",
         "EventToNotify":"OutOfOrder",
         "TimeStamp":"2019-08-07T10:16:10.000Z"
      },
      "MessageHeader":{
         "SaleID":"POSSystemID12345",
         "ProtocolVersion":"3.0",
         "MessageType":"Notification",
         "POIID":"V400m-324688179",
         "MessageClass":"Event",
         "MessageCategory":"Event",
         "DeviceID":"1517998563"
      }
   }
}

Initialised

{
   "SaleToPOIRequest":{
      "EventNotification":{
         "EventDetails":"newstate=IDLE&oldstate=START",
         "EventToNotify":"Initialised",
         "TimeStamp":"2019-08-07T10:16:10.000Z"
      },
      "MessageHeader":{
         "SaleID":"POSSystemID12345",
         "ProtocolVersion":"3.0",
         "MessageType":"Notification",
         "POIID":"V400m-324688179",
         "MessageClass":"Event",
         "MessageCategory":"Event",
         "DeviceID":"1517998564"
      }
   }
}

Reject

{
   "SaleToPOIRequest":{
      "EventNotification":{
         "EventDetails":"newstate=IDLE&oldstate=START",
         "EventToNotify":"Reject",
         "TimeStamp":"2019-08-07T10:16:10.000Z"
      },
      "MessageHeader":{
         "SaleID":"POSSystemID12345",
         "ProtocolVersion":"3.0",
         "MessageType":"Notification",
         "POIID":"V400m-324688179",
         "MessageClass":"Event",
         "MessageCategory":"Event",
         "DeviceID":"1517998565"
      }
   }
}

SaleWakeUp

{
   "SaleToPOIRequest":{
      "EventNotification":{
         "EventDetails":"0123456789",
         "EventToNotify":"SaleWakeUp",
         "TimeStamp":"2019-11-15T10:16:10.000Z"
      },
      "MessageHeader":{
         "SaleID":"POSSystemID12345",
         "ProtocolVersion":"3.0",
         "MessageType":"Notification",
         "POIID":"V400m-324688179",
         "MessageClass":"Event",
         "MessageCategory":"Event",
         "DeviceID":"1517998561"
      }
   }
}